diff --git a/doc/administration/_index.md b/doc/administration/_index.md
index 3ae8dad85e8ae64433421488d6a60124ef2d5ff9..8f5cd24069b9fb3fb610270f79c3432ab8f90a4b 100644
--- a/doc/administration/_index.md
+++ b/doc/administration/_index.md
@@ -1,8 +1,8 @@
---
stage: Systems
group: Distribution
-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"
-description: 'Learn how to install, configure, update, and maintain your GitLab instance.'
+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
+description: Learn how to install, configure, update, and maintain your GitLab instance.
title: Administer GitLab
---
diff --git a/doc/administration/admin_area.md b/doc/administration/admin_area.md
index c72357a71fdd99d969d4dd30a4c194fb3e25e2ac..e7fea3aaed629e5d6ff52cdbdd3c39c54129a061 100644
--- a/doc/administration/admin_area.md
+++ b/doc/administration/admin_area.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Admin area
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The **Admin** area provides a web UI to manage and configure features of a
GitLab Self-Managed instance. If you are an administrator, to access the **Admin** area:
@@ -20,18 +23,28 @@ GitLab Self-Managed instance. If you are an administrator, to access the **Admin
If the GitLab instance uses Admin Mode, you must [enable Admin Mode for your session](settings/sign_in_restrictions.md#turn-on-admin-mode-for-your-session) before
the **Admin** button is visible.
-NOTE:
+{{< alert type="note" >}}
+
Only administrators on GitLab Self-Managed or GitLab Dedicated can access the **Admin** area. On GitLab.com the **Admin** area feature is not available.
+{{< /alert >}}
+
## Administering organizations
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419540) in GitLab 16.10 [with a flag](feature_flags.md) named `ui_for_organizations`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419540) in GitLab 16.10 [with a flag](feature_flags.md) named `ui_for_organizations`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](feature_flags.md) named `ui_for_organizations`.
On GitLab.com and GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
+{{< /alert >}}
+
You can administer all organizations in the GitLab instance from the **Admin** area's Organizations page.
To access the Organizations page:
@@ -94,7 +107,11 @@ You can combine the filter options. For example, to list only public projects wi
## Administering users
-> - Filtering users [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+{{< history >}}
+
+- Filtering users [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+
+{{< /history >}}
You can administer all users in the GitLab instance from the **Admin** area's Users page:
@@ -148,7 +165,11 @@ By default, impersonation is enabled. GitLab can be configured to [disable imper
### User identities
-> - The ability to see a user's SCIM identity was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294608) in GitLab 15.3.
+{{< history >}}
+
+- The ability to see a user's SCIM identity was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294608) in GitLab 15.3.
+
+{{< /history >}}
When using authentication providers, administrators can see the identities for a user:
@@ -162,9 +183,12 @@ the identities being used for an account.
### User permission export
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
An administrator can export user permissions for all active users in the GitLab instance from the **Admin** area's Users page.
The export lists direct membership the users have in groups and projects.
@@ -182,7 +206,7 @@ To do this:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
-1. On the top right, select **Export permissions as CSV** (**{export}**).
+1. On the top right, select **Export permissions as CSV** ({{< icon name="export" >}}).
### Users statistics
@@ -255,7 +279,11 @@ To [Create a new group](../user/group/_index.md#create-a-group) select **New gro
## Administering topics
-> - Merging topics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366884) in GitLab 15.5.
+{{< history >}}
+
+- Merging topics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366884) in GitLab 15.5.
+
+{{< /history >}}
You can categorize and find similar projects with [topics](../user/project/project_topics.md).
@@ -288,11 +316,14 @@ To create a topic:
The created topics are displayed on the **Explore topics** page.
-NOTE:
+{{< alert type="note" >}}
+
The assigned topics are visible only to everyone with access to the project,
but everyone can see which topics exist on the GitLab instance.
Do not include sensitive information in the name of a topic.
+{{< /alert >}}
+
### Edit a topic
You can edit a topic's name, title, description, and avatar at any time.
@@ -352,7 +383,11 @@ For each Gitaly server, the following details are listed:
### Administering runners
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/340859) from **Overview > Runners** to **CI/CD > Runners** in GitLab 15.8.
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/340859) from **Overview > Runners** to **CI/CD > Runners** in GitLab 15.8.
+
+{{< /history >}}
You can administer all runners in the GitLab instance from the **Admin** area's **Runners** page. See
[GitLab Runner](https://docs.gitlab.com/runner/) for more information.
@@ -380,8 +415,12 @@ You can also filter runners by status, type, and tag. To filter:
#### Bulk delete runners
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370241) in GitLab 15.4.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/353981) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370241) in GitLab 15.4.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/353981) in GitLab 15.5.
+
+{{< /history >}}
You can delete multiple runners at the same time.
@@ -409,7 +448,11 @@ You can also edit, pause, or remove each runner.
### Administering Jobs
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/386311) from **Overview > Jobs** to **CI/CD > Jobs** in GitLab 15.8.
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/386311) from **Overview > Jobs** to **CI/CD > Jobs** in GitLab 15.8.
+
+{{< /history >}}
You can administer all jobs in the GitLab instance from the **Admin** area's Jobs page.
@@ -440,7 +483,11 @@ The following topics document the **Monitoring** section of the **Admin** area.
### System information
-> - Support for relative time [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341248) in GitLab 15.2. "Uptime" statistic was renamed to "System started".
+{{< history >}}
+
+- Support for relative time [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341248) in GitLab 15.2. "Uptime" statistic was renamed to "System started".
+
+{{< /history >}}
The **System information** page provides the following statistics:
@@ -495,9 +542,12 @@ The content of each log file is listed in chronological order. To minimize perfo
### Audit events
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The **Audit events** page lists changes made within the GitLab server. With this information you can control, analyze, and track every change.
@@ -505,6 +555,9 @@ The **Audit events** page lists changes made within the GitLab server. With this
The **Instance overview** section of the Dashboard lists the current statistics of the GitLab instance. This information is retrieved using the [Application statistics API](../api/statistics.md#get-details-on-current-application-statistics).
-NOTE:
+{{< alert type="note" >}}
+
These statistics show exact counts for values less than 10,000. For values of 10,000 and higher, these statistics show approximate data
when [TablesampleCountStrategy](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/count/tablesample_count_strategy.rb?ref_type=heads#L16) and [ReltuplesCountStrategy](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/count/reltuples_count_strategy.rb?ref_type=heads) strategies are used for calculations.
+
+{{< /alert >}}
diff --git a/doc/administration/administer_users.md b/doc/administration/administer_users.md
index 30cf0d9172361df439da826b127266788a12dc98..fd5c7ec569fcf8ef7211186b51462977a45daee3 100644
--- a/doc/administration/administer_users.md
+++ b/doc/administration/administer_users.md
@@ -1,14 +1,17 @@
---
stage: none
group: unassigned
-description: Administer GitLab users.
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
+description: Administer GitLab users.
title: Administer users
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Administer and manage users in GitLab Self-Managed.
diff --git a/doc/administration/analytics.md b/doc/administration/analytics.md
index fbe2cb494ee1279cfba729406e29d9553c119ac2..751953d3b5035c0f753d0ef08fecca74528280dc 100644
--- a/doc/administration/analytics.md
+++ b/doc/administration/analytics.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use ClickHouse for analytics reports
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - ClickHouse data collector [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414610) in GitLab 16.3 [with a flag](feature_flags.md) named `clickhouse_data_collection`. Disabled by default.
-> - Feature flag `clickhouse_data_collection` removed in GitLab 17.0 and replaced with an application setting.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- ClickHouse data collector [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414610) in GitLab 16.3 [with a flag](feature_flags.md) named `clickhouse_data_collection`. Disabled by default.
+- Feature flag `clickhouse_data_collection` removed in GitLab 17.0 and replaced with an application setting.
+
+{{< /history >}}
The [contribution analytics](../user/group/contribution_analytics/_index.md) report and [Value Streams Dashboard](../user/analytics/value_streams_dashboard.md#dashboard-metrics-and-drill-down-reports) contributors count metric can use ClickHouse as a data source.
diff --git a/doc/administration/analytics/dev_ops_reports.md b/doc/administration/analytics/dev_ops_reports.md
index 4c580f4db4f1e58be9ac617d7a2e890d0e1f6b14..a2f90888d3bb38212b81d2ffff9692e2b2093d4b 100644
--- a/doc/administration/analytics/dev_ops_reports.md
+++ b/doc/administration/analytics/dev_ops_reports.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: DevOps adoption by instance
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
DevOps Reports give you an overview of your entire instance's adoption of
development, security, and operations features, along with a DevOps score.
@@ -16,11 +19,14 @@ For more information about this feature, see also [DevOps adoption by group](../
## DevOps score
-NOTE:
+{{< alert type="note" >}}
+
To view the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping).
DevOps Score is a comparative tool, so your score data must be centrally processed by GitLab Inc. first.
If Service Ping is not activated, the DevOps score value is 0.
+{{< /alert >}}
+
You can use the DevOps score to compare your DevOps status to other organizations.
The **DevOps Score** displays usage of major GitLab features on your instance over
@@ -69,4 +75,4 @@ To remove a group from the DevOps Reports:
- From the **Add or remove groups** dropdown list, clear the group you want to remove.
- From the **Adoption by group** table, in the row of the group you want to remove, select
-**Remove Group from the table** (**{remove}**).
+**Remove Group from the table** ({{< icon name="remove" >}}).
diff --git a/doc/administration/analytics/usage_trends.md b/doc/administration/analytics/usage_trends.md
index 31a1623892c8ead883724f292b262ceaca55b7ad..0144282579864b341e589bef886489dcbf881840 100644
--- a/doc/administration/analytics/usage_trends.md
+++ b/doc/administration/analytics/usage_trends.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Usage trends
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Usage trends give you an overview of how much data your instance contains, and how quickly this volume is changing over time.
diff --git a/doc/administration/appearance.md b/doc/administration/appearance.md
index 2a3afbb9cf00143a3aeafa0b7100a6139c05b1bd..a0c6ed82644ab918e51a150882818d165f030c34 100644
--- a/doc/administration/appearance.md
+++ b/doc/administration/appearance.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Appearance
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can update your settings to change the look and feel of your instance.
@@ -21,7 +24,7 @@ To open the **Appearance** settings:
Customize the appearance of your **Homepage** button.
The **Homepage** button is located on the upper-left corner of the left sidebar.
-Replace the default **GitLab logo** **{tanuki}** with any image.
+Replace the default **GitLab logo** {{< icon name="tanuki" >}} with any image.
- The file should be less than 1 MB.
- The image should be 24 pixels high. Images more than 24 px high will be resized.
@@ -37,7 +40,7 @@ Pipeline status emails also show your custom logo. However, some email applicati
## Customize the favicon
-Customize the appearance of the favicon. A favicon is the icon for a website that shows in your browser tabs. The **GitLab logo** **{tanuki}** is the default browser and CI/CD status favicon. Replace the default icon with any image that is `32 x 32` pixels and in `.png` or `.ico` format.
+Customize the appearance of the favicon. A favicon is the icon for a website that shows in your browser tabs. The **GitLab logo** {{< icon name="tanuki" >}} is the default browser and CI/CD status favicon. Replace the default icon with any image that is `32 x 32` pixels and in `.png` or `.ico` format.
To change the favicon:
@@ -48,7 +51,11 @@ To change the favicon:
## Add system header and footer messages
-> - **Enable header and footer in emails** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9.
+{{< history >}}
+
+- **Enable header and footer in emails** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9.
+
+{{< /history >}}
Add a small header message, a small footer message, or both, to the interface of your GitLab instance. These messages show on all projects and pages of the instance, such as the sign-in and register pages.
@@ -95,17 +102,28 @@ You can add also add a [customized help message](settings/help_page.md) below th
### Disable cookie-based language selector
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144484) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144484) in GitLab 16.10.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](feature_flags.md) named `disable_preferred_language_cookie`.
On GitLab.com and GitLab Dedicated, this feature is not available.
+{{< /alert >}}
+
You can remove the cookie-based language selector from the footer of the sign-in and register pages by enabling the `disable_preferred_language_cookie` feature flag.
## Customize the Progressive Web App
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.9.
+
+{{< /history >}}
Customize the icon, display name, short name, and description for your Progressive Web App (PWA). For more information, see [Progressive Web App](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps).
diff --git a/doc/administration/application_settings_cache.md b/doc/administration/application_settings_cache.md
index e2ca6b8756357e09de01544c5cb18943400d1405..b083fa4337d2b1dbc3ce50081fa4ef60aa94c896 100644
--- a/doc/administration/application_settings_cache.md
+++ b/doc/administration/application_settings_cache.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Application cache interval
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
By default, GitLab caches application settings for 60 seconds. Occasionally,
you may need to increase that interval to have more delay between application
@@ -21,9 +24,9 @@ extra load for Redis and PostgreSQL.
To change the expiry value:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -39,7 +42,9 @@ To change the expiry value:
gitlab-ctl restart
```
-:::TabTitle Self-compiled (Source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (Source)" >}}
1. Edit `config/gitlab.yml`:
@@ -51,4 +56,6 @@ To change the expiry value:
1. Save the file, and then [restart](restart_gitlab.md#self-compiled-installations)
GitLab for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/administration/audit_event_reports.md b/doc/administration/audit_event_reports.md
index 9a31fc71df82a2347bba38b635e27bb5295b3c7d..f24c8273010a5eb8fb4bb974a22b01af5cf70e98 100644
--- a/doc/administration/audit_event_reports.md
+++ b/doc/administration/audit_event_reports.md
@@ -10,9 +10,12 @@ features.
## Instance audit events
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can view audit events from user actions across an entire GitLab instance.
To view instance audit events:
@@ -29,11 +32,18 @@ Instance audit events can also be accessed using the [instance audit events API]
## Exporting audit events
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - Entity type `Gitlab::Audit::InstanceScope` for instance audit events [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418185) in GitLab 16.2.
+{{< history >}}
+
+- Entity type `Gitlab::Audit::InstanceScope` for instance audit events [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418185) in GitLab 16.2.
+
+{{< /history >}}
You can export the current view (including filters) of your instance audit events as a
CSV(comma-separated values) file. To export the instance audit events to CSV:
@@ -76,9 +86,12 @@ All items are sorted by `created_at` in ascending order.
## User impersonation
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When a user is [impersonated](admin_area.md#user-impersonation), their actions are logged as audit events with the following additional details:
diff --git a/doc/administration/audit_event_streaming/_index.md b/doc/administration/audit_event_streaming/_index.md
index 887cb283646d23a148fad6980faf338084f0f82a..c79147154f022781b2f664b92d518ae461a618b1 100644
--- a/doc/administration/audit_event_streaming/_index.md
+++ b/doc/administration/audit_event_streaming/_index.md
@@ -5,18 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Audit event streaming for instances
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398107) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default.
-> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2.
-> - Instance streaming destinations [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) in GitLab 16.4. [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/417708) removed.
-> - Custom HTTP headers UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361630) in GitLab 15.2 [with a flag](../feature_flags.md) named `custom_headers_streaming_audit_events_ui`. Disabled by default.
-> - Custom HTTP headers UI [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) in GitLab 15.3. [Feature flag `custom_headers_streaming_audit_events_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) removed.
-> - [Improved user experience](https://gitlab.com/gitlab-org/gitlab/-/issues/367963) in GitLab 15.3.
-> - HTTP destination **Name** field [added](https://gitlab.com/gitlab-org/gitlab/-/issues/411357) in GitLab 16.3.
-> - Functionality for the **Active** checkbox [added](https://gitlab.com/gitlab-org/gitlab/-/issues/415268) in GitLab 16.5.
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398107) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default.
+- [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2.
+- Instance streaming destinations [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) in GitLab 16.4. [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/417708) removed.
+- Custom HTTP headers UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361630) in GitLab 15.2 [with a flag](../feature_flags.md) named `custom_headers_streaming_audit_events_ui`. Disabled by default.
+- Custom HTTP headers UI [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) in GitLab 15.3. [Feature flag `custom_headers_streaming_audit_events_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) removed.
+- [Improved user experience](https://gitlab.com/gitlab-org/gitlab/-/issues/367963) in GitLab 15.3.
+- HTTP destination **Name** field [added](https://gitlab.com/gitlab-org/gitlab/-/issues/411357) in GitLab 16.3.
+- Functionality for the **Active** checkbox [added](https://gitlab.com/gitlab-org/gitlab/-/issues/415268) in GitLab 16.5.
+
+{{< /history >}}
Audit event streaming for instances, administrators can:
@@ -31,10 +38,13 @@ incoming data.
Audit events are sent using the POST request method protocol supported by HTTP.
-WARNING:
+{{< alert type="warning" >}}
+
Streaming destinations receive **all** audit event data, which could include sensitive information. Make sure you trust
the streaming destination.
+{{< /alert >}}
+
Manage streaming destinations for an entire instance.
## HTTP destinations
@@ -130,17 +140,21 @@ To delete only the custom HTTP headers for a streaming destination:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Monitoring > Audit events**.
1. On the main area, select the **Streams** tab.
-1. To the right of the item, select **Edit** (**{pencil}**).
+1. To the right of the item, select **Edit** ({{< icon name="pencil" >}}).
1. Locate the **Custom HTTP headers** table.
1. Locate the header that you wish to remove.
-1. To the right of the header, select **Delete** (**{remove}**).
+1. To the right of the header, select **Delete** ({{< icon name="remove" >}}).
1. Select **Save** to update the streaming destination.
### Verify event authenticity
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398107) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default.
-> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2.
-> - Instance streaming destinations [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) in GitLab 16.4. [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/417708) removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398107) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default.
+- [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2.
+- Instance streaming destinations [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) in GitLab 16.4. [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/417708) removed.
+
+{{< /history >}}
Each streaming destination has a unique verification token (`verificationToken`) that can be used to verify the authenticity of the event. This
token is either specified by the Owner or generated automatically when the event destination is created and cannot be changed.
@@ -161,12 +175,16 @@ To list streaming destinations for an instance and see the verification tokens:
### Update event filters
-> - Event type filtering in the UI with a defined list of audit event types [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415013) in GitLab 16.3.
+{{< history >}}
+
+- Event type filtering in the UI with a defined list of audit event types [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415013) in GitLab 16.3.
+
+{{< /history >}}
When this feature is enabled, you can permit users to filter streamed audit events per destination.
If the feature is enabled with no filters, the destination receives all audit events.
-A streaming destination that has an event type filter set has a **filtered** (**{filter}**) label.
+A streaming destination that has an event type filter set has a **filtered** ({{< icon name="filter" >}}) label.
To update a streaming destination's event filters:
@@ -190,7 +208,11 @@ To override the `content-type` header default value for an instance streaming de
## Google Cloud Logging destinations
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131851) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131851) in GitLab 16.5.
+
+{{< /history >}}
Manage Google Cloud Logging destinations for an entire instance.
@@ -269,8 +291,12 @@ To delete Google Cloud Logging streaming destinations to an instance:
## AWS S3 destinations
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138245) in GitLab 16.7 [with a flag](../feature_flags.md) named `allow_streaming_instance_audit_events_to_amazon_s3`. Disabled by default.
-> - [Feature flag `allow_streaming_instance_audit_events_to_amazon_s3`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137391) removed in GitLab 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138245) in GitLab 16.7 [with a flag](../feature_flags.md) named `allow_streaming_instance_audit_events_to_amazon_s3`. Disabled by default.
+- [Feature flag `allow_streaming_instance_audit_events_to_amazon_s3`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137391) removed in GitLab 16.8.
+
+{{< /history >}}
Manage AWS S3 destinations for entire instance.
diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md
index 397199c8e05f3916d85954de5c40e58611ae389a..a9d7253f1945ecae5dc0666f8c989104e56f033f 100644
--- a/doc/administration/auditor_users.md
+++ b/doc/administration/auditor_users.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Auditor users
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Users with auditor access have read-only access to all groups, projects, and other resources except:
@@ -28,9 +31,12 @@ Situations where auditor access for users could be helpful include:
you can create an account with auditor access and then share the credentials
with those users to which you want to grant access.
-NOTE:
+{{< alert type="note" >}}
+
An auditor user counts as a billable user and consumes a license seat.
+{{< /alert >}}
+
## Add a user with auditor access
To create a new user account with auditor access (or change an existing user):
@@ -65,7 +71,11 @@ If you are signed in with auditor access, you:
## Maintain auditor users using API
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3.
+
+{{< /history >}}
Administrators can use the GitLab API to [create](../api/users.md#create-a-user) and
[modify](../api/users.md#modify-a-user) auditor users.
diff --git a/doc/administration/auth/_index.md b/doc/administration/auth/_index.md
index f42f6ffa64b67edc8a323a6985b55f3650206dd7..376e0e8553cfb56657fdd39216cea3bfc831ac7f 100644
--- a/doc/administration/auth/_index.md
+++ b/doc/administration/auth/_index.md
@@ -1,14 +1,17 @@
---
stage: Software Supply Chain Security
group: Authentication
-description: Third-party authentication providers.
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
+description: Third-party authentication providers.
title: GitLab authentication and authorization
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab integrates with a number of [OmniAuth providers](../../integration/omniauth.md#supported-providers),
and the following external authentication and authorization providers:
@@ -19,9 +22,12 @@ and the following external authentication and authorization providers:
- [SAML for GitLab.com groups](../../user/group/saml_sso/_index.md)
- [Smart card](smartcard.md)
-NOTE:
+{{< alert type="note" >}}
+
UltraAuth has removed their software which supports OmniAuth integration. We have therefore removed all references to UltraAuth integration.
+{{< /alert >}}
+
## GitLab.com compared to GitLab Self-Managed
The external authentication and authorization providers may support the following capabilities.
diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md
index f1f4ca8a3d52aeb715d55ed7f66e00901a8785f1..69796f8ed03f2171d9d1f5a98681213e198f6563 100644
--- a/doc/administration/auth/atlassian.md
+++ b/doc/administration/auth/atlassian.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Atlassian as an OAuth 2.0 authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To enable the Atlassian OmniAuth provider for passwordless authentication you must register an application with Atlassian.
diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md
index 73dcd6a89fa37de82650e561eda7d7d15bc55c62..7bbc04fcc203f0fedf54cf63af085df96a97a00d 100644
--- a/doc/administration/auth/cognito.md
+++ b/doc/administration/auth/cognito.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use AWS Cognito as an OAuth 2.0 authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Amazon Web Services (AWS) Cognito lets you add user sign-up, sign-in, and access control to your GitLab instance.
The following documentation enables AWS Cognito as an OAuth 2.0 provider.
diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md
index 4d48b76418cb4811b1318d6fc4e345e5060db822..e044afba909138f91368f40cdd0216c9d8919b49 100644
--- a/doc/administration/auth/crowd.md
+++ b/doc/administration/auth/crowd.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Atlassian Crowd as an authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Authenticate to GitLab using the Atlassian Crowd OmniAuth provider. Enabling
this provider also allows Crowd authentication for Git-over-https requests.
diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md
index 3bc872a72728be3b1fc606d517cf19d9cd837716..4770b77aae1cebf42f1e1e7a4a004dc9a5155665 100644
--- a/doc/administration/auth/jwt.md
+++ b/doc/administration/auth/jwt.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use JWT as an authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To enable the JWT OmniAuth provider, you must register your application with JWT.
JWT provides you with a secret key for you to use.
@@ -68,13 +71,19 @@ JWT provides you with a secret key for you to use.
}
```
- NOTE:
- For more information on each configuration option refer to
+ {{< alert type="note" >}}
+
+For more information on each configuration option refer to
the [OmniAuth JWT usage documentation](https://github.com/mbleigh/omniauth-jwt#usage).
- WARNING:
+ {{< /alert >}}
+
+ {{< alert type="warning" >}}
+
Incorrectly configuring these settings can result in an insecure instance.
+ {{< /alert >}}
+
1. Change `YOUR_APP_SECRET` to the client secret and set `auth_url` to your redirect URL.
1. Save the configuration file.
1. For changes to take effect, if you:
diff --git a/doc/administration/auth/ldap/_index.md b/doc/administration/auth/ldap/_index.md
index 7b06054721e604f5854d29a5685ddda4ec8b027f..d97d6e9fb4bb1fac307692d286333472f7f71855 100644
--- a/doc/administration/auth/ldap/_index.md
+++ b/doc/administration/auth/ldap/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Integrate LDAP with GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab integrates with [LDAP - Lightweight Directory Access Protocol](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
to support user authentication.
@@ -19,9 +22,12 @@ This integration works with most LDAP-compliant directory servers, including:
- Open LDAP.
- 389 Server.
-NOTE:
+{{< alert type="note" >}}
+
GitLab does not support [Microsoft Active Directory Trusts](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)).
+{{< /alert >}}
+
Users added through LDAP:
- Usually use a [licensed seat](../../../subscriptions/self_managed/_index.md#billable-users).
@@ -112,9 +118,9 @@ To configure LDAP, you edit the settings in a configuration file:
The file you edit differs depending on your GitLab setup:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -148,7 +154,9 @@ The file you edit differs depending on your GitLab setup:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -191,7 +199,9 @@ The file you edit differs depending on your GitLab setup:
For more information, see
[how to configure LDAP for a GitLab instance that was installed by using the Helm chart](https://docs.gitlab.com/charts/charts/globals.html#ldap).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -233,7 +243,9 @@ For more information, see
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -274,7 +286,9 @@ For more information, see
For more information about the various LDAP options, see the `ldap` setting in
[`gitlab.yml.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
After configuring LDAP, to test the configuration, use the
[LDAP check Rake task](../../raketasks/ldap.md#check).
@@ -287,23 +301,23 @@ The following basic settings are available:
| Setting | Required | Type | Description |
|---------------------------------|------------------------|-------------------------------|-------------|
-| `label` | **{check-circle}** Yes | String | A human-friendly name for your LDAP server. It is displayed on your sign-in page. Example: `'Paris'` or `'Acme, Ltd.'` |
-| `host` | **{check-circle}** Yes | String | IP address or domain name of your LDAP server. Ignored when `hosts` is defined. Example: `'ldap.mydomain.com'` |
-| `port` | **{check-circle}** Yes | Integer | The port to connect with on your LDAP server. Ignored when `hosts` is defined. Example: `389` or `636` (for SSL) |
-| `uid` | **{check-circle}** Yes | String | The LDAP attribute that maps to the username that users use to sign in. Should be the attribute, not the value that maps to the `uid`. Does not affect the GitLab username (see [attributes section](#attribute-configuration-settings)). Example: `'sAMAccountName'` or `'uid'` or `'userPrincipalName'` |
-| `base` | **{check-circle}** Yes | String | Base where we can search for users. Example: `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` |
-| `encryption` | **{check-circle}** Yes | String | Encryption method (the `method` key is deprecated in favor of `encryption`). It can have one of three values: `'start_tls'`, `'simple_tls'`, or `'plain'`. `simple_tls` corresponds to 'Simple TLS' in the LDAP library. `start_tls` corresponds to StartTLS, not to be confused with regular TLS. If you specify `simple_tls`, usually it's on port 636, while `start_tls` (StartTLS) would be on port 389. `plain` also operates on port 389. |
-| `hosts` | **{dotted-circle}** No | Array of strings and integers | An array of host and port pairs to open connections. Each configured server should have an identical data set. This is not meant to configure multiple distinct LDAP servers, but to configure failover. Hosts are tried in the order they are configured. Example: `[['ldap1.mydomain.com', 636], ['ldap2.mydomain.com', 636]]` |
-| `bind_dn` | **{dotted-circle}** No | String | The full DN of the user you bind with. Example: `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` |
-| `password` | **{dotted-circle}** No | String | The password of the bind user. |
-| `verify_certificates` | **{dotted-circle}** No | Boolean | Defaults to `true`. Enables SSL certificate verification if encryption method is `start_tls` or `simple_tls`. If set to `false`, no validation of the LDAP server's SSL certificate is performed. |
-| `timeout` | **{dotted-circle}** No | Integer | Defaults to `10`. Set a timeout, in seconds, for LDAP queries. This helps avoid blocking a request if the LDAP server becomes unresponsive. A value of `0` means there is no timeout. |
-| `active_directory` | **{dotted-circle}** No | Boolean | This setting specifies if LDAP server is Active Directory LDAP server. For non-AD servers it skips the AD specific queries. If your LDAP server is not AD, set this to false. |
-| `allow_username_or_email_login` | **{dotted-circle}** No | Boolean | Defaults to `false`. If enabled, GitLab ignores everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you must disable this setting, because the userPrincipalName contains an `@`. |
-| `block_auto_created_users` | **{dotted-circle}** No | Boolean | Defaults to `false`. To maintain tight control over the number of billable users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by an administrator . |
-| `user_filter` | **{dotted-circle}** No | String | Filter LDAP users. Follows the format of [RFC 4515](https://www.rfc-editor.org/rfc/rfc4515.html). GitLab does not support `omniauth-ldap`'s custom filter syntax. Examples of the `user_filter` field syntax:<br/><br/>- `'(employeeType=developer)'`<br/>- `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` |
-| `lowercase_usernames` | **{dotted-circle}** No | Boolean | If enabled, GitLab converts the name to lower case. |
-| `retry_empty_result_with_codes` | **{dotted-circle}** No | Array | An array of LDAP query response code that attempt to retry the operation if the result/content is empty. For Google Secure LDAP, set this value to `[80]`. |
+| `label` | {{< icon name="check-circle" >}} Yes | String | A human-friendly name for your LDAP server. It is displayed on your sign-in page. Example: `'Paris'` or `'Acme, Ltd.'` |
+| `host` | {{< icon name="check-circle" >}} Yes | String | IP address or domain name of your LDAP server. Ignored when `hosts` is defined. Example: `'ldap.mydomain.com'` |
+| `port` | {{< icon name="check-circle" >}} Yes | Integer | The port to connect with on your LDAP server. Ignored when `hosts` is defined. Example: `389` or `636` (for SSL) |
+| `uid` | {{< icon name="check-circle" >}} Yes | String | The LDAP attribute that maps to the username that users use to sign in. Should be the attribute, not the value that maps to the `uid`. Does not affect the GitLab username (see [attributes section](#attribute-configuration-settings)). Example: `'sAMAccountName'` or `'uid'` or `'userPrincipalName'` |
+| `base` | {{< icon name="check-circle" >}} Yes | String | Base where we can search for users. Example: `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` |
+| `encryption` | {{< icon name="check-circle" >}} Yes | String | Encryption method (the `method` key is deprecated in favor of `encryption`). It can have one of three values: `'start_tls'`, `'simple_tls'`, or `'plain'`. `simple_tls` corresponds to 'Simple TLS' in the LDAP library. `start_tls` corresponds to StartTLS, not to be confused with regular TLS. If you specify `simple_tls`, usually it's on port 636, while `start_tls` (StartTLS) would be on port 389. `plain` also operates on port 389. |
+| `hosts` | {{< icon name="dotted-circle" >}} No | Array of strings and integers | An array of host and port pairs to open connections. Each configured server should have an identical data set. This is not meant to configure multiple distinct LDAP servers, but to configure failover. Hosts are tried in the order they are configured. Example: `[['ldap1.mydomain.com', 636], ['ldap2.mydomain.com', 636]]` |
+| `bind_dn` | {{< icon name="dotted-circle" >}} No | String | The full DN of the user you bind with. Example: `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` |
+| `password` | {{< icon name="dotted-circle" >}} No | String | The password of the bind user. |
+| `verify_certificates` | {{< icon name="dotted-circle" >}} No | Boolean | Defaults to `true`. Enables SSL certificate verification if encryption method is `start_tls` or `simple_tls`. If set to `false`, no validation of the LDAP server's SSL certificate is performed. |
+| `timeout` | {{< icon name="dotted-circle" >}} No | Integer | Defaults to `10`. Set a timeout, in seconds, for LDAP queries. This helps avoid blocking a request if the LDAP server becomes unresponsive. A value of `0` means there is no timeout. |
+| `active_directory` | {{< icon name="dotted-circle" >}} No | Boolean | This setting specifies if LDAP server is Active Directory LDAP server. For non-AD servers it skips the AD specific queries. If your LDAP server is not AD, set this to false. |
+| `allow_username_or_email_login` | {{< icon name="dotted-circle" >}} No | Boolean | Defaults to `false`. If enabled, GitLab ignores everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you must disable this setting, because the userPrincipalName contains an `@`. |
+| `block_auto_created_users` | {{< icon name="dotted-circle" >}} No | Boolean | Defaults to `false`. To maintain tight control over the number of billable users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by an administrator . |
+| `user_filter` | {{< icon name="dotted-circle" >}} No | String | Filter LDAP users. Follows the format of [RFC 4515](https://www.rfc-editor.org/rfc/rfc4515.html). GitLab does not support `omniauth-ldap`'s custom filter syntax. Examples of the `user_filter` field syntax:<br/><br/>- `'(employeeType=developer)'`<br/>- `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` |
+| `lowercase_usernames` | {{< icon name="dotted-circle" >}} No | Boolean | If enabled, GitLab converts the name to lower case. |
+| `retry_empty_result_with_codes` | {{< icon name="dotted-circle" >}} No | Array | An array of LDAP query response code that attempt to retry the operation if the result/content is empty. For Google Secure LDAP, set this value to `[80]`. |
<!-- markdownlint-enable MD056 -->
@@ -322,9 +336,9 @@ pairs. The following settings are all optional:
The examples below illustrate how to set `ca_file` and `ssl_version` in `tls_options`:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -352,7 +366,9 @@ The examples below illustrate how to set `ca_file` and `ssl_version` in `tls_opt
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -388,7 +404,9 @@ The examples below illustrate how to set `ca_file` and `ssl_version` in `tls_opt
For more information, see
[how to configure LDAP for a GitLab instance that was installed by using the Helm chart](https://docs.gitlab.com/charts/charts/globals.html#ldap).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -424,7 +442,9 @@ For more information, see
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -455,7 +475,9 @@ For more information, see
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Attribute configuration settings
@@ -480,9 +502,12 @@ you must do so in an `attributes` hash.
### LDAP sync configuration settings
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
These LDAP sync configuration settings are optional, excluding `group_base` which
required when `external_groups` is configured:
@@ -494,14 +519,20 @@ required when `external_groups` is configured:
| `external_groups` | An array of CNs of groups containing users that should be considered external. Not `cn=interns` or the full DN. | `['interns', 'contractors']` |
| `sync_ssh_keys` | The LDAP attribute containing a user's public SSH key. | `'sshPublicKey'` or false if not set |
-NOTE:
+{{< alert type="note" >}}
+
If Sidekiq is configured on a different server to the Rails server, you must add the LDAP configuration to every Sidekiq server as well for LDAP synchronisation to work.
+{{< /alert >}}
+
### Use multiple LDAP servers
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you have users on multiple LDAP servers, you can configure GitLab to use them. To add additional LDAP servers:
@@ -514,9 +545,9 @@ If you have users on multiple LDAP servers, you can configure GitLab to use them
The following example shows how to configure three LDAP servers with
minimal configuration:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -558,7 +589,9 @@ minimal configuration:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -602,7 +635,9 @@ minimal configuration:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -652,7 +687,9 @@ minimal configuration:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -697,7 +734,9 @@ minimal configuration:
For more information about the various LDAP options, see the `ldap` setting in
[`gitlab.yml.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
This example results in a sign-in page with the following tabs:
@@ -711,9 +750,9 @@ To limit all GitLab access to a subset of the LDAP users on your LDAP server, fi
configured `base`. However, to further filter users if
necessary, you can set up an LDAP user filter. The filter must comply with [RFC 4515](https://www.rfc-editor.org/rfc/rfc4515.html).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -731,7 +770,9 @@ necessary, you can set up an LDAP user filter. The filter must comply with [RFC
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -756,7 +797,9 @@ necessary, you can set up an LDAP user filter. The filter must comply with [RFC
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -782,7 +825,9 @@ necessary, you can set up an LDAP user filter. The filter must comply with [RFC
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -804,7 +849,9 @@ necessary, you can set up an LDAP user filter. The filter must comply with [RFC
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To limit access to the nested members of an Active Directory group, use the following syntax:
@@ -859,9 +906,9 @@ This can lead to several confusing issues such as creating links or namespaces w
GitLab can automatically lowercase usernames provided by the LDAP server by enabling
the configuration option `lowercase_usernames`. By default, this configuration option is `false`.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -879,7 +926,9 @@ the configuration option `lowercase_usernames`. By default, this configuration o
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -904,7 +953,9 @@ the configuration option `lowercase_usernames`. By default, this configuration o
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -930,7 +981,9 @@ the configuration option `lowercase_usernames`. By default, this configuration o
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `config/gitlab.yaml`:
@@ -952,7 +1005,9 @@ the configuration option `lowercase_usernames`. By default, this configuration o
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Disable LDAP web sign in
@@ -964,9 +1019,9 @@ checks like custom 2FA.
When LDAP web sign in is disabled, users don't see an **LDAP** tab on the sign-in page.
This does not disable using LDAP credentials for Git access.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -980,7 +1035,9 @@ This does not disable using LDAP credentials for Git access.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -1003,7 +1060,9 @@ This does not disable using LDAP credentials for Git access.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -1025,7 +1084,9 @@ This does not disable using LDAP credentials for Git access.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `config/gitlab.yaml`:
@@ -1045,7 +1106,9 @@ This does not disable using LDAP credentials for Git access.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Provide smart card authentication for GitLab
@@ -1070,9 +1133,9 @@ The supported configuration items for the encrypted file are:
- `bind_dn`
- `password`
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. If initially your LDAP configuration in `/etc/gitlab/gitlab.rb` looked like:
@@ -1106,12 +1169,16 @@ The supported configuration items for the encrypted file are:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the LDAP password. For more information,
read about [Helm LDAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#ldap-password).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. If initially your LDAP configuration in `docker-compose.yml` looked like:
@@ -1154,7 +1221,9 @@ read about [Helm LDAP secrets](https://docs.gitlab.com/charts/installation/secre
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. If initially your LDAP configuration in `/home/git/gitlab/config/gitlab.yml` looked like:
@@ -1192,7 +1261,9 @@ read about [Helm LDAP secrets](https://docs.gitlab.com/charts/installation/secre
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Updating LDAP DN and email
diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md
index 27d582e37aa732e3e96f121357936670fb71341b..81a81d58b817446568414e6db7b72e5757e4f806 100644
--- a/doc/administration/auth/ldap/google_secure_ldap.md
+++ b/doc/administration/auth/ldap/google_secure_ldap.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Google Secure LDAP
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
[Google Cloud Identity](https://cloud.google.com/identity/) provides a Secure
LDAP service that can be configured with GitLab for authentication and group sync.
@@ -36,10 +39,13 @@ Secure LDAP is only available on specific Google Workspace editions. For more in
`Entire domain (GitLab)` or `Selected organizational units` for both **Verify user
credentials** and **Read user information**. Select **Add LDAP Client**.
- NOTE:
- If you plan to use GitLab [LDAP Group Sync](ldap_synchronization.md#group-sync)
+ {{< alert type="note" >}}
+
+If you plan to use GitLab [LDAP Group Sync](ldap_synchronization.md#group-sync)
, turn on `Read group information`.
+ {{< /alert >}}
+
1. Download the generated certificate. This is required for GitLab to
diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md
index 9042a2f4927f5c9c95bfdee638afa8b726e7e0ce..ce9a40147b3b92ef4a313c08e64fed2e8974e217 100644
--- a/doc/administration/auth/ldap/ldap-troubleshooting.md
+++ b/doc/administration/auth/ldap/ldap-troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting LDAP
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you are an administrator, use the following information to troubleshoot LDAP.
@@ -58,9 +61,12 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server
#### Query LDAP
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following allows you to perform a search in LDAP using the rails console.
Depending on what you're trying to do, it may make more sense to query [a user](#query-a-user-in-ldap)
@@ -155,7 +161,11 @@ investigate further.
#### Users see an error "Invalid login or password."
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438144) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438144) in GitLab 16.10.
+
+{{< /history >}}
If users see this error, it might be because they are trying to sign in using the **Standard** sign-in form instead of the **LDAP** sign-in form.
@@ -265,9 +275,12 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt -b "$ba
#### Sync all users
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The output from a manual [user sync](ldap_synchronization.md#user-sync) can show you what happens when
GitLab tries to sync its users against LDAP. Enter the [rails console](#rails-console)
@@ -283,9 +296,12 @@ Next, [learn how to read the output](#example-console-output-after-a-user-sync).
##### Example console output after a user sync
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The output from a [manual user sync](#sync-all-users) is very verbose, and a
single user's successful sync can look like this:
@@ -378,9 +394,12 @@ Gitlab::Auth::Ldap::Person.find_by_uid('<uid>', adapter)
### Group memberships
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
#### Memberships not granted
@@ -503,10 +522,13 @@ that the GitLab node can connect to LDAP.
#### Sync all groups
-NOTE:
+{{< alert type="note" >}}
+
To sync all groups manually when debugging is unnecessary,
[use the Rake task](../../raketasks/ldap.md#run-a-group-sync) instead.
+{{< /alert >}}
+
The output from a manual [group sync](ldap_synchronization.md#group-sync) can show you what happens
when GitLab syncs its LDAP group memberships against LDAP. Enter the [rails console](#rails-console)
and then run:
@@ -554,10 +576,13 @@ and more DNs may be added, or existing entries modified, based on additional
LDAP group lookups. The very last occurrence of this entry should indicate
exactly which users GitLab believes should be added to the group.
-NOTE:
+{{< alert type="note" >}}
+
10 is `Guest`, 20 is `Reporter`, 30 is `Developer`, 40 is `Maintainer`
and 50 is `Owner`.
+{{< /alert >}}
+
```shell
Resolved 'my_group' group member access: {"uid=john0,ou=people,dc=example,dc=com"=>30,
"uid=mary0,ou=people,dc=example,dc=com"=>30, "uid=john1,ou=people,dc=example,dc=com"=>30,
@@ -667,10 +692,13 @@ at least either:
The following script updates the emails for all provided users so they aren't blocked or unable to access their accounts.
-NOTE:
+{{< alert type="note" >}}
+
The following script requires that any new accounts with the new
email address are removed first. Email addresses must be unique in GitLab.
+{{< /alert >}}
+
Go to the [rails console](#rails-console) and then run:
```ruby
@@ -746,9 +774,12 @@ You can solve this error in two ways.
This solution is suitable when the LDAP servers are replicas of each other, and the affected users should be able to sign in using a configured LDAP server.
For example, if a load balancer is now used to manage LDAP high availability and a separate secondary sign-in option is no longer needed.
-NOTE:
+{{< alert type="note" >}}
+
If the LDAP servers aren't replicas of each other, this solution stops affected users from being able to sign in.
+{{< /alert >}}
+
To [rename references to the LDAP server](../../raketasks/ldap.md#other-options) that is no longer configured, run:
```shell
@@ -941,10 +972,13 @@ adfind -h ad.example.org:636 -ssl -u "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -u
### Rails console
-WARNING:
+{{< alert type="warning" >}}
+
It is very easy to create, read, modify, and destroy data with the rails
console. Be sure to run commands exactly as listed.
+{{< /alert >}}
+
The rails console is a valuable tool to help debug LDAP problems. It allows you to
directly interact with the application by running commands and seeing how GitLab
responds to them.
diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md
index a3074537a972c35880e3b2a4d14965ddcc0c44b5..4591ce6ef1e08c6ec1d6138816553c3178caebb0 100644
--- a/doc/administration/auth/ldap/ldap_synchronization.md
+++ b/doc/administration/auth/ldap/ldap_synchronization.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: LDAP synchronization
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you have [configured LDAP to work with GitLab](_index.md), GitLab can automatically synchronize
users and groups.
@@ -36,7 +39,11 @@ You must consider your LDAP server's rate limits when configuring LDAP synchroni
## User sync
-> - Preventing LDAP user's profile name synchronization [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11336) in GitLab 15.11.
+{{< history >}}
+
+- Preventing LDAP user's profile name synchronization [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11336) in GitLab 15.11.
+
+{{< /history >}}
Once per day, GitLab runs a worker to check and update GitLab
users against LDAP.
@@ -66,18 +73,21 @@ The process also updates the following user information:
- SSH public keys if `sync_ssh_keys` is set.
- Kerberos identity if Kerberos is enabled.
-NOTE:
+{{< alert type="note" >}}
+
If your LDAP server has a rate limit, that limit might be reached during the user sync process. Check the [rate limit documentation](#ldap-servers-with-rate-limits) for more information.
+{{< /alert >}}
+
### Synchronize LDAP user's profile name
By default, GitLab synchronizes the LDAP user's profile name field.
To prevent this synchronization, you can set `sync_name` to `false`.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -95,7 +105,9 @@ To prevent this synchronization, you can set `sync_name` to `false`.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -120,7 +132,9 @@ To prevent this synchronization, you can set `sync_name` to `false`.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -143,7 +157,9 @@ To prevent this synchronization, you can set `sync_name` to `false`.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -165,7 +181,9 @@ To prevent this synchronization, you can set `sync_name` to `false`.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Blocked users
@@ -183,10 +201,13 @@ A blocked user is unblocked when they sign in with LDAP if all of the following
**All users** are blocked if the LDAP server is unavailable when an LDAP user synchronization is run.
-NOTE:
+{{< alert type="note" >}}
+
If all users are blocked due to the LDAP server not being available when an LDAP user synchronization is run,
a subsequent LDAP user synchronization does not automatically unblock those users.
+{{< /alert >}}
+
## Group sync
If your LDAP supports the `memberof` property, when the user signs in for the
@@ -204,12 +225,15 @@ be available to GitLab. For example, `group_base` could be
`ou=groups,dc=example,dc=com`. In the configuration file, it looks like the
following.
-NOTE:
+{{< alert type="note" >}}
+
If your LDAP server has a rate limit, that limit might be reached during the group sync process. Check the [rate limit documentation](#ldap-servers-with-rate-limits) for more information.
-::Tabs
+{{< /alert >}}
+
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -227,7 +251,9 @@ If your LDAP server has a rate limit, that limit might be reached during the gro
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -252,7 +278,9 @@ If your LDAP server has a rate limit, that limit might be reached during the gro
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -275,7 +303,9 @@ If your LDAP server has a rate limit, that limit might be reached during the gro
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -297,15 +327,20 @@ If your LDAP server has a rate limit, that limit might be reached during the gro
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To take advantage of group sync, group Owners or users with the [Maintainer role](../../../user/permissions.md) must
[create one or more LDAP group links](../../../user/group/access_and_permissions.md#manage-group-memberships-with-ldap).
-NOTE:
+{{< alert type="note" >}}
+
If you frequently experience connection issues between your LDAP server and GitLab instance, try reducing the frequency with which GitLab performs an LDAP group sync by
[setting the group sync worker interval](#adjust-ldap-group-sync-schedule) to be greater than the 1 hour default.
+{{< /alert >}}
+
### Add group links
For information on adding group links by using CNs and filters, refer to the
@@ -318,16 +353,19 @@ administrators. Specify a group CN for `admin_group` and all members of the
LDAP group are given administrator privileges. The configuration looks
like the following.
-NOTE:
+{{< alert type="note" >}}
+
Administrators are not synced unless `group_base` is also
specified alongside `admin_group`. Also, only specify the CN of the `admin_group`,
as opposed to the full DN.
Additionally, if an LDAP user has an `admin` role, but is not a member of the `admin_group`
group, GitLab revokes their `admin` role when syncing.
-::Tabs
+{{< /alert >}}
-:::TabTitle Linux package (Omnibus)
+{{< tabs >}}
+
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -346,7 +384,9 @@ group, GitLab revokes their `admin` role when syncing.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -372,7 +412,9 @@ group, GitLab revokes their `admin` role when syncing.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -396,7 +438,9 @@ group, GitLab revokes their `admin` role when syncing.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -419,7 +463,9 @@ group, GitLab revokes their `admin` role when syncing.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Global group memberships lock
@@ -466,9 +512,9 @@ to these groups as [external users](../../external_users.md).
Group membership is checked periodically through the `LdapGroupSync` background
task.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -486,7 +532,9 @@ task.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -511,7 +559,9 @@ task.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -534,7 +584,9 @@ task.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -556,7 +608,9 @@ task.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### GitLab Duo add-on for groups
@@ -564,9 +618,9 @@ The `duo_add_on_groups` setting automatically [manages Duo add-on seats](../../d
To enable add-on seat management for groups, you must configure the `duo_add_on_groups` setting in your GitLab instance:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -584,7 +638,9 @@ To enable add-on seat management for groups, you must configure the `duo_add_on_
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -609,7 +665,9 @@ To enable add-on seat management for groups, you must configure the `duo_add_on_
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -632,7 +690,9 @@ To enable add-on seat management for groups, you must configure the `duo_add_on_
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -654,7 +714,9 @@ To enable add-on seat management for groups, you must configure the `duo_add_on_
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Group sync technical details
@@ -731,18 +793,21 @@ network and LDAP server response time affects these metrics.
By default, GitLab runs a worker once per day at 01:30 a.m. server time to
check and update GitLab users against LDAP.
-WARNING:
+{{< alert type="warning" >}}
+
Do not run the sync process too frequently as this could lead to multiple syncs running concurrently. Most installations do not need to modify the sync schedule. For more information, see the [LDAP Security documentation](_index.md#security).
+{{< /alert >}}
+
You can manually configure LDAP user sync times by setting the
following configuration values, in cron format. If needed, you can
use a [crontab generator](http://www.crontabgenerator.com).
The example below shows how to set LDAP user
sync to run once every 12 hours at the top of the hour.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -756,7 +821,9 @@ sync to run once every 12 hours at the top of the hour.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -780,7 +847,9 @@ sync to run once every 12 hours at the top of the hour.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -799,7 +868,9 @@ sync to run once every 12 hours at the top of the hour.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -820,7 +891,9 @@ sync to run once every 12 hours at the top of the hour.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Adjust LDAP group sync schedule
@@ -828,16 +901,19 @@ By default, GitLab runs a group sync process every hour, on the hour.
The values shown are in cron format. If needed, you can use a
[Crontab Generator](http://www.crontabgenerator.com).
-WARNING:
+{{< alert type="warning" >}}
+
Do not start the sync process too frequently as this could lead to multiple syncs running concurrently. Most installations do not need to modify the sync schedule.
+{{< /alert >}}
+
You can manually configure LDAP group sync times by setting the
following configuration values. The example below shows how to set group
sync to run once every two hours at the top of the hour.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -851,7 +927,9 @@ sync to run once every two hours at the top of the hour.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -875,7 +953,9 @@ sync to run once every two hours at the top of the hour.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -894,7 +974,9 @@ sync to run once every two hours at the top of the hour.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -915,7 +997,9 @@ sync to run once every two hours at the top of the hour.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Troubleshooting
diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md
index abc34b4efe4246609c7aace4e2aaa2a739ef8d1d..e2733a8909e0220037800d109161f74b30a3f279 100644
--- a/doc/administration/auth/oidc.md
+++ b/doc/administration/auth/oidc.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use OpenID Connect as an authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can use GitLab as a client application with [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html)
as an OmniAuth provider.
@@ -107,8 +110,11 @@ The OpenID Connect provider provides you with a client's details and secret for
}
```
- NOTE:
- For more information on using multiple identity providers with OIDC, see [issue 5992](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5992).
+ {{< alert type="note" >}}
+
+For more information on using multiple identity providers with OIDC, see [issue 5992](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5992).
+
+ {{< /alert >}}
For self-compiled installations:
@@ -135,8 +141,11 @@ The OpenID Connect provider provides you with a client's details and secret for
}
```
- NOTE:
- For more information on each configuration option, refer to the [OmniAuth OpenID Connect usage documentation](https://github.com/omniauth/omniauth_openid_connect#usage) and [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html).
+ {{< alert type="note" >}}
+
+For more information on each configuration option, refer to the [OmniAuth OpenID Connect usage documentation](https://github.com/omniauth/omniauth_openid_connect#usage) and [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html).
+
+ {{< /alert >}}
1. For the provider configuration, change the values for the provider to match your
OpenID Connect client setup. Use the following as a guide:
@@ -242,9 +251,12 @@ you need the following information:
[Microsoft Quickstart Register an Application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) documentation
to obtain the tenant ID, client ID, and client secret for your app.
-NOTE:
+{{< alert type="note" >}}
+
All accounts provisioned by Azure must have an email address defined. If an email address is not defined, Azure assigns a randomly generated address. If you've configured [domain sign-up restrictions](../settings/sign_up_restrictions.md#allow-or-deny-sign-ups-using-specific-email-domains), this random address might prevent the account from being created.
+{{< /alert >}}
+
Example configuration block for Linux package installations:
```ruby
@@ -341,9 +353,9 @@ To migrate to the Generic OpenID Connect configuration, you must update the conf
For Linux package installations, update the configuration as follows:
-::Tabs
+{{< tabs >}}
-:::TabTitle Azure OAuth 2.0
+{{< tab title="Azure OAuth 2.0" >}}
```ruby
gitlab_rails['omniauth_providers'] = [
@@ -370,7 +382,9 @@ gitlab_rails['omniauth_providers'] = [
]
```
-:::TabTitle Azure Active Directory v2
+{{< /tab >}}
+
+{{< tab title="Azure Active Directory v2" >}}
```ruby
gitlab_rails['omniauth_providers'] = [
@@ -397,15 +411,17 @@ gitlab_rails['omniauth_providers'] = [
]
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
For Helm installations:
Add the [provider's configuration](https://docs.gitlab.com/charts/charts/globals.html#providers) in a YAML file (for example, `provider.yaml`):
-::Tabs
+{{< tabs >}}
-:::TabTitle Azure OAuth 2.0
+{{< tab title="Azure OAuth 2.0" >}}
```ruby
{
@@ -433,7 +449,9 @@ Add the [provider's configuration](https://docs.gitlab.com/charts/charts/globals
}
```
-:::TabTitle Azure Active Directory v2
+{{< /tab >}}
+
+{{< tab title="Azure Active Directory v2" >}}
```ruby
{
@@ -461,7 +479,9 @@ Add the [provider's configuration](https://docs.gitlab.com/charts/charts/globals
}
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
As you migrate from `azure_oauth2` to `omniauth_openid_connect` as part of upgrading to GitLab 17.0 or above, the `sub` claim value set for your organization can vary. `azure_oauth2` uses Microsoft V1 endpoint while `azure_activedirectory_v2` and `omniauth_openid_connect` both use Microsoft V2 endpoint with a common `sub` value.
@@ -477,9 +497,12 @@ As you migrate from `azure_oauth2` to `omniauth_openid_connect` as part of upgra
- Update `extern_uid` manually. To do this, use the [API or Rails console](../../integration/omniauth.md#change-apps-or-configuration) to update the `extern_uid` for each user.
This method may be required if the instance has already been upgraded to 17.0 or later, and users have attempted to sign in.
-NOTE:
+{{< alert type="note" >}}
+
`azure_oauth2` might have used Entra ID's `upn` claim as the email address, if the `email` claim was missing or blank when provisioning GitLab accounts.
+{{< /alert >}}
+
### Configure Microsoft Azure Active Directory B2C
GitLab requires special
@@ -672,10 +695,13 @@ gitlab_rails['omniauth_providers'] = [
#### Configure Keycloak with a symmetric key algorithm
-WARNING:
+{{< alert type="warning" >}}
+
The following instructions are included for completeness, but only use symmetric key
encryption if absolutely necessary.
+{{< /alert >}}
+
To use symmetric key encryption:
1. Extract the secret key from the Keycloak database. Keycloak does not expose this
@@ -959,11 +985,18 @@ For more information, see the [GitLab API user method documentation](https://pyt
## Configure users based on OIDC group membership
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209898) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209898) in GitLab 15.10.
+
+{{< /history >}}
You can configure OIDC group membership to:
@@ -985,9 +1018,9 @@ response to require users to be members of a certain group, configure GitLab to
If you do not set `required_groups` or leave the setting empty, any user authenticated by the IdP through OIDC can use GitLab.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1021,7 +1054,9 @@ If you do not set `required_groups` or leave the setting empty, any user authent
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1055,7 +1090,9 @@ If you do not set `required_groups` or leave the setting empty, any user authent
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### External groups
@@ -1068,9 +1105,9 @@ based on group membership, configure GitLab to identify:
[external user](../external_users.md), using the
`external_groups` setting.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1104,7 +1141,9 @@ based on group membership, configure GitLab to identify:
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1138,13 +1177,18 @@ based on group membership, configure GitLab to identify:
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Auditor groups
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Your IdP must pass group information to GitLab in the OIDC response. To use this
response to assign users as auditors based on group membership, configure GitLab to identify:
@@ -1153,9 +1197,9 @@ response to assign users as auditors based on group membership, configure GitLab
- Which group memberships grant the user auditor access, using the `auditor_groups`
setting.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1189,7 +1233,9 @@ response to assign users as auditors based on group membership, configure GitLab
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1223,7 +1269,9 @@ response to assign users as auditors based on group membership, configure GitLab
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Administrator groups
@@ -1234,9 +1282,9 @@ response to assign users as administrator based on group membership, configure G
- Which group memberships grant the user administrator access, using the
`admin_groups` setting.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1270,7 +1318,9 @@ response to assign users as administrator based on group membership, configure G
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1304,23 +1354,32 @@ response to assign users as administrator based on group membership, configure G
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure a custom duration for ID Tokens
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377654) in GitLab 17.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377654) in GitLab 17.8.
+
+{{< /history >}}
By default, GitLab ID tokens expire after 120 seconds.
To configure a custom duration for your ID tokens:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1330,7 +1389,9 @@ To configure a custom duration for your ID tokens:
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1343,7 +1404,9 @@ To configure a custom duration for your ID tokens:
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Troubleshooting
diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md
index 749e6f05d7029158283c724fad94b314c7d5d2bd..4006c1780ea177e93de322edaf0c0633d7f2bd4e 100644
--- a/doc/administration/auth/smartcard.md
+++ b/doc/administration/auth/smartcard.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Smart card authentication
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab supports authentication using smart cards.
@@ -28,8 +31,11 @@ GitLab supports two authentication methods:
### Authentication against a local database with X.509 certificates
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
Smart cards with X.509 certificates can be used to authenticate with GitLab.
@@ -52,8 +58,11 @@ Certificate:
### Authentication against a local database with X.509 certificates and SAN extension
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
Smart cards with X.509 certificates using SAN extensions can be used to authenticate
with GitLab.
@@ -91,8 +100,11 @@ Certificate:
### Authentication against an LDAP server
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
GitLab implements a standard way of certificate matching following
[RFC4523](https://www.rfc-editor.org/rfc/rfc4523). It uses the
@@ -104,7 +116,11 @@ attribute. As a prerequisite, you must use an LDAP server that:
### Authentication against an Active Directory LDAP server
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328074) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328074) in GitLab 16.9.
+
+{{< /history >}}
Active Directory does not support the `certificateExactMatch` rule or the `userCertificate` attribute. Most tools for certificate-based authentication such as smart cards use the `altSecurityIdentities` attribute, which can contain multiple certificates for each user. The data in the field must match [one of the formats Microsoft recommends](https://learn.microsoft.com/en-us/entra/identity/authentication/concept-certificate-based-authentication-certificateuserids#supported-patterns-for-certificate-user-ids).
@@ -124,12 +140,19 @@ Use the following attributes to customize the field GitLab checks and the format
For `issuer_and_serial_number`, the `<SR>` portion is in reverse-byte-order, with the least-significant byte first. For more information, see [how to map a user to a certificate using the altSecurityIdentities attribute](https://learn.microsoft.com/en-us/archive/blogs/spatdsg/howto-map-a-user-to-a-certificate-via-all-the-methods-available-in-the-altsecurityidentities-attribute).
-NOTE:
+{{< alert type="note" >}}
+
If no `smartcard_ad_cert_format` is specified, but an LDAP server is configured with `active_directory: true` and smart cards enabled, GitLab defaults to the behavior of 16.8 and earlier, and uses `certificateExactMatch` on the `userCertificate` attribute.
+{{< /alert >}}
+
### Authentication against Entra ID Domain Services
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328074) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328074) in GitLab 16.9.
+
+{{< /history >}}
[Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis), formerly known as Azure Active Directory, provides a cloud-based directory for companies and organizations. [Entra Domain Services](https://learn.microsoft.com/en-us/entra/identity/domain-services/overview) provides a secure read-only LDAP interface to the directory, but only exposes a limited subset of the fields Entra ID has.
@@ -160,11 +183,14 @@ For Linux package installations:
gitlab_rails['smartcard_client_certificate_required_port'] = 3444
```
- NOTE:
- Assign a value to at least one of the following variables:
+ {{< alert type="note" >}}
+
+Assign a value to at least one of the following variables:
`gitlab_rails['smartcard_client_certificate_required_host']` or
`gitlab_rails['smartcard_client_certificate_required_port']`.
+ {{< /alert >}}
+
1. Save the file and [reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation)
GitLab for the changes to take effect.
@@ -254,10 +280,13 @@ For self-compiled installations:
client_certificate_required_port: 3443
```
- NOTE:
- Assign a value to at least one of the following variables:
+ {{< alert type="note" >}}
+
+Assign a value to at least one of the following variables:
`client_certificate_required_host` or `client_certificate_required_port`.
+ {{< /alert >}}
+
1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations)
GitLab for the changes to take effect.
diff --git a/doc/administration/auth/test_oidc_oauth.md b/doc/administration/auth/test_oidc_oauth.md
index 769e885bb3ae75c16f86d6cf1e16090bf6840ba5..e27212c75db618ba6cfffa1f1a1ee70e513d5f8a 100644
--- a/doc/administration/auth/test_oidc_oauth.md
+++ b/doc/administration/auth/test_oidc_oauth.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Test OIDC/OAuth in GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To test OIDC/OAuth in GitLab, you must:
diff --git a/doc/administration/backup_restore/_index.md b/doc/administration/backup_restore/_index.md
index 625500f3c462835a0e935c0f4cdb28e8714de020..8f82a24c845fe0d7b4b3c7be14f80a31a09f10f7 100644
--- a/doc/administration/backup_restore/_index.md
+++ b/doc/administration/backup_restore/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Back up and restore overview
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Your GitLab instance contains critical data for your software development or organization.
It is important to have a disaster recovery plan that includes regular backups for:
@@ -19,10 +22,13 @@ It is important to have a disaster recovery plan that includes regular backups f
- **Migration**: Facilitate moving GitLab to new servers or environments.
- **Testing and development**: Create copies for testing upgrades or new features without risk to production data.
-NOTE:
+{{< alert type="note" >}}
+
This documentation applies to GitLab Community and Enterprise Edition.
While data security is ensured for GitLab.com, you can't use these methods to export or back up your data from GitLab.com.
+{{< /alert >}}
+
## Back up GitLab
The procedures to back up your GitLab instance vary based on your
diff --git a/doc/administration/backup_restore/backup_archive_process.md b/doc/administration/backup_restore/backup_archive_process.md
index 631d221084e77f3d5be16a3dee7d8dae2e3e25db..8eea7f88e2828a4857fd8882bdee2e71c7e5494d 100644
--- a/doc/administration/backup_restore/backup_archive_process.md
+++ b/doc/administration/backup_restore/backup_archive_process.md
@@ -144,10 +144,13 @@ Because backups are created from live instances, files might be modified during
In this case, an [alternate strategy](backup_gitlab.md#backup-strategy-option) can be used to back up files. The `rsync` utility creates a copy of the
files to back up and passes them to `tar` for archiving.
-NOTE:
+{{< alert type="note" >}}
+
If you are using this strategy, the machine running the backup Rake task must have
sufficient storage for both the copied files and the compressed archive.
+{{< /alert >}}
+
## Backup ID
Backup IDs are unique identifiers for backup archives. These IDs are crucial when you need to restore
diff --git a/doc/administration/backup_restore/backup_cli.md b/doc/administration/backup_restore/backup_cli.md
index 0330ab7c7eda098eb1d8e5728d90e78893ff8694..2d0b752e5c5cb42c1590fff51ae0d5b8dca134bf 100644
--- a/doc/administration/backup_restore/backup_cli.md
+++ b/doc/administration/backup_restore/backup_cli.md
@@ -2,16 +2,22 @@
stage: Systems
group: Geo
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
-ignore_in_report: true
title: Back up and Restore GitLab with `gitlab-backup-cli`
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11908) in GitLab 17.0. This feature is an [experiment](../../policy/development_stages_support.md) and subject to the [GitLab Testing Agreement](https://handbook.gitlab.com/handbook/legal/testing-agreement/).
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11908) in GitLab 17.0. This feature is an [experiment](../../policy/development_stages_support.md) and subject to the [GitLab Testing Agreement](https://handbook.gitlab.com/handbook/legal/testing-agreement/).
+
+{{< /history >}}
This tool is under development and is ultimately meant to replace [the Rake tasks used for backing up and restoring GitLab](backup_gitlab.md). You can follow the development of this tool in the epic: [Next Gen Scalable Backup and Restore](https://gitlab.com/groups/gitlab-org/-/epics/11577).
@@ -130,7 +136,11 @@ For example, if the backup directory name is `1714053314_2024_04_25_17.0.0-pre`,
## Backup metadata file (`backup_information.json`)
-> - Metadata version 2 was introduced in [GitLab 16.11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149441).
+{{< history >}}
+
+- Metadata version 2 was introduced in [GitLab 16.11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149441).
+
+{{< /history >}}
`backup_information.json` is found in the backup directory, and it stores metadata about the backup. For example:
@@ -145,7 +155,11 @@ For example, if the backup directory name is `1714053314_2024_04_25_17.0.0-pre`,
## Restore a backup
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/469247) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/469247) in GitLab 17.6.
+
+{{< /history >}}
Prerequisites:
diff --git a/doc/administration/backup_restore/backup_gitlab.md b/doc/administration/backup_restore/backup_gitlab.md
index 70cf48ab7cb9605f380720a807b8d813d7d1ead5..32939492df9e5bf91cca233b990177ae2235e953 100644
--- a/doc/administration/backup_restore/backup_gitlab.md
+++ b/doc/administration/backup_restore/backup_gitlab.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Back up GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The exact procedure for backing up GitLab depends on many factors. Your particular deployment's usage and configuration determine what kind of data exists, where it is located, and how much there is. These factors influence your options for how to perform a backup, how to store it, and how to restore it.
@@ -107,40 +110,53 @@ The backup command does not back up registry data when they are stored in Object
### Storing configuration files
-WARNING:
+{{< alert type="warning" >}}
+
The backup Rake task GitLab provides does _not_ store your configuration files. The primary reason for this is that your database contains items including encrypted information for two-factor authentication and the CI/CD _secure variables_. Storing encrypted information in the same location as its key defeats the purpose of using encryption in the first place. For example, the secrets file contains your database encryption key. If you lose it, then the GitLab application will not be able to decrypt any encrypted values in the database.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The secrets file may change after upgrades.
+{{< /alert >}}
You should back up the configuration directory. At the very **minimum**, you must back up:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package
+{{< tab title="Linux package" >}}
- `/etc/gitlab/gitlab-secrets.json`
- `/etc/gitlab/gitlab.rb`
For more information, see [Backup and restore Linux package (Omnibus) configuration](https://docs.gitlab.com/omnibus/settings/backups.html#backup-and-restore-omnibus-gitlab-configuration).
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
- `/home/git/gitlab/config/secrets.yml`
- `/home/git/gitlab/config/gitlab.yml`
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
- Back up the volume where the configuration files are stored. If you created
the GitLab container according to the documentation, it should be in the
`/srv/gitlab/config` directory.
-:::TabTitle GitLab Helm chart
+{{< /tab >}}
+
+{{< tab title="GitLab Helm chart" >}}
- Follow the [Back up the secrets](https://docs.gitlab.com/charts/backup-restore/backup.html#back-up-the-secrets)
instructions.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
You may also want to back up any TLS keys and certificates (`/etc/gitlab/ssl`, `/etc/gitlab/trusted-certs`), and your
[SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079)
@@ -184,10 +200,13 @@ Backups do not include:
- [Global server hooks](../server_hooks.md#create-global-server-hooks-for-all-repositories)
- [File hooks](../file_hooks.md)
-WARNING:
+{{< alert type="warning" >}}
+
GitLab does not back up any configuration files (`/etc/gitlab`), TLS keys and certificates, or system
files. You are highly advised to read about [storing configuration files](#storing-configuration-files).
+{{< /alert >}}
+
### Requirements
To be able to back up and restore, ensure that Rsync is installed on your
@@ -206,35 +225,49 @@ system. If you installed GitLab:
### Backup command
-WARNING:
+{{< alert type="warning" >}}
+
The backup command does not back up items in [object storage](#object-storage) on Linux package (Omnibus) / Docker / Self-compiled installations.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The backup command requires [additional parameters](#back-up-and-restore-for-installations-using-pgbouncer) when
your installation is using PgBouncer, for either performance reasons or when using it with a Patroni cluster.
+{{< /alert >}}
+
+{{< alert type="warning" >}}
-WARNING:
Before GitLab 15.5.0, the backup command doesn't verify if another backup is already running, as described in
[issue 362593](https://gitlab.com/gitlab-org/gitlab/-/issues/362593). We strongly recommend
you make sure that all backups are complete before starting a new one.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
You can only restore a backup to **exactly the same version and type (CE/EE)**
of GitLab on which it was created.
-::Tabs
+{{< /alert >}}
+
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-backup create
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Run the backup task by using `kubectl` to run the `backup-utility` script on the GitLab toolbox pod. For more details, see the [charts backup documentation](https://docs.gitlab.com/charts/backup-restore/backup.html).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
Run the backup from the host.
@@ -242,13 +275,17 @@ Run the backup from the host.
docker exec -t <container name> gitlab-backup create
```
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
```shell
sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
If your GitLab deployment has multiple nodes, you need to pick a node for running the backup command. You must ensure that the designated node:
@@ -317,10 +354,13 @@ sudo gitlab-backup create STRATEGY=copy
#### Backup filename
-WARNING:
+{{< alert type="warning" >}}
+
If you use a custom backup filename, you can't
[limit the lifetime of the backups](#limit-backup-lifetime-for-local-files-prune-old-backups).
+{{< /alert >}}
+
Backup files are created with filenames according to [specific defaults](backup_archive_process.md#backup-id). However, you can
override the `<backup-id>` portion of the filename by setting the `BACKUP`
environment variable. For example:
@@ -386,12 +426,18 @@ DECOMPRESS_CMD=tee gitlab-backup restore
##### Parallel compression with `pigz`
-WARNING:
+{{< alert type="warning" >}}
+
While we support using `COMPRESS_CMD` and `DECOMPRESS_CMD` to override the default Gzip compression library, we only test the default Gzip library with default options on a routine basis. You are responsible for testing and validating the viability of your backups. We strongly recommend this as best practice in general for backups, whether overriding the compression command or not. If you encounter issues with another compression library, you should revert back to the default. Troubleshooting and fixing errors with alternative libraries are a lower priority for GitLab.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
`pigz` is not included in the GitLab Linux package. You must install it yourself.
+{{< /alert >}}
+
An example of compressing backups with `pigz` using 4 processes:
```shell
@@ -406,12 +452,18 @@ DECOMPRESS_CMD="pigz --decompress --stdout" sudo gitlab-backup restore
##### Parallel compression with `zstd`
-WARNING:
+{{< alert type="warning" >}}
+
While we support using `COMPRESS_CMD` and `DECOMPRESS_CMD` to override the default Gzip compression library, we only test the default Gzip library with default options on a routine basis. You are responsible for testing and validating the viability of your backups. We strongly recommend this as best practice in general for backups, whether overriding the compression command or not. If you encounter issues with another compression library, you should revert back to the default. Troubleshooting and fixing errors with alternative libraries are a lower priority for GitLab.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
`zstd` is not included in the GitLab Linux package. You must install it yourself.
+{{< /alert >}}
+
An example of compressing backups with `zstd` using 4 threads:
```shell
@@ -442,9 +494,9 @@ sudo gitlab-backup create BACKUP=dump GZIP_RSYNCABLE=yes
Depending on your installation type, slightly different components can be skipped on backup creation.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus) / Docker / Self-compiled
+{{< tab title="Linux package (Omnibus) / Docker / Self-compiled" >}}
<!-- source: https://gitlab.com/gitlab-org/gitlab/-/blob/d693aa7f894c7306a0d20ab6d138a7b95785f2ff/lib/backup/manager.rb#L117-133 -->
@@ -461,7 +513,9 @@ Depending on your installation type, slightly different components can be skippe
- `ci_secure_files` (Project-level secure files)
- `external_diffs` (External merge request diffs)
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
<!-- source: https://gitlab.com/gitlab-org/build/CNG/-/blob/068e146db915efcd875414e04403410b71a2e70c/gitlab-toolbox/scripts/bin/backup-utility#L19 -->
@@ -477,27 +531,35 @@ Depending on your installation type, slightly different components can be skippe
- `ci_secure_files` (Project-level Secure Files)
- `external_diffs` (Merge request diffs)
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-backup create SKIP=db,uploads
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
See [Skipping components](https://docs.gitlab.com/charts/backup-restore/backup.html#skipping-components) in charts backup documentation.
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
```shell
sudo -u git -H bundle exec rake gitlab:backup:create SKIP=db,uploads RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
`SKIP=` is also used to:
@@ -506,9 +568,12 @@ sudo -u git -H bundle exec rake gitlab:backup:create SKIP=db,uploads RAILS_ENV=p
#### Skipping tar creation
-NOTE:
+{{< alert type="note" >}}
+
It is not possible to skip the tar creation when using [object storage](#upload-backups-to-a-remote-cloud-storage) for backups.
+{{< /alert >}}
+
The last part of creating a backup is generation of a `.tar` file containing all the parts. In some cases, creating a `.tar` file might be wasted effort or even directly harmful, so you can skip this step by adding `tar` to the `SKIP` environment variable. Example use-cases:
- When the backup is picked up by other backup software.
@@ -519,28 +584,36 @@ backup in the directory used for the intermediate files. These files are
overwritten when a new backup is created, so you should make sure they are copied
elsewhere, because you can only have one backup on the system.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-backup create SKIP=tar
```
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
```shell
sudo -u git -H bundle exec rake gitlab:backup:create SKIP=tar RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Create server-side repository backups
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4941) in `gitlab-backup` in GitLab 16.3.
-> - Server-side support in `gitlab-backup` for restoring a specified backup instead of the latest backup [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132188) in GitLab 16.6.
-> - Server-side support in `gitlab-backup` for creating incremental backups [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6475) in GitLab 16.6.
-> - Server-side support in `backup-utility` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438393) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4941) in `gitlab-backup` in GitLab 16.3.
+- Server-side support in `gitlab-backup` for restoring a specified backup instead of the latest backup [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132188) in GitLab 16.6.
+- Server-side support in `gitlab-backup` for creating incremental backups [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6475) in GitLab 16.6.
+- Server-side support in `backup-utility` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438393) in GitLab 17.0.
+
+{{< /history >}}
Instead of storing large repository backups in the backup archive, repository
backups can be configured so that the Gitaly node that hosts each repository is
@@ -550,21 +623,25 @@ helps reduce the network resources required to create and restore a backup.
1. [Configure a server-side backup destination in Gitaly](../gitaly/configure_gitaly.md#configure-server-side-backups).
1. Create a backup using the repositories server-side option. See the following examples.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-backup create REPOSITORIES_SERVER_SIDE=true
```
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
```shell
sudo -u git -H bundle exec rake gitlab:backup:create REPOSITORIES_SERVER_SIDE=true
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
```shell
kubectl exec <Toolbox pod name> -it -- backup-utility --repositories-server-side
@@ -573,7 +650,9 @@ kubectl exec <Toolbox pod name> -it -- backup-utility --repositories-server-side
When you are using [cron-based backups](https://docs.gitlab.com/charts/backup-restore/backup.html#cron-based-backup),
add the `--repositories-server-side` flag to the extra arguments.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Back up Git repositories concurrently
@@ -590,21 +669,25 @@ task:
For example, with 4 repository storages:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-backup create GITLAB_BACKUP_MAX_CONCURRENCY=4 GITLAB_BACKUP_MAX_STORAGE_CONCURRENCY=1
```
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
```shell
sudo -u git -H bundle exec rake gitlab:backup:create GITLAB_BACKUP_MAX_CONCURRENCY=4 GITLAB_BACKUP_MAX_STORAGE_CONCURRENCY=1
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
```yaml
toolbox:
@@ -616,21 +699,30 @@ toolbox:
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Incremental repository backups
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351383) in GitLab 14.10 [with a flag](../feature_flags.md) named `incremental_repository_backup`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/355945) in GitLab 15.3. Feature flag `incremental_repository_backup` removed.
-> - Server-side support for creating incremental backups [introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5461) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351383) in GitLab 14.10 [with a flag](../feature_flags.md) named `incremental_repository_backup`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/355945) in GitLab 15.3. Feature flag `incremental_repository_backup` removed.
+- Server-side support for creating incremental backups [introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5461) in GitLab 16.6.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
Only repositories support incremental backups. Therefore, if you use `INCREMENTAL=yes`, the task
creates a self-contained backup tar archive. This is because all subtasks except repositories are
still creating full backups (they overwrite the existing full backup).
See [issue 19256](https://gitlab.com/gitlab-org/gitlab/-/issues/19256) for a feature request to
support incremental backups for all subtasks.
+{{< /alert >}}
+
Incremental repository backups can be faster than full repository backups because they only pack changes since the last backup into the backup bundle for each repository.
The incremental backup archives are not linked to each other: each archive is a self-contained backup of the instance. There must be an existing backup
to create an incremental backup from.
@@ -653,7 +745,11 @@ sudo gitlab-backup create INCREMENTAL=yes SKIP=tar
#### Back up specific repository storages
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86896) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86896) in GitLab 15.0.
+
+{{< /history >}}
When using [multiple repository storages](../repository_storage_paths.md),
repositories from specific repository storages can be backed up separately
@@ -662,26 +758,34 @@ storage names.
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-backup create REPOSITORIES_STORAGES=storage1,storage2
```
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
```shell
sudo -u git -H bundle exec rake gitlab:backup:create REPOSITORIES_STORAGES=storage1,storage2
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Back up specific repositories
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88094) in GitLab 15.1.
-> - [Skipping specific repositories added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121865) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88094) in GitLab 15.1.
+- [Skipping specific repositories added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121865) in GitLab 16.1.
+
+{{< /history >}}
You can back up specific repositories using the `REPOSITORIES_PATHS` option.
Similarly, you can use `SKIP_REPOSITORIES_PATHS` to skip certain repositories.
@@ -692,33 +796,42 @@ descendent groups are included or skipped, depending on which option you used.
For example, to back up all repositories for all projects in **Group A** (`group-a`), the repository for **Project C** in **Group B** (`group-b/project-c`),
and skip the **Project D** in **Group A** (`group-a/project-d`):
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-backup create REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
```
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
```shell
sudo -u git -H bundle exec rake gitlab:backup:create REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
```shell
REPOSITORIES_PATHS=group-a SKIP_REPOSITORIES_PATHS=group-a/project_a2 backup-utility --skip db,registry,uploads,artifacts,lfs,packages,external_diffs,terraform_state,ci_secure_files,pages
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Upload backups to a remote (cloud) storage
-NOTE:
+{{< alert type="note" >}}
+
It is not possible to [skip the tar creation](#skipping-tar-creation) when using object storage for backups.
+{{< /alert >}}
+
You can let the backup script upload (using the [Fog library](https://fog.io/))
the `.tar` file it creates. In the following example, we use Amazon S3 for
storage, but Fog also lets you use [other storage providers](https://fog.io/storage/).
@@ -963,9 +1076,9 @@ For self-compiled installations:
##### Using Azure Blob storage
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -993,7 +1106,9 @@ For self-compiled installations:
1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
1. Edit `home/git/gitlab/config/gitlab.yml`:
@@ -1010,7 +1125,9 @@ For self-compiled installations:
1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
For more details, see the [table of Azure parameters](../object_storage.md#azure-blob-storage).
@@ -1029,21 +1146,25 @@ sudo gitlab-backup create DIRECTORY=weekly
If you have configured GitLab to [upload backups in a remote storage](#upload-backups-to-a-remote-cloud-storage),
you can use the `SKIP=remote` option to skip uploading your backups to the remote storage.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-backup create SKIP=remote
```
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
```shell
sudo -u git -H bundle exec rake gitlab:backup:create SKIP=remote RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Upload to locally-mounted shares
@@ -1080,9 +1201,9 @@ remaining after the failed upload attempt.
##### Configure uploads to locally-mounted shares
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1100,7 +1221,9 @@ remaining after the failed upload attempt.
1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect.
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
1. Edit `home/git/gitlab/config/gitlab.yml`:
@@ -1119,7 +1242,9 @@ remaining after the failed upload attempt.
1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Backup archive permissions
@@ -1129,9 +1254,9 @@ meant to avoid other system users reading GitLab data. If you need the backup
archives to have different permissions, you can use the `archive_permissions`
setting.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1142,7 +1267,9 @@ setting.
1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect.
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1154,19 +1281,24 @@ setting.
1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Configuring cron to make daily backups
-WARNING:
+{{< alert type="warning" >}}
+
The following cron jobs do not [back up your GitLab configuration files](#storing-configuration-files)
or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079).
+{{< /alert >}}
+
You can schedule a cron job that backs up your repositories and GitLab metadata.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit the crontab for the `root` user:
@@ -1181,7 +1313,9 @@ You can schedule a cron job that backs up your repositories and GitLab metadata.
0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1
```
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
1. Edit the crontab for the `git` user:
@@ -1196,7 +1330,9 @@ You can schedule a cron job that backs up your repositories and GitLab metadata.
0 2 * * * cd /home/git/gitlab && PATH=/usr/local/bin:/usr/bin:/bin bundle exec rake gitlab:backup:create RAILS_ENV=production CRON=1
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
The `CRON=1` environment setting directs the backup script to hide all progress
output if there aren't any errors. This is recommended to reduce cron spam.
@@ -1204,10 +1340,13 @@ When troubleshooting backup problems, however, replace `CRON=1` with `--trace` t
#### Limit backup lifetime for local files (prune old backups)
-WARNING:
+{{< alert type="warning" >}}
+
The process described in this section doesn't work if you used a [custom filename](#backup-filename)
for your backups.
+{{< /alert >}}
+
To prevent regular backups from using all your disk space, you may want to set a limited lifetime
for backups. The next time the backup task runs, backups older than the `backup_keep_time` are
pruned.
@@ -1218,9 +1357,9 @@ because the user may not have permission to list and delete files. It's
recommended that you configure the appropriate retention policy for your object
storage (for example, [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-lifecycle.html)).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1232,7 +1371,9 @@ storage (for example, [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/user-
1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect.
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1245,7 +1386,9 @@ storage (for example, [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/user-
1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Back up and restore for installations using PgBouncer
@@ -1285,7 +1428,11 @@ There are two ways to fix this:
###### Environment variable overrides
-> - Multiple databases support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133177) in GitLab 16.5.
+{{< history >}}
+
+- Multiple databases support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133177) in GitLab 16.5.
+
+{{< /history >}}
By default, GitLab uses the database configuration stored in a
configuration file (`database.yml`). However, you can override the database settings
@@ -1352,9 +1499,12 @@ In the following cases, consider using file system data transfer or snapshots as
- Your GitLab instance has a lot of forked projects and the regular backup task duplicates the Git data for all of them.
- Your GitLab instance has a problem and using the regular backup and import Rake tasks isn't possible.
-WARNING:
+{{< alert type="warning" >}}
+
Gitaly Cluster [does not support snapshot backups](../gitaly/_index.md#snapshot-backup-and-recovery).
+{{< /alert >}}
+
When considering using file system data transfer or snapshots:
- Don't use these methods to migrate from one operating system to another. The operating systems of the source and destination should be as similar as possible. For example,
@@ -1386,21 +1536,25 @@ practical use.
First, ensure you back up existing GitLab data while [skipping repositories](#excluding-specific-data-from-the-backup):
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-backup create SKIP=repositories
```
-:::TabTitle Self-compiled
+{{< /tab >}}
+
+{{< tab title="Self-compiled" >}}
```shell
sudo -u git -H bundle exec rake gitlab:backup:create SKIP=repositories RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
For manually backing up the Git repository data on disk, there are multiple possible strategies:
diff --git a/doc/administration/backup_restore/backup_large_reference_architectures.md b/doc/administration/backup_restore/backup_large_reference_architectures.md
index d04f4b80d9bd8ba264eafccb53ded8d4f691eb96..7927f0f4159e51cdef3662e72e901725bc54f00e 100644
--- a/doc/administration/backup_restore/backup_large_reference_architectures.md
+++ b/doc/administration/backup_restore/backup_large_reference_architectures.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Back up and restore large reference architectures
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This document describes how to:
@@ -28,32 +31,38 @@ This document is intended for environments using:
The [backup command](backup_gitlab.md) uses `pg_dump`, which is [not appropriate for databases over 100 GB](backup_gitlab.md#postgresql-databases). You must choose a PostgreSQL solution which has native, robust backup capabilities.
-::Tabs
+{{< tabs >}}
-:::TabTitle AWS
+{{< tab title="AWS" >}}
1. [Configure AWS Backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/creating-a-backup-plan.html) to back up RDS (and S3) data. For maximum protection, [configure continuous backups as well as snapshot backups](https://docs.aws.amazon.com/aws-backup/latest/devguide/point-in-time-recovery.html).
1. Configure AWS Backup to copy backups to a separate region. When AWS takes a backup, the backup can only be restored in the region the backup is stored.
1. After AWS Backup has run at least one scheduled backup, then you can [create an on-demand backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/recov-point-create-on-demand-backup.html) as needed.
-:::TabTitle Google
+{{< /tab >}}
+
+{{< tab title="Google" >}}
Schedule [automated daily backups of Google Cloud SQL data](https://cloud.google.com/sql/docs/postgres/backup-recovery/backing-up#schedulebackups).
Daily backups [can be retained](https://cloud.google.com/sql/docs/postgres/backup-recovery/backups#retention) for up to one year, and transaction logs can be retained for 7 days by default for point-in-time recovery.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure backup of object storage data
[Object storage](../object_storage.md), ([not NFS](../nfs.md)) is recommended for storing GitLab data, including [blobs](backup_gitlab.md#blobs) and [Container registry](backup_gitlab.md#container-registry).
-::Tabs
+{{< tabs >}}
-:::TabTitle AWS
+{{< tab title="AWS" >}}
Configure AWS Backup to back up S3 data. This can be done at the same time when [configuring the backup of PostgreSQL data](#configure-backup-of-postgresql-data).
-:::TabTitle Google
+{{< /tab >}}
+
+{{< tab title="Google" >}}
1. [Create a backup bucket in GCS](https://cloud.google.com/storage/docs/creating-buckets).
1. [Create Storage Transfer Service jobs](https://cloud.google.com/storage-transfer/docs/create-transfers) which copy each GitLab object storage bucket to a backup bucket. You can create these jobs once, and [schedule them to run daily](https://cloud.google.com/storage-transfer/docs/schedule-transfer-jobs). However this mixes new and old object storage data, so files that were deleted in GitLab will still exist in the backup. This wastes storage after restore, but it is otherwise not a problem. These files would be inaccessible to GitLab users since they do not exist in the GitLab database. You can delete [some of these orphaned files](../../raketasks/cleanup.md#clean-up-project-upload-files-from-object-storage) after restore, but this clean up Rake task only operates on a subset of files.
@@ -98,15 +107,17 @@ Configure AWS Backup to back up S3 data. This can be done at the same time when
1. The example script does not delete old backups. You could implement clean up of old backups according to your desired retention policy.
1. Ensure that backups are performed at the same time or later than Cloud SQL backups, to reduce data inconsistencies.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure backup of Git repositories
Set up cronjobs to perform Gitaly server-side backups:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. [Configure a server-side backup destination in all Gitaly nodes](../gitaly/configure_gitaly.md#configure-server-side-backups).
1. Configure [Upload backups to a remote (cloud) storage](backup_gitlab.md#upload-backups-to-a-remote-cloud-storage). Even though Gitaly backs up all Git data to its own object storage bucket, the `gitlab-backup` command also creates a `tar` file containing backup metadata. This `tar` file is required by the restore command.
@@ -146,7 +157,9 @@ Set up cronjobs to perform Gitaly server-side backups:
0 2 2-31 * * /opt/gitlab/bin/gitlab-backup create REPOSITORIES_SERVER_SIDE=true SKIP=db INCREMENTAL=yes PREVIOUS_BACKUP=1708568263_2024_02_22_16.9.0-ce CRON=1
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. [Configure a server-side backup destination in all Gitaly nodes](../gitaly/configure_gitaly.md#configure-server-side-backups).
1. [Configure Object storage buckets for backup-utility](https://docs.gitlab.com/charts/backup-restore/#object-storage). Even though Gitaly backs up all Git data to its own object storage bucket, the `backup-utility` command also creates a `tar` file containing backup metadata. This `tar` file is required by the restore command.
@@ -166,7 +179,9 @@ Set up cronjobs to perform Gitaly server-side backups:
--repositories-server-side --skip db --skip repositories --skip uploads --skip builds --skip artifacts --skip pages --skip lfs --skip terraform_state --skip registry --skip packages --skip ci_secure_files
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure backup of configuration files
@@ -257,9 +272,9 @@ Before restoring a backup:
### Restore object storage data
-::Tabs
+{{< tabs >}}
-:::TabTitle AWS
+{{< tab title="AWS" >}}
Each bucket exists as a separate backup within AWS and each backup can be restored to an existing or
new bucket.
@@ -277,19 +292,23 @@ new bucket.
1. You can move on to [Restore PostgreSQL data](#restore-postgresql-data) while the restore job is
running.
-:::TabTitle Google
+{{< /tab >}}
+
+{{< tab title="Google" >}}
1. [Create Storage Transfer Service jobs](https://cloud.google.com/storage-transfer/docs/create-transfers) to transfer backed up data to the GitLab buckets.
1. You can move on to [Restore PostgreSQL data](#restore-postgresql-data) while the transfer jobs are
running.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Restore PostgreSQL data
-::Tabs
+{{< tabs >}}
-:::TabTitle AWS
+{{< tab title="AWS" >}}
1. [Restore the AWS RDS database using built-in tooling](https://docs.aws.amazon.com/aws-backup/latest/devguide/restoring-rds.html),
which creates a new RDS instance.
@@ -304,7 +323,9 @@ new bucket.
1. Before moving on, wait until the new RDS instance is created and ready to use.
-:::TabTitle Google
+{{< /tab >}}
+
+{{< tab title="Google" >}}
1. [Restore the Google Cloud SQL database using built-in tooling](https://cloud.google.com/sql/docs/postgres/backup-recovery/restoring).
1. If you restore to a new database instance, then reconfigure GitLab to point to the new database:
@@ -317,7 +338,9 @@ new bucket.
1. Before moving on, wait until the Cloud SQL instance is ready to use.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Restore Git repositories
@@ -326,9 +349,9 @@ First, as part of [Restore object storage data](#restore-object-storage-data), y
- Restored a bucket containing the Gitaly server-side backups of Git repositories.
- Restored a bucket containing the `*_gitlab_backup.tar` files.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. SSH into a GitLab Rails node, which is a node that runs Puma or Sidekiq.
1. In your backup bucket, choose a `*_gitlab_backup.tar` file based on its timestamp, aligned with the PostgreSQL and object storage data that you restored.
@@ -385,7 +408,9 @@ First, as part of [Restore object storage data](#restore-object-storage-data), y
If you are migrating GitLab to a new environment, you can run the same checks on the source GitLab instance to determine whether
the integrity check result is preexisting or related to the backup and restore process.
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. SSH into a toolbox pod.
1. In your backup bucket, choose a `*_gitlab_backup.tar` file based on its timestamp, aligned with the PostgreSQL and object storage data that you restored.
@@ -445,6 +470,8 @@ First, as part of [Restore object storage data](#restore-object-storage-data), y
If you are migrating GitLab to a new environment, you can run the same checks on the source GitLab instance to determine whether
the integrity check result is preexisting or related to the backup and restore process.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
The restoration should be complete.
diff --git a/doc/administration/backup_restore/migrate_to_new_server.md b/doc/administration/backup_restore/migrate_to_new_server.md
index 287f4a2e55e01b766091fd36ec8cc9133e1000fa..44140561b5dfdf5b1bd3d9a104fc6afe118ff274 100644
--- a/doc/administration/backup_restore/migrate_to_new_server.md
+++ b/doc/administration/backup_restore/migrate_to_new_server.md
@@ -10,7 +10,8 @@ title: Migrate to a new server
You can use GitLab backup and restore to migrate your instance to a new server. This section outlines a typical procedure for a GitLab deployment running on a single server.
If you're running GitLab Geo, an alternative option is [Geo disaster recovery for planned failover](../geo/disaster_recovery/planned_failover.md). You must make sure all sites meet the [Geo requirements](../geo/_index.md#requirements-for-running-geo) before selecting Geo for the migration.
-WARNING:
+{{< alert type="warning" >}}
+
Avoid uncoordinated data processing by both the new and old servers, where multiple
servers could connect concurrently and process the same data. For example, when using
[incoming email](../incoming_email.md), if both GitLab instances are
@@ -19,6 +20,8 @@ This type of problem can occur with other services as well, such as a
[non-packaged database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server),
a non-packaged Redis instance, or non-packaged Sidekiq.
+{{< /alert >}}
+
Prerequisites:
- Some time before your migration, consider notifying your users of upcoming
diff --git a/doc/administration/backup_restore/restore_gitlab.md b/doc/administration/backup_restore/restore_gitlab.md
index 373562cdc220107cfe66a6c3a425e876e6cc8758..eeb58f49e5f883a086c9fcc6921d57f468a44018 100644
--- a/doc/administration/backup_restore/restore_gitlab.md
+++ b/doc/administration/backup_restore/restore_gitlab.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Restore GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides a command-line interface to restore your entire installation,
and is flexible enough to fit your needs.
@@ -106,9 +109,12 @@ after copying over the GitLab secrets file from the original installation.
Next, restore the backup, specifying the ID of the backup you wish to
restore:
-WARNING:
+{{< alert type="warning" >}}
+
The following command overwrites the contents of your GitLab database!
+{{< /alert >}}
+
```shell
# NOTE: "_gitlab_backup.tar" is omitted from the name
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
@@ -128,10 +134,13 @@ GitLab version mismatch:
Install the [correct GitLab version](https://packages.gitlab.com/gitlab/),
and then try again.
-WARNING:
+{{< alert type="warning" >}}
+
The restore command requires [additional parameters](backup_gitlab.md#back-up-and-restore-for-installations-using-pgbouncer) when
your installation is using PgBouncer, for either performance reasons or when using it with a Patroni cluster.
+{{< /alert >}}
+
Next, restart and [check](../raketasks/maintenance.md#check-gitlab-configuration) GitLab:
```shell
@@ -376,13 +385,20 @@ To exclude specific tasks:
### Restore specific repository storages
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86896) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86896) in GitLab 15.0.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
GitLab 17.1 and earlier are [affected by a race condition](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158412) that can cause data loss. The problem affects
repositories that have been forked and use GitLab [object pools](../repository_storage_paths.md#hashed-object-pools). To avoid data loss, **only restore backups by using GitLab
17.2 or later**.
+{{< /alert >}}
+
When using [multiple repository storages](../repository_storage_paths.md),
repositories from specific repository storages can be restored separately
using the `REPOSITORIES_STORAGES` option. The option accepts a comma-separated list of
@@ -404,24 +420,34 @@ For example:
### Restore specific repositories
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88094) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88094) in GitLab 15.1.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
GitLab 17.1 and earlier are [affected by a race condition](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158412) that can cause data loss. The problem affects
repositories that have been forked and use GitLab [object pools](../repository_storage_paths.md#hashed-object-pools). To avoid data loss, **only restore backups by using GitLab
17.2 or later**.
+{{< /alert >}}
+
You can restore specific repositories using the `REPOSITORIES_PATHS` and the `SKIP_REPOSITORIES_PATHS` options.
Both options accept a comma-separated list of project and group paths. If you
specify a group path, all repositories in all projects in the group and
descendent groups are included or skipped, depending on which option you used.
Both the groups and projects must exist in the specified backup or on the target instance.
-NOTE:
+{{< alert type="note" >}}
+
The `REPOSITORIES_PATHS` and `SKIP_REPOSITORIES_PATHS` options apply only to Git repositories.
They do not apply to project or group database entries. If you created a repositories backup
with `SKIP=db`, by itself it cannot be used to restore specific repositories to a new instance.
+{{< /alert >}}
+
For example, to restore all repositories for all projects in **Group A** (`group-a`), the repository for **Project C** in **Group B** (`group-b/project-c`),
and skip the **Project D** in **Group A** (`group-a/project-d`):
diff --git a/doc/administration/backup_restore/troubleshooting_backup_gitlab.md b/doc/administration/backup_restore/troubleshooting_backup_gitlab.md
index b8ba29c4c973a92edfa3d16d733e243061eaabbd..caa5514818f40fecf45d225cdf72d5fe02783cc2 100644
--- a/doc/administration/backup_restore/troubleshooting_backup_gitlab.md
+++ b/doc/administration/backup_restore/troubleshooting_backup_gitlab.md
@@ -37,10 +37,13 @@ runner authentication, which is described in more detail in the following
sections. After resetting the tokens, you should be able to visit your project
and the jobs begin running again.
-WARNING:
+{{< alert type="warning" >}}
+
The steps in this section can potentially lead to **data loss** on the above listed items.
Consider opening a [Support Request](https://support.gitlab.com/hc/en-us/requests/new) if you're a Premium or Ultimate customer.
+{{< /alert >}}
+
### Verify that all values can be decrypted
You can determine if your database contains values that can't be decrypted by using a
@@ -50,9 +53,12 @@ You can determine if your database contains values that can't be decrypted by us
You must directly modify GitLab data to work around your lost secrets file.
-WARNING:
+{{< alert type="warning" >}}
+
Be sure to create a full database backup before attempting any changes.
+{{< /alert >}}
+
### Disable user two-factor authentication (2FA)
Users with 2FA enabled can't sign in to GitLab. In that case, you must
@@ -118,10 +124,13 @@ You may need to reconfigure or restart GitLab for the changes to take effect.
1. Clear all tokens for projects, groups, and the entire instance:
- WARNING:
+ {{< alert type="warning" >}}
+
The final `UPDATE` operation stops the runners from being able to pick
up new jobs. You must register new runners.
+ {{< /alert >}}
+
```sql
-- Clear project tokens
UPDATE projects SET runners_token = null, runners_token_encrypted = null;
@@ -272,10 +281,13 @@ Problem: <class 'OSError: [Errno 36] File name too long:
This problem stops the backup script from completing. To fix this problem, you must truncate the filenames causing the problem. A maximum of 246 characters, including the file extension, is permitted.
-WARNING:
+{{< alert type="warning" >}}
+
The steps in this section can potentially lead to **data loss**. All steps must be followed strictly in the order given.
Consider opening a [Support Request](https://support.gitlab.com/hc/en-us/requests/new) if you're a Premium or Ultimate customer.
+{{< /alert >}}
+
Truncating filenames to resolve the error involves:
- Cleaning up remote uploaded files that aren't tracked in the database.
@@ -296,9 +308,12 @@ To fix these files, you must clean up all remote uploaded files that are in the
1. If you are sure you want to delete these files and remove all non-referenced uploaded files, run:
- WARNING:
+ {{< alert type="warning" >}}
+
The following action is **irreversible**.
+ {{< /alert >}}
+
```shell
bundle exec rake gitlab:cleanup:remote_upload_files RAILS_ENV=production DRY_RUN=false
```
@@ -417,9 +432,12 @@ Truncate the filenames in the `uploads` table:
1. Validate that the new filenames from the previous query are the expected ones. If you are sure you want to truncate the records found in the previous step to 246 characters, run the following:
- WARNING:
+ {{< alert type="warning" >}}
+
The following action is **irreversible**.
+ {{< /alert >}}
+
```sql
CREATE TEMP TABLE uploads_with_long_filenames AS
SELECT ROW_NUMBER() OVER(ORDER BY id) row_id, path, id
diff --git a/doc/administration/broadcast_messages.md b/doc/administration/broadcast_messages.md
index bf768e480f3944bed2eb7f763601e765bc2cd421..210da58e5e7120a5e5f31db142883727f31d2c1e 100644
--- a/doc/administration/broadcast_messages.md
+++ b/doc/administration/broadcast_messages.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Broadcast messages
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab can display two types of broadcast messages to users of a GitLab instance:
diff --git a/doc/administration/cells.md b/doc/administration/cells.md
index a6419d0993711935d653eadc1a5fe6be85636f67..4dd6e3163b0044e50ed8605160187de9d4f5c3ba 100644
--- a/doc/administration/cells.md
+++ b/doc/administration/cells.md
@@ -5,23 +5,27 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Cells
---
-DETAILS:
-**Offering:** GitLab.com
-**Status:** Experiment
+{{< details >}}
+
+- Offering: GitLab.com
+- Status: Experiment
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is available for administrators of GitLab.com only. This feature is not available for GitLab Self-Managed or GitLab Dedicated instances.
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the
-sole discretion of GitLab Inc.
+{{< /alert >}}
+
+{{< alert type="disclaimer" />}}
+
+{{< alert type="note" >}}
-NOTE:
Cells 1.0 is in development. For more information about the state of cell development, see [epic 12383](https://gitlab.com/groups/gitlab-org/-/epics/12383).
+{{< /alert >}}
+
This page explains how to configure the GitLab Rails console for cell functionality. For more information on the proposed design and terminology, see the design document for [Cells](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/).
## Configuration
diff --git a/doc/administration/cicd/_index.md b/doc/administration/cicd/_index.md
index ff0a2277df568556be55644cb09b8cf684b6eb16..f90f17e6075c175bc5a9ecf70968b7f8cdcae127 100644
--- a/doc/administration/cicd/_index.md
+++ b/doc/administration/cicd/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab CI/CD instance configuration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab administrators can manage the GitLab CI/CD configuration for their instance.
@@ -62,9 +65,12 @@ For Linux package installations:
## Set the `needs` job limit
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The maximum number of jobs that can be defined in `needs` defaults to 50.
diff --git a/doc/administration/cicd/compute_minutes.md b/doc/administration/cicd/compute_minutes.md
index b515db6ec26adf8a5e90028c8e36d7cde6dda2c9..91e5dade554098ebad3a870463c52e5c49a298de 100644
--- a/doc/administration/cicd/compute_minutes.md
+++ b/doc/administration/cicd/compute_minutes.md
@@ -1,16 +1,23 @@
---
stage: Verify
group: Pipeline Execution
-description: Calculations, quotas, purchase information.
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
+description: Calculations, quotas, purchase information.
title: Compute minutes administration
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" or "compute minutes" in GitLab 16.1.
-> - [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" or "compute minutes" in GitLab 16.1.
+{{< /history >}}
Administrators can limit the amount of time that projects can use to run jobs on
[instance runners](../../ci/runners/runners_scope.md#instance-runners) each month. This limit
diff --git a/doc/administration/cicd/external_pipeline_validation.md b/doc/administration/cicd/external_pipeline_validation.md
index 251ffc44848745bb13c1bc451902a9ddda744b45..5a4812e0d32300edf54156e53948503ec555234b 100644
--- a/doc/administration/cicd/external_pipeline_validation.md
+++ b/doc/administration/cicd/external_pipeline_validation.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: External pipeline validation
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can use an external service to validate a pipeline before it's created.
@@ -37,7 +40,11 @@ required number of seconds.
## Payload schema
-> - `tag_list` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335904) in GitLab 16.11.
+{{< history >}}
+
+- `tag_list` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335904) in GitLab 16.11.
+
+{{< /history >}}
```json
{
diff --git a/doc/administration/cicd/job_artifacts.md b/doc/administration/cicd/job_artifacts.md
index eb35769ef7980323fbf0200d75d0761d74c964c5..ba592b8c12786a244da7888f2cb16bd517ff30c6 100644
--- a/doc/administration/cicd/job_artifacts.md
+++ b/doc/administration/cicd/job_artifacts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Jobs artifacts administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This is the administration documentation. To learn how to use job artifacts in your GitLab CI/CD pipeline,
see the [job artifacts configuration documentation](../../ci/jobs/job_artifacts.md).
@@ -19,9 +22,9 @@ finishes. This feature is enabled by default in all GitLab installations.
To disable artifacts site-wide:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -35,7 +38,9 @@ To disable artifacts site-wide:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -58,7 +63,9 @@ To disable artifacts site-wide:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -77,7 +84,9 @@ To disable artifacts site-wide:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -97,7 +106,9 @@ To disable artifacts site-wide:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Storing job artifacts
@@ -113,14 +124,17 @@ Most artifacts are compressed by GitLab Runner before being sent to the coordina
If you're using the Linux package or have a self-compiled installation, you
can change the location where the artifacts are stored locally.
-NOTE:
+{{< alert type="note" >}}
+
For Docker installations, you can change the path where your data is mounted.
For the Helm chart, use
[object storage](https://docs.gitlab.com/charts/advanced/external-object-storage/).
-::Tabs
+{{< /alert >}}
-:::TabTitle Linux package (Omnibus)
+{{< tabs >}}
+
+{{< tab title="Linux package (Omnibus)" >}}
The artifacts are stored by default in `/var/opt/gitlab/gitlab-rails/shared/artifacts`.
@@ -137,7 +151,9 @@ The artifacts are stored by default in `/var/opt/gitlab/gitlab-rails/shared/arti
sudo gitlab-ctl reconfigure
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
The artifacts are stored by default in `/home/git/gitlab/shared/artifacts`.
@@ -161,7 +177,9 @@ The artifacts are stored by default in `/home/git/gitlab/shared/artifacts`.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Using object storage
@@ -172,10 +190,13 @@ If you configure GitLab to store artifacts on object storage, you may also want
[eliminate local disk usage for job logs](job_logs.md#prevent-local-disk-usage).
In both cases, job logs are archived and moved to object storage when the job completes.
-WARNING:
+{{< alert type="warning" >}}
+
In a multi-server setup you must use one of the options to
[eliminate local disk usage for job logs](job_logs.md#prevent-local-disk-usage), or job logs could be lost.
+{{< /alert >}}
+
You should use the [consolidated object storage settings](../object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form).
### Migrating to object storage
@@ -186,54 +207,66 @@ processing is done in a background worker and requires **no downtime**.
1. [Configure the object storage](#using-object-storage).
1. Migrate the artifacts:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake gitlab:artifacts:migrate
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
```shell
sudo docker exec -t <container name> gitlab-rake gitlab:artifacts:migrate
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Optional. Track the progress and verify that all job artifacts migrated
successfully using the PostgreSQL console.
1. Open a PostgreSQL console:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-psql
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
```shell
sudo docker exec -it <container_name> /bin/bash
gitlab-psql
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo -u git -H psql -d gitlabhq_production
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Verify that all artifacts migrated to object storage with the following
SQL query. The number of `objectstg` should be the same as `total`:
@@ -248,15 +281,17 @@ processing is done in a background worker and requires **no downtime**.
1. Verify that there are no files on disk in the `artifacts` directory:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
sudo find /var/opt/gitlab/gitlab-rails/shared/artifacts -type f | grep -v tmp | wc -l
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
Assuming you mounted `/var/opt/gitlab` to `/srv/gitlab`:
@@ -264,13 +299,17 @@ processing is done in a background worker and requires **no downtime**.
sudo find /srv/gitlab/gitlab-rails/shared/artifacts -type f | grep -v tmp | wc -l
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo find /home/git/gitlab/shared/artifacts -type f | grep -v tmp | wc -l
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. If [Geo](../geo/_index.md) is enabled, [reverify all job artifacts](../geo/replication/troubleshooting/synchronization_verification.md#reverify-one-component-on-all-sites).
@@ -296,9 +335,9 @@ runs every 7 minutes (`*/7 * * * *` in [Cron](../../topics/cron/_index.md) synta
To change the default schedule on which expired artifacts are deleted:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line (or uncomment it if
it already exists and is commented out), substituting your schedule in cron
@@ -314,7 +353,9 @@ To change the default schedule on which expired artifacts are deleted:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -338,7 +379,9 @@ To change the default schedule on which expired artifacts are deleted:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -357,7 +400,9 @@ To change the default schedule on which expired artifacts are deleted:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -378,7 +423,9 @@ To change the default schedule on which expired artifacts are deleted:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Set the maximum file size of the artifacts
diff --git a/doc/administration/cicd/job_artifacts_troubleshooting.md b/doc/administration/cicd/job_artifacts_troubleshooting.md
index cb82dd5144ee8416cb7556fd2c1218cb2f663f2d..78b7c6bbfb0b57a0717078dcff1c55c39bbc4d1c 100644
--- a/doc/administration/cicd/job_artifacts_troubleshooting.md
+++ b/doc/administration/cicd/job_artifacts_troubleshooting.md
@@ -73,15 +73,17 @@ You can check the database to confirm if your instance has artifacts with the `u
1. Start a database console:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-psql
```
- :::TabTitle Helm chart (Kubernetes)
+ {{< /tab >}}
+
+ {{< tab title="Helm chart (Kubernetes)" >}}
```shell
# Find the toolbox pod
@@ -90,20 +92,26 @@ You can check the database to confirm if your instance has artifacts with the `u
kubectl exec -it <toolbox-pod-name> -- /srv/gitlab/bin/rails dbconsole --include-password --database main
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
```shell
sudo docker exec -it <container_name> /bin/bash
gitlab-psql
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo -u git -H psql -d gitlabhq_production
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Run the following query:
@@ -246,11 +254,14 @@ To change the number of job artifacts listed, change the number in `limit(50)`.
### Delete old builds and artifacts
-WARNING:
+{{< alert type="warning" >}}
+
These commands remove data permanently. Before running them in a production environment,
you should try them in a test environment first and make a backup of the instance
that can be restored if needed.
+{{< /alert >}}
+
#### Delete old artifacts for a project
This step also erases artifacts that users have [chosen to keep](../../ci/jobs/job_artifacts.md#with-an-expiry):
@@ -358,11 +369,14 @@ they are not scheduled by a background queue.
### Delete old pipelines
-WARNING:
+{{< alert type="warning" >}}
+
These commands remove data permanently. Before running them in a production environment,
consider seeking guidance from a Support Engineer. You should also try them in a test environment first
and make a backup of the instance that can be restored if needed.
+{{< /alert >}}
+
Deleting a pipeline also removes that pipeline's:
- Job artifacts
diff --git a/doc/administration/cicd/job_logs.md b/doc/administration/cicd/job_logs.md
index f75aa67e224fdb1564611eb69549904c92444b3d..c8a6e94d92ebf173f96d84af2799c544f756c144 100644
--- a/doc/administration/cicd/job_logs.md
+++ b/doc/administration/cicd/job_logs.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Job logs
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Job logs are sent by a runner while it's processing a job. You can see
logs in places like job pages, pipelines, and email notifications.
@@ -30,15 +33,18 @@ The `ROOT_PATH` varies per environment:
## Changing the job logs local location
-NOTE:
+{{< alert type="note" >}}
+
For Docker installations, you can change the path where your data is mounted.
For the Helm chart, use object storage.
+{{< /alert >}}
+
To change the location where the job logs are stored:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Optional. If you have existing job logs, pause continuous integration data
processing by temporarily stopping Sidekiq:
@@ -80,7 +86,9 @@ To change the location where the job logs are stored:
sudo rm -rf /var/opt/gitlab/gitlab-ci/builds
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Optional. If you have existing job logs, pause continuous integration data
processing by temporarily stopping Sidekiq:
@@ -136,7 +144,9 @@ To change the location where the job logs are stored:
sudo rm -rf /home/git/gitlab/builds
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Uploading logs to object storage
@@ -173,22 +183,30 @@ see [Delete job logs](../../user/storage_management_automation.md#delete-job-log
Alternatively, you can delete job logs with shell commands. For example, to delete all job logs older than 60 days, run the following
command from a shell in your GitLab instance.
-NOTE:
+{{< alert type="note" >}}
+
For the Helm chart, use the storage management tools provided with your object
storage.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The following command permanently deletes the log files and is irreversible.
-::Tabs
+{{< /alert >}}
+
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
find /var/opt/gitlab/gitlab-rails/shared/artifacts -name "job.log" -mtime +60 -delete
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
Assuming you mounted `/var/opt/gitlab` to `/srv/gitlab`:
@@ -196,13 +214,17 @@ Assuming you mounted `/var/opt/gitlab` to `/srv/gitlab`:
find /srv/gitlab/gitlab-rails/shared/artifacts -name "job.log" -mtime +60 -delete
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
find /home/git/gitlab/shared/artifacts -name "job.log" -mtime +60 -delete
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
After the logs are deleted, you can find any broken file references by running
the Rake task that checks the
diff --git a/doc/administration/cicd/maintenance.md b/doc/administration/cicd/maintenance.md
index 1bf047a0d6b01970c5deacf58f1357b58dff2432..8c7d4e02da1d5a8a2ced5c6f75f2bc3e76bb40bd 100644
--- a/doc/administration/cicd/maintenance.md
+++ b/doc/administration/cicd/maintenance.md
@@ -5,16 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI/CD maintenance console commands
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following commands are run in the [Rails console](../operations/rails_console.md#starting-a-rails-console-session).
-WARNING:
+{{< alert type="warning" >}}
+
Any command that changes data directly could be damaging if not run correctly, or under the right conditions.
We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case.
+{{< /alert >}}
+
## Cancel all running pipelines and their jobs
```ruby
@@ -82,12 +88,15 @@ ps = Ci::CreatePipelineService.new(schedule.project, user, ref: schedule.ref).ex
## Obtain runners registration token (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
The ability to pass a runner registration token, and support for certain configuration arguments, was
[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and is planned for removal
in GitLab 18.0. Runner authentication tokens should be used instead. For more information, see
[Migrating to the new runner registration workflow](../../ci/runners/new_creation_workflow.md).
+{{< /alert >}}
+
Prerequisites:
- Runner registration tokens must be [enabled](../settings/continuous_integration.md#allow-runner-registrations-tokens) in the **Admin** area.
@@ -98,16 +107,19 @@ Gitlab::CurrentSettings.current_application_settings.runners_registration_token
## Seed runners registration token (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
The ability to pass a runner registration token, and support for certain configuration arguments, was
[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and is planned for removal
in GitLab 18.0. Runner authentication tokens should be used instead. For more information, see
[Migrating to the new runner registration workflow](../../ci/runners/new_creation_workflow.md).
+{{< /alert >}}
+
```ruby
appSetting = Gitlab::CurrentSettings.current_application_settings
appSetting.set_runners_registration_token('<new-runners-registration-token>')
appSetting.save!
```
-<!--- end_remove -->
\ No newline at end of file
+<!--- end_remove -->
diff --git a/doc/administration/cicd/secure_files.md b/doc/administration/cicd/secure_files.md
index 7cffa64784fc7fc33a81ef1f5394c744cc6f4cc5..318d79d8a53fd1566723ae5841247ccf712ac27b 100644
--- a/doc/administration/cicd/secure_files.md
+++ b/doc/administration/cicd/secure_files.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Secure Files administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) and feature flag `ci_secure_files` removed in GitLab 15.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) and feature flag `ci_secure_files` removed in GitLab 15.7.
+
+{{< /history >}}
You can securely store up to 100 files for use in CI/CD pipelines as secure files.
These files are stored securely outside of your project's repository and are not version controlled.
@@ -89,16 +96,23 @@ are stored locally, follow the steps below.
## Using object storage
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Instead of storing Secure Files on disk, you should use [one of the supported object storage options](../object_storage.md#supported-object-storage-providers).
This configuration relies on valid credentials to be configured already.
### Consolidated object storage
-> - Support for consolidated object storage was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149873) in GitLab 17.0.
+{{< history >}}
+
+- Support for consolidated object storage was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149873) in GitLab 17.0.
+
+{{< /history >}}
Using the [consolidated form](../object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form)
of the object storage is recommended.
@@ -120,9 +134,9 @@ The following settings are:
See [the available connection settings for different providers](../object_storage.md#configure-the-connection-settings).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, but using
the values you want:
@@ -138,8 +152,11 @@ See [the available connection settings for different providers](../object_storag
}
```
- NOTE:
- If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs:
+ {{< alert type="note" >}}
+
+ If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs:
+
+ {{< /alert >}}
```ruby
gitlab_rails['ci_secure_files_object_store_connection'] = {
@@ -157,7 +174,9 @@ See [the available connection settings for different providers](../object_storag
1. [Migrate any existing local states to the object storage](#migrate-to-object-storage).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
@@ -186,16 +205,25 @@ See [the available connection settings for different providers](../object_storag
1. [Migrate any existing local states to the object storage](#migrate-to-object-storage).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Migrate to object storage
-> - [Introduced](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/readme/-/issues/125) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/readme/-/issues/125) in GitLab 16.1.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
It's not possible to migrate Secure Files from object storage back to local storage,
so proceed with caution.
+{{< /alert >}}
+
To migrate Secure Files to object storage, follow the instructions below.
- For Linux package installations:
diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md
index 04120a4c6c3ad472bf6491e9436ff184b8a3cc57..6b47686c98a67d7cb2fa3208a8e98e296818860d 100644
--- a/doc/administration/clusters/kas.md
+++ b/doc/administration/clusters/kas.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Install the GitLab agent server for Kubernetes (KAS)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The agent server is a component installed together with GitLab. It is required to
manage the [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent).
@@ -114,8 +117,12 @@ gitlab_kas['env'] = {
##### Option 2 - automatic CIDR-based configuration
-> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/464) in GitLab 16.5.0.
-> - [Added](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/2183) multiple CIDR support to `OWN_PRIVATE_API_CIDR` in GitLab 17.8.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/464) in GitLab 16.5.0.
+- [Added](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/2183) multiple CIDR support to `OWN_PRIVATE_API_CIDR` in GitLab 17.8.1.
+
+{{< /history >}}
You might not be able to set an exact IP address or hostname in the `OWN_PRIVATE_API_URL` variable if, for example,
the KAS host is assigned an IP address and a hostname dynamically.
@@ -148,8 +155,12 @@ gitlab_kas['env'] = {
##### Option 3 - automatic configuration based on listener configuration
-> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/464) in GitLab 16.5.0.
-> - [Updated](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/510) KAS to listen on and publish all non-loopback IP addresses and filter out IPv4 and IPv6 addresses based on the value of `private_api_listen_network`.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/464) in GitLab 16.5.0.
+- [Updated](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/510) KAS to listen on and publish all non-loopback IP addresses and filter out IPv4 and IPv6 addresses based on the value of `private_api_listen_network`.
+
+{{< /history >}}
A KAS node can determine what IP addresses are available based on the `private_api_listen_network` and
`private_api_listen_address` settings:
@@ -230,9 +241,13 @@ See [how to use the GitLab-KAS chart](https://docs.gitlab.com/charts/charts/gitl
## Kubernetes API proxy cookie
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104504) in GitLab 15.10 [with feature flags](../feature_flags.md) named `kas_user_access` and `kas_user_access_project`. Disabled by default.
-> - Feature flags `kas_user_access` and `kas_user_access_project` [enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123479) in GitLab 16.1.
-> - Feature flags `kas_user_access` and `kas_user_access_project` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125835) in GitLab 16.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104504) in GitLab 15.10 [with feature flags](../feature_flags.md) named `kas_user_access` and `kas_user_access_project`. Disabled by default.
+- Feature flags `kas_user_access` and `kas_user_access_project` [enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123479) in GitLab 16.1.
+- Feature flags `kas_user_access` and `kas_user_access_project` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125835) in GitLab 16.2.
+
+{{< /history >}}
KAS proxies Kubernetes API requests to the GitLab agent with either:
@@ -247,11 +262,18 @@ to authenticate and authorize the user.
## Enable receptive agents
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12180) in GitLab 17.4.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12180) in GitLab 17.4.
+{{< /history >}}
[Receptive agents](../../user/clusters/agent/_index.md#receptive-agents) allow GitLab to integrate with Kubernetes clusters
that cannot establish a network connection to the GitLab instance, but can be connected to by GitLab.
diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md
index 4547d8ae16e2fb111521a97c2b7f25074e4e9938..ce6f5ea1ae0956c89ed53a2948e1094b3276b12a 100644
--- a/doc/administration/compliance.md
+++ b/doc/administration/compliance.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Compliance features
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab compliance features ensure your GitLab instance meets common compliance standards, and are available at various pricing tiers. For more information about compliance management, see the compliance
management [solutions page](https://about.gitlab.com/solutions/compliance/).
@@ -23,12 +26,12 @@ and secure supply chain best practices:
| Feature | Instances | Groups | Projects | Description |
|:--------------|:------------------|:--------------------|:-----------------------|:-------------------------------|
-| [Credentials inventory](credentials_inventory.md) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Keep track of the credentials used by all of the users in a GitLab instance. |
-| [Granular user roles<br/>and flexible permissions](../user/permissions.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Manage access and permissions with five different user roles and settings for external users. Set permissions according to people's role, rather than either read or write access to a repository. Don't share the source code with people that only need access to the issue tracker. |
-| [Merge request approvals](../user/project/merge_requests/approvals/_index.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Configure approvals required for merge requests. |
-| [Push rules](../user/project/repository/push_rules.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Control pushes to your repositories. |
-| Separation of duties using<br/>[protected branches](../user/project/repository/branches/protected.md#require-code-owner-approval-on-a-protected-branch) and<br/>[custom CI/CD configuration paths](../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Leverage the GitLab cross-project YAML configurations to define deployers of code and developers of code. See how to use this setup to define these roles in the [Separation of Duties deploy project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and the [Separation of Duties project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md). |
-| [Security policies](../user/application_security/policies/_index.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Configure customizable policies that require merge request approval based on policy rules, or enforce security scanners to execute in project pipelines for compliance requirements. Policies can be enforced granularly against specific projects, or all projects in a group or subgroup. |
+| [Credentials inventory](credentials_inventory.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Keep track of the credentials used by all of the users in a GitLab instance. |
+| [Granular user roles<br/>and flexible permissions](../user/permissions.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Manage access and permissions with five different user roles and settings for external users. Set permissions according to people's role, rather than either read or write access to a repository. Don't share the source code with people that only need access to the issue tracker. |
+| [Merge request approvals](../user/project/merge_requests/approvals/_index.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Configure approvals required for merge requests. |
+| [Push rules](../user/project/repository/push_rules.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Control pushes to your repositories. |
+| Separation of duties using<br/>[protected branches](../user/project/repository/branches/protected.md#require-code-owner-approval-on-a-protected-branch) and<br/>[custom CI/CD configuration paths](../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file) | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Leverage the GitLab cross-project YAML configurations to define deployers of code and developers of code. See how to use this setup to define these roles in the [Separation of Duties deploy project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and the [Separation of Duties project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md). |
+| [Security policies](../user/application_security/policies/_index.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Configure customizable policies that require merge request approval based on policy rules, or enforce security scanners to execute in project pipelines for compliance requirements. Policies can be enforced granularly against specific projects, or all projects in a group or subgroup. |
## Compliant workflow automation
@@ -42,9 +45,9 @@ compliance:
| Feature | Instances | Groups | Projects | Description |
|:------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------------------------------------------------------------------------------------------|
-| [Compliance frameworks](../user/group/compliance_frameworks.md) | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Describe the type of compliance requirements projects must follow. |
-| [Compliance pipelines](../user/group/compliance_pipelines.md) | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Define a pipeline configuration to run for any projects with a given compliance framework. |
-| [Merge request approval policy approval settings](../user/application_security/policies/merge_request_approval_policies.md#approval_settings) | **{dotted-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Enforce a merge request approval policy enforcing multiple approvers and override various project settings in all enforced groups or projects across your GitLab instance or group. |
+| [Compliance frameworks](../user/group/compliance_frameworks.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Describe the type of compliance requirements projects must follow. |
+| [Compliance pipelines](../user/group/compliance_pipelines.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Define a pipeline configuration to run for any projects with a given compliance framework. |
+| [Merge request approval policy approval settings](../user/application_security/policies/merge_request_approval_policies.md#approval_settings) | {{< icon name="dotted-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} Yes | Enforce a merge request approval policy enforcing multiple approvers and override various project settings in all enforced groups or projects across your GitLab instance or group. |
## Audit management
@@ -59,10 +62,10 @@ These features can help provide visibility into GitLab and audit what is happeni
| Feature | Instances | Groups | Projects | Description |
|:-------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [Audit events](audit_event_reports.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | To maintain the integrity of your code, audit events give administrators the ability to view any modifications made in the GitLab server in an advanced audit events system, so you can control, analyze, and track every change. |
-| [Audit reports](audit_event_reports.md) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Create and access reports based on the audit events that have occurred. Use pre-built GitLab reports or the API to build your own. |
-| [Auditor users](auditor_users.md) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance. |
-| [Compliance center](../user/compliance/compliance_center/_index.md) | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | Quickly get visibility into the compliance posture of your organization through compliance standards adherence reporting and violations reports. Manage your groups compliance frameworks centrally. |
+| [Audit events](audit_event_reports.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | To maintain the integrity of your code, audit events give administrators the ability to view any modifications made in the GitLab server in an advanced audit events system, so you can control, analyze, and track every change. |
+| [Audit reports](audit_event_reports.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Create and access reports based on the audit events that have occurred. Use pre-built GitLab reports or the API to build your own. |
+| [Auditor users](auditor_users.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance. |
+| [Compliance center](../user/compliance/compliance_center/_index.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Quickly get visibility into the compliance posture of your organization through compliance standards adherence reporting and violations reports. Manage your groups compliance frameworks centrally. |
## Other compliance features
@@ -70,13 +73,13 @@ These features can also help with compliance requirements:
| Feature | Instances | Groups | Projects | Description |
|:------------------------------------------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [Email all users of a project,<br/>group, or entire server](email_from_gitlab.md) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Email groups of users based on project or group membership, or email everyone using the GitLab instance. These emails are great for scheduled maintenance or upgrades. |
-| [Enforce ToS acceptance](settings/terms.md) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Enforce your users accepting new terms of service by blocking GitLab traffic. |
-| [External Status Checks](../user/project/merge_requests/status_checks.md) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Interface with third-party systems you already use during development to ensure you remain compliant. |
-| [Generate reports on permission<br/>levels of users](admin_area.md#user-permission-export) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Generate a report listing all users' access permissions for groups and projects in the instance. |
-| [License approval policies](../user/compliance/license_approval_policies.md) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Search dependencies for their licenses. This lets you determine if the licenses of your project's dependencies are compatible with your project's license. |
-| [Lock project membership to group](../user/group/access_and_permissions.md#prevent-members-from-being-added-to-projects-in-a-group) | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Group owners can prevent new members from being added to projects in a group. |
-| [LDAP group sync](auth/ldap/ldap_synchronization.md#group-sync) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Automatically synchronize groups and manage SSH keys, permissions, and authentication, so you can focus on building your product, not configuring your tools. |
-| [LDAP group sync filters](auth/ldap/ldap_synchronization.md#group-sync) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Gives more flexibility to synchronize with LDAP based on filters, meaning you can leverage LDAP attributes to map GitLab permissions. |
-| [Linux package installations support<br/>log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-forwarding) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Forward your logs to a central system. |
-| [Restrict SSH Keys](../security/ssh_keys_restrictions.md) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Control the technology and key length of SSH keys used to access GitLab. |
+| [Email all users of a project,<br/>group, or entire server](email_from_gitlab.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Email groups of users based on project or group membership, or email everyone using the GitLab instance. These emails are great for scheduled maintenance or upgrades. |
+| [Enforce ToS acceptance](settings/terms.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Enforce your users accepting new terms of service by blocking GitLab traffic. |
+| [External Status Checks](../user/project/merge_requests/status_checks.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Interface with third-party systems you already use during development to ensure you remain compliant. |
+| [Generate reports on permission<br/>levels of users](admin_area.md#user-permission-export) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Generate a report listing all users' access permissions for groups and projects in the instance. |
+| [License approval policies](../user/compliance/license_approval_policies.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Search dependencies for their licenses. This lets you determine if the licenses of your project's dependencies are compatible with your project's license. |
+| [Lock project membership to group](../user/group/access_and_permissions.md#prevent-members-from-being-added-to-projects-in-a-group) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Group owners can prevent new members from being added to projects in a group. |
+| [LDAP group sync](auth/ldap/ldap_synchronization.md#group-sync) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Automatically synchronize groups and manage SSH keys, permissions, and authentication, so you can focus on building your product, not configuring your tools. |
+| [LDAP group sync filters](auth/ldap/ldap_synchronization.md#group-sync) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Gives more flexibility to synchronize with LDAP based on filters, meaning you can leverage LDAP attributes to map GitLab permissions. |
+| [Linux package installations support<br/>log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-forwarding) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Forward your logs to a central system. |
+| [Restrict SSH Keys](../security/ssh_keys_restrictions.md) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Control the technology and key length of SSH keys used to access GitLab. |
diff --git a/doc/administration/configure.md b/doc/administration/configure.md
index 3ccf3c4929d8d23014c771a5f7fc84cfadb7c141..959487bc4c04496ad9fda7854a331dcd7a42f28c 100644
--- a/doc/administration/configure.md
+++ b/doc/administration/configure.md
@@ -1,14 +1,17 @@
---
stage: Systems
group: Distribution
-description: Configuration settings.
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
+description: Configuration settings.
title: Configure GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Customize and configure GitLab Self-Managed.
diff --git a/doc/administration/consul.md b/doc/administration/consul.md
index 80ae1f2b12f19c70577b3ef970ca571fa578a934..d685749aa0bd4bffe5cd119ee280ce5e238c8585 100644
--- a/doc/administration/consul.md
+++ b/doc/administration/consul.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: How to set up Consul
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
A Consul cluster consists of both
[server and client agents](https://developer.hashicorp.com/consul/docs/agent).
@@ -126,9 +129,9 @@ Below are some examples of TLS encryption.
In the following example, the server uses TLS for incoming connections (without client TLS authentication).
-::Tabs
+{{< tabs >}}
-:::TabTitle Consul server node
+{{< tab title="Consul server node" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -151,7 +154,9 @@ In the following example, the server uses TLS for incoming connections (without
sudo gitlab-ctl reconfigure
```
-:::TabTitle Consul client node
+{{< /tab >}}
+
+{{< tab title="Consul client node" >}}
The following can be configured on a Patroni node for example.
@@ -173,15 +178,17 @@ The following can be configured on a Patroni node for example.
Patroni talks to the local Consul agent which does not use TLS for incoming
connections. Hence the HTTP URL for `patroni['consul']['url']`.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Default TLS support
In the following example, the server uses mutual TLS authentication.
-::Tabs
+{{< tabs >}}
-:::TabTitle Consul server node
+{{< tab title="Consul server node" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -203,7 +210,9 @@ In the following example, the server uses mutual TLS authentication.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Consul client node
+{{< /tab >}}
+
+{{< tab title="Consul client node" >}}
The following can be configured on a Patroni node for example.
@@ -228,7 +237,9 @@ Patroni talks to the local Consul agent which does not use TLS for incoming
connections, even though it uses TLS authentication to Consul server nodes.
Hence the HTTP URL for `patroni['consul']['url']`.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Full TLS support
@@ -237,9 +248,9 @@ In the following example, both client and server use mutual TLS authentication.
The Consul server, client, and Patroni client certificates must be issued by the
same CA for mutual TLS authentication to work.
-::Tabs
+{{< tabs >}}
-:::TabTitle Consul server node
+{{< tab title="Consul server node" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -261,7 +272,9 @@ same CA for mutual TLS authentication to work.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Consul client node
+{{< /tab >}}
+
+{{< tab title="Consul client node" >}}
The following can be configured on a Patroni node for example.
@@ -289,7 +302,9 @@ The following can be configured on a Patroni node for example.
sudo gitlab-ctl reconfigure
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Gossip encryption
diff --git a/doc/administration/credentials_inventory.md b/doc/administration/credentials_inventory.md
index 4f9b38eaf3d75d3177497efd5e06476cf6f013df..2b2dd608154f464080fc90a42c42b4f502e933d6 100644
--- a/doc/administration/credentials_inventory.md
+++ b/doc/administration/credentials_inventory.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Credentials inventory for GitLab Self-Managed
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
As a GitLab administrator, you are responsible for the overall security of your instance.
To assist, GitLab provides an inventory of all the credentials that can be used to access
diff --git a/doc/administration/custom_html_header_tags.md b/doc/administration/custom_html_header_tags.md
index 40a906965e63a652b0d69314f3b670711d9495bc..bfe645261052500b5ef3e06f8373562dc6a577d4 100644
--- a/doc/administration/custom_html_header_tags.md
+++ b/doc/administration/custom_html_header_tags.md
@@ -6,11 +6,18 @@ description: Learn how to modify the HTML header tags of your GitLab instance.
title: Custom HTML header tags
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153877) in GitLab 17.1.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153877) in GitLab 17.1.
+
+{{< /history >}}
If you self-manage a GitLab instance in the EU, or any jurisdiction that
requires a cookie consent banner, additional HTML header tags are needed to
@@ -38,9 +45,9 @@ must extend the `script_src` and `style_src`.
To add a custom HTML header tag:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add your configuration. For example:
@@ -61,7 +68,9 @@ To add a custom HTML header tag:
1. Save the file, and then [reconfigure](restart_gitlab.md#reconfigure-a-linux-package-installation) and [restart](restart_gitlab.md#restart-a-linux-package-installation) GitLab.
-:::TabTitle Self-compiled (Source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (Source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -87,4 +96,6 @@ To add a custom HTML header tag:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/administration/custom_project_templates.md b/doc/administration/custom_project_templates.md
index 8ada9879f61de931b0a4be98bf8236145f7d892f..b9f3eb1f5fbbf93c97f0f9e446b1057794ff74e6 100644
--- a/doc/administration/custom_project_templates.md
+++ b/doc/administration/custom_project_templates.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Configure project templates and make them available to all projects on your GitLab instance."
+description: Configure project templates and make them available to all projects on your GitLab instance.
title: Custom instance-level project templates
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
As an administrator, you can configure a group that contains projects available for
use as the source of project templates on your instance. You can then
diff --git a/doc/administration/dedicated/_index.md b/doc/administration/dedicated/_index.md
index 30bafa75639befddc70e746fb79e9421bf68d054..4baa6b56bec75dd17fea9ae6ee5cdb70871654f0 100644
--- a/doc/administration/dedicated/_index.md
+++ b/doc/administration/dedicated/_index.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Switchboard
-description: Get started with GitLab Dedicated.
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
+description: Get started with GitLab Dedicated.
title: Administer GitLab Dedicated
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
Use GitLab Dedicated to run GitLab on a fully-managed, single-tenant instance hosted on AWS. You maintain control over your instance configuration through Switchboard, the GitLab Dedicated management portal, while GitLab manages the underlying infrastructure.
diff --git a/doc/administration/dedicated/architecture.md b/doc/administration/dedicated/architecture.md
index eb14b5df04b0f42a3a829c1c6339ad7d492a78be..73a1ae290d696f6dae99e756c3432655d0d343ea 100644
--- a/doc/administration/dedicated/architecture.md
+++ b/doc/administration/dedicated/architecture.md
@@ -1,14 +1,17 @@
---
stage: SaaS Platforms
group: GitLab Dedicated
-description: Get to know the GitLab Dedicated architecture through a series of diagrams.
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
+description: Get to know the GitLab Dedicated architecture through a series of diagrams.
title: GitLab Dedicated architecture
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
This page provides a set of architectural documents and diagrams for GitLab Dedicated.
diff --git a/doc/administration/dedicated/configure_instance/_index.md b/doc/administration/dedicated/configure_instance/_index.md
index e2fe6750013e565c0916e5320eead2dfa631f28e..2834597d9c143197364a3ed46ef095ae72bb8b70 100644
--- a/doc/administration/dedicated/configure_instance/_index.md
+++ b/doc/administration/dedicated/configure_instance/_index.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Switchboard
-description: Configure your GitLab Dedicated instance with Switchboard.
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
+description: Configure your GitLab Dedicated instance with Switchboard.
title: Configure GitLab Dedicated
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
The instructions on this page guide you through configuring your GitLab Dedicated instance, including enabling and updating the settings for [available functionality](../../../subscriptions/gitlab_dedicated/_index.md#available-features).
@@ -18,9 +21,12 @@ As a GitLab-managed solution, you cannot change any GitLab functionality control
GitLab Dedicated engineers do not have direct access to your environment, except for [break glass situations](../../../subscriptions/gitlab_dedicated/_index.md#access-controls).
-NOTE:
+{{< alert type="note" >}}
+
An instance refers to a GitLab Dedicated deployment, whereas a tenant refers to a customer.
+{{< /alert >}}
+
## Configure your instance using Switchboard
You can use Switchboard to make limited configuration changes to your GitLab Dedicated instance.
@@ -59,9 +65,12 @@ When you apply changes immediately:
After the deployment job is complete, you receive an email notification. Check your spam folder if you do not see a notification in your main inbox.
All users with access to view or edit your tenant in Switchboard receive a notification for each change. For more information, see [Manage Switchboard notification preferences](../configure_instance/users_notifications.md#manage-notification-preferences).
-NOTE:
+{{< alert type="note" >}}
+
You only receive email notifications for changes made by a Switchboard tenant administrator. Changes made by a GitLab Operator (for example, a GitLab version update completed during a maintenance window) do not trigger email notifications.
+{{< /alert >}}
+
## Configuration change log
The **Configuration change log** page in Switchboard tracks changes made to your GitLab Dedicated instance.
@@ -107,5 +116,8 @@ Configuration changes requested with a [support ticket](https://support.gitlab.c
- May be postponed to the following week if GitLab needs to perform high-priority maintenance tasks.
- Can't be applied outside the weekly maintenance window unless they qualify for [emergency support](https://about.gitlab.com/support/#how-to-engage-emergency-support).
-NOTE:
+{{< alert type="note" >}}
+
Even if a change request meets the minimum lead time, it might not be applied during the upcoming maintenance window.
+
+{{< /alert >}}
diff --git a/doc/administration/dedicated/configure_instance/network_security.md b/doc/administration/dedicated/configure_instance/network_security.md
index 028af453674d28b93871df35eedcdf48390221c5..5e2e3cb188290a1e99965465b810db3aeb454860 100644
--- a/doc/administration/dedicated/configure_instance/network_security.md
+++ b/doc/administration/dedicated/configure_instance/network_security.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Switchboard
-description: Configure network access and security settings for GitLab Dedicated.
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
+description: Configure network access and security settings for GitLab Dedicated.
title: GitLab Dedicated network access and security
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
## Bring your own domain (BYOD)
@@ -127,8 +130,11 @@ Prerequisites:
- Add the ARN of the role that GitLab Dedicated uses to connect to your endpoint service to the Allowed Principals list on the Endpoint Service. You can find this ARN in Switchboard under Outbound private link IAM principal. For more information, see [Manage permissions](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions).
- Recommended. Set **Acceptance required** to **No** to enable GitLab Dedicated to connect in a single operation. If set to **Yes**, you must manually accept the connection after it's initiated.
- NOTE:
- If you set **Acceptance required** to **Yes**, Switchboard cannot accurately determine when the link is accepted. After you manually accept the link, the status shows as **Pending** instead of **Active** until next scheduled maintenance. After maintenance, the link status refreshes and shows as connected.
+ {{< alert type="note" >}}
+
+If you set **Acceptance required** to **Yes**, Switchboard cannot accurately determine when the link is accepted. After you manually accept the link, the status shows as **Pending** instead of **Active** until next scheduled maintenance. After maintenance, the link status refreshes and shows as connected.
+
+ {{< /alert >}}
- Once the endpoint service is created, note the Service Name and if you have enabled Private DNS or not.
@@ -145,9 +151,9 @@ Prerequisites:
1. Sign in to [Switchboard](https://console.gitlab-dedicated.com/).
1. At the top of the page, select **Configuration**.
1. Expand **Outbound private link**.
-1. Go to the outbound private link you want to delete, then select **Delete** (**{remove}**).
+1. Go to the outbound private link you want to delete, then select **Delete** ({{< icon name="remove" >}}).
1. Select **Delete**.
-1. Optional. To delete all the links in a region, from the region header, select **Delete** (**{remove}**). This also deletes the region configuration.
+1. Optional. To delete all the links in a region, from the region header, select **Delete** ({{< icon name="remove" >}}). This also deletes the region configuration.
#### Add an outbound private link with a support request
diff --git a/doc/administration/dedicated/configure_instance/saml.md b/doc/administration/dedicated/configure_instance/saml.md
index 2425fa292846e0ac296c67eefe62193999a166aa..89b1c2e8c12958624db241c595f94860e5a26c92 100644
--- a/doc/administration/dedicated/configure_instance/saml.md
+++ b/doc/administration/dedicated/configure_instance/saml.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Switchboard
-description: Configure SAML single sign-on (SSO) authentication for GitLab Dedicated.
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
+description: Configure SAML single sign-on (SSO) authentication for GitLab Dedicated.
title: SAML single sign-on for GitLab Dedicated
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
You can [configure SAML single sign-on (SSO)](../../../integration/saml.md#configure-saml-support-in-gitlab) for your GitLab Dedicated instance. Optionally, you can configure more than one SAML identity provider (IdP).
@@ -23,9 +26,12 @@ Prerequisites:
- You must [set up the identity provider](../../../integration/saml.md#set-up-identity-providers) before you can configure SAML for GitLab Dedicated.
- To configure GitLab to sign SAML authentication requests, you must create a private key and public certificate pair for your GitLab Dedicated instance.
-NOTE:
+{{< alert type="note" >}}
+
You can only configure one SAML IdP with Switchboard. If you configured a SAML IdP on your GitLab Dedicated instance before the introduction of support for multiple IdPs, you can manage that provider through Switchboard. To configure additional SAML IdPs, [submit a support request](#activate-saml-with-a-support-request).
+{{< /alert >}}
+
## Activate SAML with Switchboard
To activate SAML for your GitLab Dedicated instance:
@@ -104,9 +110,12 @@ If you are unable to use Switchboard to activate or update SAML for your GitLab
If [SAML request signing](../../../integration/saml.md#sign-saml-authentication-requests-optional) is desired, a certificate must be obtained. This certificate can be self-signed which has the advantage of not having to prove ownership of an arbitrary Common Name (CN) to a public Certificate Authority (CA).
-NOTE:
+{{< alert type="note" >}}
+
Because SAML request signing requires certificate signing, you must complete these steps to use SAML with this feature enabled.
+{{< /alert >}}
+
To enable SAML request signing:
1. Open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) and indicate that you want request signing enabled.
diff --git a/doc/administration/dedicated/configure_instance/users_notifications.md b/doc/administration/dedicated/configure_instance/users_notifications.md
index fc76d26c812824e7790a15ebcfd7a4e7d08a0eb1..6b062e71830860573978aa2049836a9cd6cda8d2 100644
--- a/doc/administration/dedicated/configure_instance/users_notifications.md
+++ b/doc/administration/dedicated/configure_instance/users_notifications.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Switchboard
-description: Manage Switchboard users and configure notification preferences, including SMTP email service settings.
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
+description: Manage Switchboard users and configure notification preferences, including SMTP email service settings.
title: GitLab Dedicated users and notifications
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
## Add Switchboard users
diff --git a/doc/administration/dedicated/create_instance.md b/doc/administration/dedicated/create_instance.md
index ef4fbe8d2f1041f6089e07234315823fd033249a..e46caf44fb1f357247a751257a9a1e662f01a753 100644
--- a/doc/administration/dedicated/create_instance.md
+++ b/doc/administration/dedicated/create_instance.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Switchboard
-description: Create your GitLab Dedicated instance with Switchboard.
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
+description: Create your GitLab Dedicated instance with Switchboard.
title: Create your GitLab Dedicated instance
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
The instructions on this page guide you through the onboarding and initial setup of your GitLab Dedicated instance using [Switchboard](https://about.gitlab.com/direction/saas-platforms/switchboard/), the GitLab Dedicated portal.
@@ -35,9 +38,12 @@ complete your onboarding to create a new instance.
### Encrypted Data At Rest (BYOK)
-NOTE:
+{{< alert type="note" >}}
+
To enable BYOK, you must do it before onboarding. If enabled, it is not possible to later disable BYOK.
+{{< /alert >}}
+
You can opt to encrypt your GitLab data at rest with AWS KMS keys, which must be made accessible to GitLab Dedicated infrastructure. Due to key rotation requirements, GitLab Dedicated only supports keys with AWS-managed key material (the [AWS_KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-origin) origin type).
Encryption for data in motion (moving over a network) is performed with TLS using keys generated and managed by GitLab Dedicated components, and is not covered by BYOK.
@@ -185,9 +191,12 @@ information required to create your GitLab Dedicated instance.
1. Summary: Confirm that the information you've provided in the previous steps is accurate
before initiating the creation of your instance.
-NOTE:
+{{< alert type="note" >}}
+
Some configuration settings (like the option to bring your own keys and your tenant name) are permanent and cannot be changed once your instance has been created.
+{{< /alert >}}
+
It can take up to 3 hours to create the GitLab Dedicated instance. When the setup is complete, you will receive a confirmation email.
## Step 3: Access and configure your GitLab Dedicated instance
@@ -198,8 +207,11 @@ To access and configure your GitLab Dedicated instance:
1. In the **Access your GitLab Dedicated instance** banner, select **View credentials**.
1. Copy the tenant URL and temporary root credentials for your instance.
- NOTE:
- For security, you can retrieve the temporary root credentials from Switchboard only once. Be sure to store these credentials securely (for example, in a password manager) before leaving Switchboard.
+ {{< alert type="note" >}}
+
+For security, you can retrieve the temporary root credentials from Switchboard only once. Be sure to store these credentials securely (for example, in a password manager) before leaving Switchboard.
+
+ {{< /alert >}}
1. Go to the tenant URL for your GitLab Dedicated instance and sign in with your temporary root credentials.
1. [Change your temporary root password](../../user/profile/user_passwords.md#change-your-password) to a new secure password.
@@ -216,5 +228,8 @@ Also plan ahead if you need the following GitLab Dedicated features:
To view all available infrastructure configuration options, see [Configure your GitLab Dedicated instance](../dedicated/configure_instance/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
New GitLab Dedicated instances use the same default settings as GitLab Self-Managed. A GitLab administrator can change these settings from the [Admin Area](../admin_area.md).
+
+{{< /alert >}}
diff --git a/doc/administration/dedicated/hosted_runners.md b/doc/administration/dedicated/hosted_runners.md
index 13a1ca70e16cd24ce4734dbb60d755025d484c0f..9f3ce1323f08d7d657120222dec0a1420c4c282f 100644
--- a/doc/administration/dedicated/hosted_runners.md
+++ b/doc/administration/dedicated/hosted_runners.md
@@ -1,19 +1,25 @@
---
stage: Verify
group: Hosted Runners
-description: Use hosted runners to run your CI/CD jobs on GitLab Dedicated.
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
+description: Use hosted runners to run your CI/CD jobs on GitLab Dedicated.
title: Hosted runners for GitLab Dedicated
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
-**Status:** Limited availability
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+- Status: Limited availability
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
To use this feature, you must purchase a subscription for Hosted Runners for GitLab Dedicated. To participate in the limited availability of Hosted Runners for Dedicated, reach out to your Customer Success Manager or Account representative.
+{{< /alert >}}
+
You can run your CI/CD jobs on GitLab-hosted [runners](../../ci/runners/_index.md). These runners are managed by GitLab and fully integrated with your GitLab Dedicated instance.
GitLab-hosted runners for Dedicated are autoscaling [instance runners](../../ci/runners/runners_scope.md#instance-runners),
running on AWS EC2 in the same region as the GitLab Dedicated instance.
@@ -53,9 +59,12 @@ The following machine types are available for hosted runners on Linux Arm64.
| X-Large | `linux-xlarge-arm64` | 16 | 64 GB | 200 GB |
| 2X-Large | `linux-2xlarge-arm64` | 32 | 128 GB | 200 GB |
-NOTE:
+{{< alert type="note" >}}
+
The machine type and underlying processor type might change. Jobs optimized for a specific processor design might behave inconsistently.
+{{< /alert >}}
+
Default runner tags are assigned upon creation. Administrators can subsequently [modify the tag settings](#configure-hosted-runners-in-gitlab) for their instance runners.
### Container images
@@ -119,9 +128,12 @@ Prerequisites:
- You must be an administrator.
-NOTE:
+{{< alert type="note" >}}
+
Compute usage visualizations are not available, but an [epic](https://gitlab.com/groups/gitlab-com/gl-infra/gitlab-dedicated/-/epics/524) exists to add them for general availability.
+{{< /alert >}}
+
To view hosted runners in GitLab:
1. On the left sidebar, at the bottom, select **Admin**.
@@ -141,9 +153,12 @@ Available configuration options include:
- [Change the maximum job timeout](../../ci/runners/configure_runners.md#for-an-instance-runner).
- [Set the runner to run tagged or untagged jobs](../../ci/runners/configure_runners.md#for-an-instance-runner-2).
-NOTE:
+{{< alert type="note" >}}
+
Any changes to the runner description and the runner tags are not controlled by GitLab.
+{{< /alert >}}
+
### Disable hosted runners for groups or projects in GitLab
By default, hosted runners are available for all projects and groups in your GitLab Dedicated instance.
diff --git a/doc/administration/dedicated/maintenance.md b/doc/administration/dedicated/maintenance.md
index 82f4a7a050420d5639cb9a3fde3e09ddf230fc90..05e91e072565604de5799c72a48c433b7aa8bc9f 100644
--- a/doc/administration/dedicated/maintenance.md
+++ b/doc/administration/dedicated/maintenance.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Environment Automation
-description: Maintenance windows, release schedules, and emergency maintenance processes for GitLab Dedicated instances.
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
+description: Maintenance windows, release schedules, and emergency maintenance processes for GitLab Dedicated instances.
title: GitLab Dedicated maintenance and release schedule
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
GitLab performs regular maintenance to your GitLab Dedicated instance. This page outlines the maintenance windows and release upgrade schedule.
@@ -25,9 +28,12 @@ Maintenance is performed outside standard working hours:
View your maintenance window in [Switchboard](tenant_overview.md#maintenance-windows), including upcoming and recent maintenance. You can postpone scheduled maintenance to another window in the same week by contacting your Customer Success Manager at least one week in advance.
-NOTE:
+{{< alert type="note" >}}
+
The scheduled weekly maintenance window is separate from [emergency maintenance](#emergency-maintenance), which cannot be postponed.
+{{< /alert >}}
+
### Access during maintenance
Downtime is not expected for the entire duration of your maintenance window. A brief service interruption (less than one minute) may occur when compute resources restart after upgrades, typically during the first half of the maintenance window.
@@ -36,9 +42,12 @@ Long-running connections may be interrupted during this period. To minimize disr
Longer service interruptions are rare. If extended downtime is expected, GitLab provides advance notice.
-NOTE:
+{{< alert type="note" >}}
+
Performance degradation or downtime during the scheduled maintenance window does not count against [the system Service Level Availability](https://handbook.gitlab.com/handbook/engineering/infrastructure/team/gitlab-dedicated/slas/).
+{{< /alert >}}
+
## Release rollout schedule
GitLab Dedicated is [upgraded](../../subscriptions/gitlab_dedicated/maintenance.md#upgrades-and-patches) to the previous minor version (`N-1`) after each GitLab release. For example, when GitLab 16.9 is released, GitLab Dedicated instances are upgraded to 16.8.
@@ -53,9 +62,12 @@ Upgrades occur in your selected [maintenance window](#maintenance-windows) accor
For example, GitLab 16.9 released on 2024-02-15. Instances in the EMEA and Americas (Option 1) regions were then upgraded to 16.8 on 2024-02-20, 5 days after the 16.9 release.
-NOTE:
+{{< alert type="note" >}}
+
If a production change lock (PCL) is active during a scheduled upgrade, GitLab defers the upgrade to the first maintenance window after the PCL ends. For more information, including upcoming and current PCL periods, see [Production Change Lock](https://handbook.gitlab.com/handbook/engineering/infrastructure/team/gitlab-dedicated/#production-change-lock-pcl).
+{{< /alert >}}
+
## Emergency maintenance
In an event of a platform outage, degradation, or a security event requiring urgent action,
diff --git a/doc/administration/dedicated/monitor.md b/doc/administration/dedicated/monitor.md
index fbb42b90261d5cad4c92d4464d801c7dc27858fe..09d0ff728f984b43403e97a31a0b02e9a8750a3d 100644
--- a/doc/administration/dedicated/monitor.md
+++ b/doc/administration/dedicated/monitor.md
@@ -1,8 +1,8 @@
---
stage: GitLab Dedicated
group: Switchboard
-description: Access application logs and S3 bucket data to monitor your GitLab Dedicated instance.
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
+description: Access application logs and S3 bucket data to monitor your GitLab Dedicated instance.
title: Monitor your GitLab Dedicated instance
---
@@ -17,8 +17,11 @@ To gain read only access to the S3 bucket with your application logs:
1. Open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) with the title `Customer Log Access`.
1. In the body of the ticket, include a list of IAM Principal Amazon Resource Names (ARNs) that require access to the logs from the S3 bucket. The ARNs can be for users or roles.
- NOTE:
- Specify the full ARN path without wildcards (`*`). Wildcard characters are not supported. GitLab team members can read more about the proposed feature to add wildcard support in this confidential issue: [7010](https://gitlab.com/gitlab-com/gl-infra/gitlab-dedicated/team/-/issues/7010).
+ {{< alert type="note" >}}
+
+Specify the full ARN path without wildcards (`*`). Wildcard characters are not supported. GitLab team members can read more about the proposed feature to add wildcard support in this confidential issue: [7010](https://gitlab.com/gitlab-com/gl-infra/gitlab-dedicated/team/-/issues/7010).
+
+ {{< /alert >}}
GitLab provides the name of the S3 bucket. Your authorized users or roles can then access all objects in the bucket. To verify access, you can use the [AWS CLI](https://aws.amazon.com/cli/).
diff --git a/doc/administration/dedicated/tenant_overview.md b/doc/administration/dedicated/tenant_overview.md
index b2ce500b1accc033a55542e0c8d7eb69647604fb..16b173814ede2dd881abde944e3a8a100f8b0395 100644
--- a/doc/administration/dedicated/tenant_overview.md
+++ b/doc/administration/dedicated/tenant_overview.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Switchboard
-description: View information about your GitLab Dedicated instance with Switchboard.
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
+description: View information about your GitLab Dedicated instance with Switchboard.
title: View GitLab Dedicated instance details
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
Monitor your GitLab Dedicated instance details, maintenance windows, and configuration status in Switchboard.
@@ -47,9 +50,12 @@ The **Maintenance windows** section displays the:
- Most recent emergency maintenance window (if applicable)
- Upcoming GitLab version upgrade
-NOTE:
+{{< alert type="note" >}}
+
Each Sunday night in UTC, Switchboard updates to display the planned GitLab version upgrades for the upcoming week's maintenance windows. For more information, see [Maintenance windows](../dedicated/maintenance.md#maintenance-windows).
+{{< /alert >}}
+
## Hosted runners
The **Hosted runners** section shows the [hosted runners](../dedicated/hosted_runners.md) associated with your instance.
diff --git a/doc/administration/diff_limits.md b/doc/administration/diff_limits.md
index 392ddaa784e67cb472024ae02595f08ec9082d89..a5c79767d92553a53d78c6525d7a5014ea893ffd 100644
--- a/doc/administration/diff_limits.md
+++ b/doc/administration/diff_limits.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Configure the maximum diff size to display on GitLab Self-Managed."
+description: Configure the maximum diff size to display on GitLab Self-Managed.
title: Diff limits administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can set a maximum size for display of diff files (patches).
@@ -17,10 +20,13 @@ Read more about the [built-in limits for merge requests and diffs](instance_limi
## Configure diff limits
-WARNING:
+{{< alert type="warning" >}}
+
These settings are experimental. An increased maximum increases resource
consumption of your instance. Keep this in mind when adjusting the maximum.
+{{< /alert >}}
+
To speed the loading of merge request views and branch comparison views
on your instance, configure these maximum values for diffs:
diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md
index 32e471e62975a0293914eb6503ab93f1524a39ab..c367ede0baa7ab42d273fcee25dd1f684eec59ec 100644
--- a/doc/administration/docs_self_host.md
+++ b/doc/administration/docs_self_host.md
@@ -5,19 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Host the GitLab product documentation
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you are not able to access the GitLab product documentation at `docs.gitlab.com`,
you can host the documentation yourself instead.
-NOTE:
+{{< alert type="note" >}}
+
The local help of your instance does not include all the docs (for example, it
doesn't include docs for GitLab Runner or GitLab Operator), and it's not
searchable or browsable. It's intended to only support direct links to specific
pages from within your instance.
+{{< /alert >}}
+
## Documentation self-hosting options
To host the GitLab product documentation, you can use:
@@ -114,12 +120,15 @@ To host the product documentation site with GitLab Pages:
### Self-host the product documentation on your own web server
-NOTE:
+{{< alert type="note" >}}
+
The website you create must be hosted under a subdirectory that matches
your installed GitLab version (for example, `17.8/`). The
[Docker images](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/container_registry/8244403)
use this version by default.
+{{< /alert >}}
+
Because the product documentation site is static, you can take the contents of
`/usr/share/nginx/html` from inside the container, and use your own web server to host
the documentation wherever you want.
diff --git a/doc/administration/duo_add_on_seat_management_with_ldap.md b/doc/administration/duo_add_on_seat_management_with_ldap.md
index 6a8e6d48e147938a37ce4c6580026b60a478eecf..2a0b8d1abc955b0735957ad10d643c350e1ee80f 100644
--- a/doc/administration/duo_add_on_seat_management_with_ldap.md
+++ b/doc/administration/duo_add_on_seat_management_with_ldap.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Duo add-on seat management with LDAP
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175101) in GitLab 17.8.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175101) in GitLab 17.8.
+
+{{< /history >}}
GitLab administrators can configure automatic GitLab Duo add-on seat assignment based on LDAP group membership. When enabled, GitLab will automatically assign or remove add-on seats for users when they sign in, depending on their LDAP group memberships.
diff --git a/doc/administration/email_from_gitlab.md b/doc/administration/email_from_gitlab.md
index 20da07fb8e357714dd6f907accb8becedd447ec8..eb6acdf04c50fdc0102e0b243d30d5646ac4d50a 100644
--- a/doc/administration/email_from_gitlab.md
+++ b/doc/administration/email_from_gitlab.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Email from GitLab
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Administrators can email all users, or users of a chosen group or project.
Users receive the email at their primary email address.
@@ -29,7 +32,7 @@ To send an email:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
-1. In the upper-right corner, select **Send email to users** (**{mail}**).
+1. In the upper-right corner, select **Send email to users** ({{< icon name="mail" >}}).
1. Complete the fields. The email body supports only plain text and does not support HTML, Markdown, or other rich text formats.
1. From the **Select group or project** dropdown list, select the recipient.
1. Select **Send message**.
diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md
index edece58ba723a0b2b71770b235ec599f615aa5a3..b99f47ca237d9a27934c9d2205adea8847be8b20 100644
--- a/doc/administration/encrypted_configuration.md
+++ b/doc/administration/encrypted_configuration.md
@@ -1,13 +1,16 @@
---
stage: Systems
group: Distribution
-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"
+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
title: Encrypted Configuration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab can read settings for certain features from encrypted settings files. The supported features are:
diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md
index fc02826caf91316d37d50d641c7412ec2654ad0b..63d3f4d9ed8446d30d7a7cc7e47b719266425190 100644
--- a/doc/administration/environment_variables.md
+++ b/doc/administration/environment_variables.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Environment variables
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab exposes certain environment variables which can be used to override
their defaults values.
diff --git a/doc/administration/external_users.md b/doc/administration/external_users.md
index a669403eb09412ed986c11d2fe1bb7b4182ea670..dda8621c5c3a606d835b875535f43dc733f3f9ef 100644
--- a/doc/administration/external_users.md
+++ b/doc/administration/external_users.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: External users
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
In cases where it is desired that a user has access only to some internal or
private projects, there is the option of creating **External Users**. This
@@ -32,9 +35,12 @@ always take into account the
[project's visibility](../user/public_access.md#change-project-visibility) and [permissions settings](../user/project/settings/_index.md#configure-project-features-and-permissions)
as well as the permission level of the user.
-NOTE:
+{{< alert type="note" >}}
+
External users still count towards a license seat, unless the user has the [Guest role](../subscriptions/self_managed/_index.md#free-guest-users) in the Ultimate tier.
+{{< /alert >}}
+
An administrator can flag a user as external by either of the following methods:
- [Through the API](../api/users.md#modify-a-user).
diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md
index b27cd2be340bcfc9f30f78213ec8bbbded142330..ae7f9724fa28f6823a82de13b55c0cbbfdeaca94 100644
--- a/doc/administration/feature_flags.md
+++ b/doc/administration/feature_flags.md
@@ -2,13 +2,16 @@
stage: Systems
group: Distribution
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
-description: "GitLab administrator: enable and disable GitLab features deployed behind feature flags"
+description: 'GitLab administrator: enable and disable GitLab features deployed behind feature flags'
title: Enable and disable GitLab features deployed behind feature flags
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab adopted [feature flags strategies](../development/feature_flags/_index.md)
to deploy features in an early stage of development so that they can be
@@ -46,9 +49,12 @@ GitLab, the feature flag status may change.
Before enabling a disabled feature flag in a production GitLab environment, it is crucial to understand the potential risks involved.
-WARNING:
+{{< alert type="warning" >}}
+
Data corruption, stability degradation, performance degradation, and security issues may occur if you enable a feature that's disabled by default.
+{{< /alert >}}
+
Features that are disabled by default may change or be removed without notice in a future version of GitLab.
Features behind default-disabled feature flags are not recommended for use in a production environment
diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md
index c6e023838758827d4a50e3a05996f5d6571c30c9..c9acd5d2c1047adb5845f56b3c82f5caf4483e73 100644
--- a/doc/administration/file_hooks.md
+++ b/doc/administration/file_hooks.md
@@ -1,13 +1,16 @@
---
stage: Foundations
group: Import and Integrate
-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"
+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
title: File hooks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Use custom file hooks (not to be confused with [server hooks](server_hooks.md) or [system hooks](system_hooks.md)),
to introduce custom integrations without modifying the GitLab source code.
@@ -17,12 +20,15 @@ in a file hook's code, and create many file hooks as you need. Each file hook is
triggered by GitLab asynchronously in case of an event. For a list of events,
see the [system hooks](system_hooks.md) and [webhooks](../user/project/integrations/webhook_events.md) documentation.
-NOTE:
+{{< alert type="note" >}}
+
File hooks must be configured on the file system of the GitLab server. Only GitLab
server administrators can complete these tasks. Explore
[system hooks](system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md)
as an option if you do not have file system access.
+{{< /alert >}}
+
Instead of writing and supporting your own file hook, you can also make changes
directly to the GitLab source code and contribute back upstream. In this way, we can
ensure functionality is preserved across versions and covered by tests.
diff --git a/doc/administration/geo/_index.md b/doc/administration/geo/_index.md
index 5189e1341a1d4e6fed54fa0d3e5788577f4eec7a..8bd704384adedbe15a15d569b763140ced9b71ff 100644
--- a/doc/administration/geo/_index.md
+++ b/doc/administration/geo/_index.md
@@ -5,18 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Geo is the solution for widely distributed development teams and for providing
a warm-standby as part of a disaster recovery strategy. Geo is **not** an out of the box HA solution.
-WARNING:
+{{< alert type="warning" >}}
+
Geo undergoes significant changes from release to release. Upgrades are
supported and [documented](#upgrading-geo), but you should ensure that you're
using the right version of the documentation for your installation.
+{{< /alert >}}
+
To make sure you're using the right version of the documentation, go to [the Geo page on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/administration/geo/_index.md) and choose the appropriate release from the **Switch branch/tag** dropdown list. For example, [`v15.7.6-ee`](https://gitlab.com/gitlab-org/gitlab/-/blob/v15.7.6-ee/doc/administration/geo/_index.md).
Fetching large repositories can take a long time for teams and runners located far from a single GitLab instance.
@@ -216,16 +222,23 @@ The following table lists basic ports that must be open between the **primary**
See the full list of ports used by GitLab in [Package defaults](../package_information/defaults.md)
-NOTE:
+{{< alert type="note" >}}
+
[Web terminal](../../ci/environments/_index.md#web-terminals-deprecated) support requires your load balancer to correctly handle WebSocket connections.
When using HTTP or HTTPS proxying, your load balancer must be configured to pass through the `Connection` and `Upgrade` hop-by-hop headers. See the [web terminal](../integration/terminal.md) integration guide for more details.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
When using HTTPS protocol for port 443, you must add an SSL certificate to the load balancers.
If you wish to terminate SSL at the GitLab application server instead, use TCP protocol.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
If you are only using `HTTPS` for external/internal URLs, it is not necessary to open port 80 in the firewall.
+{{< /alert >}}
#### Internal URL
@@ -263,9 +276,12 @@ This new architecture allows GitLab to be resilient to connectivity issues betwe
## Known issues
-WARNING:
+{{< alert type="warning" >}}
+
These known issues reflect only the latest version of GitLab. If you are using an older version, additional issues might exist.
+{{< /alert >}}
+
- Pushing directly to a **secondary** site redirects (for HTTP) or proxies (for SSH) the request to the **primary** site instead of [handling it directly](https://gitlab.com/gitlab-org/gitlab/-/issues/1381). You cannot use Git over HTTP with credentials embedded in the URI, for example, `https://user:personal-access-token@secondary.tld`. For more information, see how to [use a Geo Site](replication/usage.md).
- The **primary** site has to be online for OAuth login to happen. Existing sessions and Git are not affected. Support for the **secondary** site to use an OAuth provider independent from the primary is [being planned](https://gitlab.com/gitlab-org/gitlab/-/issues/208465).
- The installation takes multiple manual steps that together can take about an hour depending on circumstances. Consider using the
diff --git a/doc/administration/geo/disaster_recovery/_index.md b/doc/administration/geo/disaster_recovery/_index.md
index dc98052328dfd25ec7a8de295b45e4152f81abdb..f25c8445be6a31b67e57c2bf5c869eb3fd110849 100644
--- a/doc/administration/geo/disaster_recovery/_index.md
+++ b/doc/administration/geo/disaster_recovery/_index.md
@@ -5,17 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Disaster Recovery (Geo)
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Geo replicates your database, your Git repositories, and other assets.
Some [known issues](../_index.md#known-issues) exist.
-WARNING:
+{{< alert type="warning" >}}
+
Multi-secondary configurations require the complete re-synchronization and re-configuration of all non-promoted secondaries and
causes downtime.
+{{< /alert >}}
+
## Promoting a **secondary** Geo site in single-secondary configurations
While you can't automatically promote a Geo replica and do a failover,
@@ -33,11 +39,14 @@ order to avoid unnecessary data loss.
### Step 2. Permanently disable the **primary** site
-WARNING:
+{{< alert type="warning" >}}
+
If the **primary** site goes offline, there may be data saved on the **primary** site
that have not been replicated to the **secondary** site. This data should be treated
as lost if you proceed.
+{{< /alert >}}
+
If an outage on the **primary** site happens, you should do everything possible to
avoid a split-brain situation where writes can occur in two different GitLab
instances, complicating recovery efforts. So to prepare for the failover, we
@@ -72,8 +81,11 @@ must disable the **primary** site.
If you plan to [update the primary domain DNS record](#step-4-optional-updating-the-primary-domain-dns-record),
you may wish to maintain a low TTL to ensure fast propagation of DNS changes.
- NOTE:
- The primary site's `/etc/gitlab/gitlab.rb` file is not copied to the secondary sites automatically during this process. Make sure that you back up the primary's `/etc/gitlab/gitlab.rb` file, so that you can later restore any needed values on your secondary sites.
+ {{< alert type="note" >}}
+
+The primary site's `/etc/gitlab/gitlab.rb` file is not copied to the secondary sites automatically during this process. Make sure that you back up the primary's `/etc/gitlab/gitlab.rb` file, so that you can later restore any needed values on your secondary sites.
+
+ {{< /alert >}}
### Step 3. Promoting a **secondary** site
@@ -270,10 +282,13 @@ changing Git remotes and API URLs.
external_url 'https://<new_external_url>'
```
- NOTE:
- Changing `external_url` does not prevent access through the old secondary URL, as
+ {{< alert type="note" >}}
+
+Changing `external_url` does not prevent access through the old secondary URL, as
long as the secondary DNS records are still intact.
+ {{< /alert >}}
+
1. Update the **secondary**'s SSL certificate:
- If you use the [Let's Encrypt integration](https://docs.gitlab.com/omnibus/settings/ssl/#enable-the-lets-encrypt-integration),
@@ -409,11 +424,14 @@ The following sections assume you are using the `gitlab` namespace. If you used
### Step 1. Permanently disable the **primary** cluster
-WARNING:
+{{< alert type="warning" >}}
+
If the **primary** site goes offline, there may be data saved on the **primary** site
that has not been replicated to the **secondary** site. This data should be treated
as lost if you proceed.
+{{< /alert >}}
+
If an outage on the **primary** site happens, you should do everything possible to
avoid a split-brain situation where writes can occur in two different GitLab
instances, complicating recovery efforts. So to prepare for the failover, you
@@ -440,11 +458,14 @@ must disable the **primary** site:
### Step 2. Promote all **secondary** site nodes external to the cluster
-WARNING:
+{{< alert type="warning" >}}
+
If the secondary site [has been paused](../../geo/_index.md#pausing-and-resuming-replication), this performs
a point-in-time recovery to the last known state.
Data that was created on the primary while the secondary was paused is lost.
+{{< /alert >}}
+
1. For each node (such as PostgreSQL or Gitaly) outside of the **secondary** Kubernetes cluster using the Linux
package, SSH into the node and run one of the following commands:
diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md
index a4b7b726d09160c9bc8230248f0339a6f6327dbc..05a72e20152e9d42d7b7336a3bc292de01b9dad7 100644
--- a/doc/administration/geo/disaster_recovery/background_verification.md
+++ b/doc/administration/geo/disaster_recovery/background_verification.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Automatic background verification
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Automatic background verification ensures that the transferred data matches a
calculated checksum. If the checksum of the data on the **primary** site matches checksum of the
diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md
index 8af9a7c5d00e98536f2d4456f40e1c6acbb6c937..fed8326693b588cb1c7f15f0436045e2bc301432 100644
--- a/doc/administration/geo/disaster_recovery/bring_primary_back.md
+++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Bring a demoted primary site back online
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
After a failover, it is possible to fail back to the demoted **primary** site to
restore your original configuration. This process consists of two steps:
@@ -15,9 +18,12 @@ restore your original configuration. This process consists of two steps:
1. Making the old **primary** site a **secondary** site.
1. Promoting a **secondary** site to a **primary** site.
-WARNING:
+{{< alert type="warning" >}}
+
If you have any doubts about the consistency of the data on this site, we recommend setting it up from scratch.
+{{< /alert >}}
+
## Configure the former **primary** site to be a **secondary** site
Since the former **primary** site is out of sync with the current **primary** site, the first step is to bring the former **primary** site up to date. Note, deletion of data stored on disk like
@@ -44,18 +50,23 @@ To bring the former **primary** site up to date:
sudo gitlab-ctl start
```
- NOTE:
- If you [disabled the **primary** site permanently](_index.md#step-2-permanently-disable-the-primary-site),
+ {{< alert type="note" >}}
+
+If you [disabled the **primary** site permanently](_index.md#step-2-permanently-disable-the-primary-site),
you need to undo those steps now. For distributions with systemd, such as Debian/Ubuntu/CentOS7+, you must run
`sudo systemctl enable gitlab-runsvdir`. For distributions without systemd, such as CentOS 6, you need to install
the GitLab instance from scratch and set it up as a **secondary** site by
following [Setup instructions](../setup/_index.md). In this case, you don't need to follow the next step.
- NOTE:
- If you [changed the DNS records](_index.md#step-4-optional-updating-the-primary-domain-dns-record)
+ {{< /alert >}}
+
+ {{< alert type="note" >}}
+
+If you [changed the DNS records](_index.md#step-4-optional-updating-the-primary-domain-dns-record)
for this site during disaster recovery procedure you may need to
[block all the writes to this site](planned_failover.md#prevent-updates-to-the-primary-site)
during this procedure.
+ {{< /alert >}}
1. [Set up Geo](../setup/_index.md). In this case, the **secondary** site
refers to the former **primary** site.
@@ -103,8 +114,12 @@ Use-cases:
### Skipping re-transfer of blobs or files
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352530) in GitLab 16.8 [with a flag](../../feature_flags.md) named `geo_skip_download_if_exists`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435788) in GitLab 16.9. Feature flag `geo_skip_download_if_exists` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352530) in GitLab 16.8 [with a flag](../../feature_flags.md) named `geo_skip_download_if_exists`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435788) in GitLab 16.9. Feature flag `geo_skip_download_if_exists` removed.
+
+{{< /history >}}
When you add a secondary site which has preexisting file data, then the secondary Geo site will avoid re-transferring that data. This applies to:
diff --git a/doc/administration/geo/disaster_recovery/failover_troubleshooting.md b/doc/administration/geo/disaster_recovery/failover_troubleshooting.md
index 2f522b44749c1d4909a93908ed76bdf1003b9353..33792469ae82596bfc9056c8e1a033936ec3cb11 100644
--- a/doc/administration/geo/disaster_recovery/failover_troubleshooting.md
+++ b/doc/administration/geo/disaster_recovery/failover_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Geo failover
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
## Fixing errors during a failover or when promoting a secondary to a primary site
diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md
index db2b15a66f4a308d92dfd3e8378d628befc907bb..f18224af3f846977cbf9d093bac744bae0ea46d5 100644
--- a/doc/administration/geo/disaster_recovery/planned_failover.md
+++ b/doc/administration/geo/disaster_recovery/planned_failover.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Disaster recovery for planned failover
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The primary use-case of Disaster Recovery is to ensure business continuity in
the event of unplanned outage, but it can be used in conjunction with a planned
diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md
index 5f0e70931ca8ac54415fc9157a384e9b28528c27..faadea1eb0d41c6b593ec4d458a44979ef74ae9e 100644
--- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md
+++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md
@@ -2,21 +2,26 @@
stage: Systems
group: Geo
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
-ignore_in_report: true
title: Disaster Recovery (Geo) promotion runbooks
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
Disaster Recovery (Geo) promotion runbooks.
-WARNING:
+{{< alert type="warning" >}}
+
This runbook is an [experiment](../../../../policy/development_stages_support.md#experiment). For complete, production-ready documentation, see the
[disaster recovery documentation](../_index.md).
+{{< /alert >}}
+
## Geo planned failover for a multi-node configuration
| Component | Configuration |
@@ -64,11 +69,14 @@ What is not covered:
### Preparation
-NOTE:
+{{< alert type="note" >}}
+
Before following any of those steps, make sure you have `root` access to the
**secondary** to promote it, because there isn't provided an automated way to
promote a Geo replica and perform a failover.
+{{< /alert >}}
+
On the **secondary** site:
1. On the left sidebar, at the bottom, select **Admin**.
@@ -99,10 +107,13 @@ follow these steps to avoid unnecessary data loss:
and make sure to stop any [background jobs](../../../maintenance_mode/_index.md#background-jobs).
1. Finish replicating and verifying all data:
- WARNING:
+ {{< alert type="warning" >}}
+
Not all data is automatically replicated. Read more about
[what is excluded](../planned_failover.md#not-all-data-is-automatically-replicated).
+ {{< /alert >}}
+
1. If you are manually replicating any
[data not managed by Geo](../../replication/datatypes.md#replicated-data-types),
trigger the final replication process now.
@@ -134,15 +145,21 @@ follow these steps to avoid unnecessary data loss:
1. In this final step, you must permanently disable the **primary** site.
- WARNING:
+ {{< alert type="warning" >}}
+
When the **primary** site goes offline, there may be data saved on the **primary** site
that has not been replicated to the **secondary** site. This data should be treated
as lost if you proceed.
- NOTE:
+ {{< /alert >}}
+
+ {{< alert type="note" >}}
+
If you plan to [update the **primary** domain DNS record](../_index.md#step-4-optional-updating-the-primary-domain-dns-record),
you may wish to lower the TTL now to speed up propagation.
+ {{< /alert >}}
+
When performing a failover, we want to avoid a split-brain situation where
writes can occur in two different GitLab instances. So to prepare for the
failover, you must disable the **primary** site:
@@ -159,17 +176,23 @@ follow these steps to avoid unnecessary data loss:
sudo systemctl disable gitlab-runsvdir
```
- NOTE:
+ {{< alert type="note" >}}
+
(**CentOS only**) In CentOS 6 or older, it is challenging to prevent GitLab from being
started if the machine reboots isn't available (see [issue 3058](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3058)).
It may be safest to uninstall the GitLab package completely with `sudo yum remove gitlab-ee`.
- NOTE:
+ {{< /alert >}}
+
+ {{< alert type="note" >}}
+
(**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu
or any other distribution based on the Upstart init system, you can prevent GitLab
from starting if the machine reboots as `root` with
`initctl stop gitlab-runsvvdir && echo 'manual' > /etc/init/gitlab-runsvdir.override && initctl reload-configuration`.
+ {{< /alert >}}
+
- If you do not have SSH access to the **primary** site, take the machine offline and
prevent it from rebooting. As there are many ways you may prefer to accomplish
this, we avoid a single recommendation. You may have to:
diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md
index b1b83b560922790508b6ec2e2da9cb8b9b4cbc67..bdf7c4a91236c70bbfed73b96bd520c9684cf9af 100644
--- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md
+++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md
@@ -2,21 +2,26 @@
stage: Systems
group: Geo
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
-ignore_in_report: true
title: Disaster Recovery (Geo) promotion runbooks
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
Disaster Recovery (Geo) promotion runbooks.
-WARNING:
+{{< alert type="warning" >}}
+
This runbook is an [experiment](../../../../policy/development_stages_support.md#experiment). For complete, production-ready documentation, see the
[disaster recovery documentation](../_index.md).
+{{< /alert >}}
+
## Geo planned failover for a single-node configuration
| Component | Configuration |
@@ -52,11 +57,14 @@ What is not covered:
### Preparation
-NOTE:
+{{< alert type="note" >}}
+
Before following any of those steps, make sure you have `root` access to the
**secondary** to promote it, since there isn't provided an automated way to
promote a Geo replica and perform a failover.
+{{< /alert >}}
+
On the **secondary** site, go to the **Admin area > Geo** dashboard to
review its status. Replicated objects (shown in green) should be close to 100%,
and there should be no failures (shown in red). If a large proportion of
@@ -128,10 +136,13 @@ follow these steps to avoid unnecessary data loss:
1. Finish replicating and verifying all data:
- WARNING:
+ {{< alert type="warning" >}}
+
Not all data is automatically replicated. Read more about
[what is excluded](../planned_failover.md#not-all-data-is-automatically-replicated).
+ {{< /alert >}}
+
1. If you are manually replicating any
[data not managed by Geo](../../replication/datatypes.md#replicated-data-types),
trigger the final replication process now.
@@ -163,15 +174,21 @@ follow these steps to avoid unnecessary data loss:
1. In this final step, you need to permanently disable the **primary** site.
- WARNING:
+ {{< alert type="warning" >}}
+
When the **primary** site goes offline, there may be data saved on the **primary** site
that has not been replicated to the **secondary** site. This data should be treated
as lost if you proceed.
- NOTE:
+ {{< /alert >}}
+
+ {{< alert type="note" >}}
+
If you plan to [update the **primary** domain DNS record](../_index.md#step-4-optional-updating-the-primary-domain-dns-record),
you may wish to lower the TTL now to speed up propagation.
+ {{< /alert >}}
+
When performing a failover, we want to avoid a split-brain situation where
writes can occur in two different GitLab instances. So to prepare for the
failover, you must disable the **primary** site:
@@ -188,17 +205,23 @@ follow these steps to avoid unnecessary data loss:
sudo systemctl disable gitlab-runsvdir
```
- NOTE:
+ {{< alert type="note" >}}
+
(**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being
started if the machine reboots isn't available (see [issue 3058](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3058)).
It may be safest to uninstall the GitLab package completely with `sudo yum remove gitlab-ee`.
- NOTE:
+ {{< /alert >}}
+
+ {{< alert type="note" >}}
+
(**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu
or any other distribution based on the Upstart init system, you can prevent GitLab
from starting if the machine reboots as `root` with
`initctl stop gitlab-runsvvdir && echo 'manual' > /etc/init/gitlab-runsvdir.override && initctl reload-configuration`.
+ {{< /alert >}}
+
- If you do not have SSH access to the **primary** site, take the machine offline and
prevent it from rebooting. Since there are many ways you may prefer to accomplish
this, we avoid a single recommendation. You may need to:
diff --git a/doc/administration/geo/glossary.md b/doc/administration/geo/glossary.md
index 1e3d7df9f504f95493c2ba7ed971765c1d44444e..6df06d3c33b4e857fb42baac04df4f2d489a2bea 100644
--- a/doc/administration/geo/glossary.md
+++ b/doc/administration/geo/glossary.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo glossary
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
We are updating the Geo documentation, user interface and commands to reflect these changes. Not all pages comply with
these definitions yet.
+{{< /alert >}}
+
These are the defined terms to describe all aspects of Geo. Using a set of clearly
defined terms helps us to communicate efficiently and avoids confusion. The language
on this page aims to be [ubiquitous](https://handbook.gitlab.com/handbook/communication/#ubiquitous-language)
diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md
index e59a1334f750e14ff820d8ba27474360e6bb4bca..4f33987f11bd40ca30c4cc1ec89f0e0c9e08ff2e 100644
--- a/doc/administration/geo/replication/configuration.md
+++ b/doc/administration/geo/replication/configuration.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure a new **secondary** site
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This is the final step in setting up a **secondary** Geo site. Stages of the
setup process must be completed in the documented order.
If not, [complete all prior stages](../setup/_index.md#using-linux-package-installations) before proceeding.
+{{< /alert >}}
+
The basic steps of configuring a **secondary** site are to:
1. Replicate required configurations between the **primary** and the **secondary** site.
@@ -29,11 +35,14 @@ Prerequisites for **both primary and secondary sites**:
- [Set up the database replication](../setup/database.md)
- [Configure fast lookup of authorized SSH keys](../../operations/fast_ssh_key_lookup.md)
-NOTE:
+{{< alert type="note" >}}
+
**Do not** set up any custom authentication for the **secondary** site. This is handled by the **primary** site.
Any change that requires access to the **Admin area** needs to be done in the
**primary** site because the **secondary** site is a read-only replica.
+{{< /alert >}}
+
## Step 1. Manually replicate secret GitLab values
GitLab stores a number of secret values in the `/etc/gitlab/gitlab-secrets.json`
@@ -170,8 +179,11 @@ In the following steps, replace `<ssh_host_key_path>` with the one you're using:
for file in <ssh_host_key_path>/ssh_host_*_key.pub; do ssh-keygen -lf $file; done
```
- NOTE:
- The output for private keys and public keys command should generate the same fingerprint.
+ {{< alert type="note" >}}
+
+The output for private keys and public keys command should generate the same fingerprint.
+
+ {{< /alert >}}
1. Restart either `sshd` for OpenSSH or the `gitlab-sshd` service on **each Rails node on your secondary** site:
diff --git a/doc/administration/geo/replication/container_registry.md b/doc/administration/geo/replication/container_registry.md
index 78cc6161ec6c10a0d4f6c3c60a215f925ae0290a..71499b46c498d54f86e2d3eb1142859ecf3809fa 100644
--- a/doc/administration/geo/replication/container_registry.md
+++ b/doc/administration/geo/replication/container_registry.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Container registry for a secondary site
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can set up a container registry on your **secondary** Geo site that mirrors the one on the **primary** Geo site. This container registry replication is used only for disaster recovery purposes.
@@ -101,15 +104,20 @@ To be able to replicate new container images, the container registry must send n
]
```
- NOTE:
- Replace `<example.com>` with the `external_url` defined in your primary site's `/etc/gitlab/gitlab.rb` file, and
+ {{< alert type="note" >}}
+
+Replace `<example.com>` with the `external_url` defined in your primary site's `/etc/gitlab/gitlab.rb` file, and
replace `<replace_with_a_secret_token>` with a case sensitive alphanumeric string
that starts with a letter. You can generate one with `< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c 32 | sed "s/^[0-9]*//"; echo`
- NOTE:
- If you use an external Registry (not the one integrated with GitLab), you only need to specify
+ {{< /alert >}}
+
+ {{< alert type="note" >}}
+
+If you use an external Registry (not the one integrated with GitLab), you only need to specify
the notification secret (`registry['notification_secret']`) in the
`/etc/gitlab/gitlab.rb` file.
+ {{< /alert >}}
1. For GitLab HA only. Edit `/etc/gitlab/gitlab.rb` on every web node:
diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md
index b47d947beb162988c96336dcf13ebb318c8ad5ae..6c5fac5d34094c669bbd2a0353b3ea44345da5d5 100644
--- a/doc/administration/geo/replication/datatypes.md
+++ b/doc/administration/geo/replication/datatypes.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Supported Geo data types
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
A Geo data type is a specific class of data that is required by one or more GitLab features to
store relevant information.
@@ -152,11 +155,15 @@ Elasticsearch is not supported in Geo.
The replication for some data types is behind a corresponding feature flag:
-> - They're deployed behind a feature flag, enabled by default.
-> - They're enabled on GitLab.com.
-> - They can't be enabled or disabled per-project.
-> - They are recommended for production use.
-> - For a GitLab Self-Managed instance, GitLab administrators can opt to [disable them](#enable-or-disable-replication-for-some-data-types).
+{{< history >}}
+
+- They're deployed behind a feature flag, enabled by default.
+- They're enabled on GitLab.com.
+- They can't be enabled or disabled per-project.
+- They are recommended for production use.
+- For a GitLab Self-Managed instance, GitLab administrators can opt to [disable them](#enable-or-disable-replication-for-some-data-types).
+
+{{< /history >}}
#### Enable or disable replication (for some data types)
@@ -175,13 +182,16 @@ To enable, such as for package file replication:
Feature.enable(:geo_package_file_replication)
```
-WARNING:
+{{< alert type="warning" >}}
+
Features not on this list, or with **No** in the **Replicated** column,
are not replicated to a **secondary** site. Failing over without manually
replicating data from those features causes the data to be **lost**.
To use those features on a **secondary** site, or to execute a failover
successfully, you must replicate their data using some other means.
+{{< /alert >}}
+
| Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | GitLab-managed object storage replication (added in GitLab version) | GitLab-managed object storage verification (added in GitLab version) | Notes |
|:----------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------|:------------------------------------------------------------------------------|:--------------------------------------------------------------------------------|:--------------------------------------------------------------------------------|:------|
| [Application data in PostgreSQL](../../postgresql/_index.md) | **Yes** (10.2) | **Yes** (10.2) | Not applicable | Not applicable | |
diff --git a/doc/administration/geo/replication/disable_geo.md b/doc/administration/geo/replication/disable_geo.md
index 5d04f50e8a9e0c65ea69dab0bfff3c9d16726139..c5e843197b6d2c92317b6d846ee6766055fa5caf 100644
--- a/doc/administration/geo/replication/disable_geo.md
+++ b/doc/administration/geo/replication/disable_geo.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Disabling Geo
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you want to revert to a regular Linux package installation setup after a test, or you have encountered a Disaster Recovery
situation and you want to disable Geo momentarily, you can use these instructions to disable your
diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md
index 6f7c3fc72815677bef29856b72044703573df624..c645bb4b8c3cff5f0f26eeff51841ad3a7f1b663 100644
--- a/doc/administration/geo/replication/faq.md
+++ b/doc/administration/geo/replication/faq.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo Frequently Asked Questions
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
## What are the minimum requirements to run Geo?
diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md
index 53085a7f9ff0fd9353eaf26f370777064e5a6fa3..c5a2ab24a710e66b7fd99f7f42742658eda9215f 100644
--- a/doc/administration/geo/replication/geo_validation_tests.md
+++ b/doc/administration/geo/replication/geo_validation_tests.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo validation tests
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The Geo team performs manual testing and validation on common deployment configurations to ensure
that Geo works when upgrading between minor GitLab versions and major PostgreSQL database versions.
diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md
index 2806c48e1fa0e1786ec9af13a5218c737944e9ac..5d68722ff3a38787a779b8fa0a3823907d8f7319 100644
--- a/doc/administration/geo/replication/location_aware_git_url.md
+++ b/doc/administration/geo/replication/location_aware_git_url.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Location-aware Git remote URL with AWS Route53
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
[GitLab Geo supports location-aware DNS including web UI and API traffic.](../secondary_proxy/_index.md#configure-location-aware-dns)
This configuration is recommended over the location-aware Git remote URL
described in this document.
+{{< /alert >}}
+
You can provide GitLab users with a single remote URL that automatically uses
the Geo site closest to them. This means users don't need to update their Git
configuration to take advantage of closer Geo sites as they move.
diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md
index 9cc94385e031a73399a609ecc9ee8b0d3855c82e..6bc9968b18320b88b3a1b2fac1a58d22da21e3e7 100644
--- a/doc/administration/geo/replication/multiple_servers.md
+++ b/doc/administration/geo/replication/multiple_servers.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo for multiple nodes
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This document describes a minimal reference architecture for running Geo
in a multi-node configuration. If your multi-node setup differs from the one
@@ -29,9 +32,12 @@ network topology of your deployment.
The only external way to access the two Geo sites is by HTTPS at
`gitlab.us.example.com` and `gitlab.eu.example.com` in the example above.
-NOTE:
+{{< alert type="note" >}}
+
The **primary** and **secondary** Geo sites must be able to communicate to each other over HTTPS.
+{{< /alert >}}
+
## Redis and PostgreSQL for multiple nodes
Because of the additional complexity involved in setting up this configuration
@@ -42,9 +48,12 @@ For more information on setting up a multi-node PostgreSQL cluster and Redis clu
- [Geo multi-node database replication](../setup/database.md#multi-node-database-replication)
- [Redis multi-node documentation](../../redis/replication_and_failover.md)
-NOTE:
+{{< alert type="note" >}}
+
It is possible to use cloud hosted services for PostgreSQL and Redis, but this is beyond the scope of this document.
+{{< /alert >}}
+
## Prerequisites: Two independently working GitLab multi-node sites
One GitLab site serves as the Geo **primary** site. Use the
@@ -64,9 +73,12 @@ The following steps enable a GitLab site to serve as the Geo **primary** site.
### Step 1: Configure the **primary** frontend nodes
-NOTE:
+{{< alert type="note" >}}
+
Do not use [`geo_primary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles) because it is intended for a single-node site.
+{{< /alert >}}
+
1. Edit `/etc/gitlab/gitlab.rb` and add the following:
```ruby
@@ -92,7 +104,8 @@ After making these changes, [reconfigure GitLab](../../restart_gitlab.md#reconfi
sudo gitlab-ctl set-geo-primary-node
```
-NOTE:
+{{< alert type="note" >}}
+
PostgreSQL and Redis should have already been disabled on the
application nodes during typical GitLab multi-node setup. Connections
from the application nodes to services on the backend nodes should
@@ -100,6 +113,8 @@ have also been configured. See multi-node configuration documentation for
[PostgreSQL](../../postgresql/replication_and_failover.md#configuring-the-application-nodes)
and [Redis](../../redis/replication_and_failover.md#example-configuration-for-the-gitlab-application).
+{{< /alert >}}
+
## Configure the other GitLab site to be a Geo **secondary** site
A **secondary** site is similar to any other GitLab multi-node site, with three
@@ -128,10 +143,13 @@ documentation:
- [Gitaly](../../gitaly/_index.md), which stores data that is
synchronized from the Geo **primary** site.
-NOTE:
+{{< alert type="note" >}}
+
[NFS](../../nfs.md) can be used in place of Gitaly but is not
recommended.
+{{< /alert >}}
+
### Step 2: Configure the Geo tracking database on the Geo **secondary** site
The Geo tracking database cannot be run in a multi-node PostgreSQL cluster,
@@ -192,9 +210,12 @@ After streaming replication is enabled in the secondary Geo site's read-replica
### Step 4: Configure the frontend application nodes on the Geo **secondary** site
-NOTE:
+{{< alert type="note" >}}
+
Do not use [`geo_secondary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles) because it is intended for a single-node site.
+{{< /alert >}}
+
In the minimal [architecture diagram](#architecture-overview) above, there are two
machines running the GitLab application services. These services are enabled
selectively in the configuration.
@@ -268,17 +289,22 @@ then make the following modifications:
registry['gid'] = 9002
```
-NOTE:
+{{< alert type="note" >}}
+
If you had set up PostgreSQL cluster using the Linux package and had set
`postgresql['sql_user_password'] = 'md5 digest of secret'`, keep in
mind that `gitlab_rails['db_password']` and `geo_secondary['db_password']`
contains the plaintext passwords. This is used to let the Rails
nodes connect to the databases.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Make sure that current node's IP is listed in
`postgresql['md5_auth_cidr_addresses']` setting of the read-replica database to
allow Rails on this node to connect to PostgreSQL.
+{{< /alert >}}
After making these changes, [reconfigure GitLab](../../restart_gitlab.md#reconfigure-a-linux-package-installation) so the changes take effect.
diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md
index 63779861626bc700b1fb36ece06ff7d3f0ff8158..b7798348aafe34addf0eaa16f60a8efc97f2a9de 100644
--- a/doc/administration/geo/replication/object_storage.md
+++ b/doc/administration/geo/replication/object_storage.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo with Object storage
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
> Verification of files stored in object storage was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8056) in GitLab 16.4 [with a flag](../../feature_flags.md) named `geo_object_storage_verification`. Enabled by default.
@@ -38,7 +41,11 @@ See [Object storage replication tests](geo_validation_tests.md#object-storage-re
## Enabling GitLab-managed object storage replication
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5551) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5551) in GitLab 15.1.
+
+{{< /history >}}
**Secondary** sites can replicate files stored on the **primary** site regardless of
whether they are stored on the local file system or in object storage.
diff --git a/doc/administration/geo/replication/pause_resume_replication.md b/doc/administration/geo/replication/pause_resume_replication.md
index f49a8ac2ba913a7eb867c77ad946f16bc9e8d89e..1e577abfc582a39fa1aaeffb7e1ae1d6f45f7d68 100644
--- a/doc/administration/geo/replication/pause_resume_replication.md
+++ b/doc/administration/geo/replication/pause_resume_replication.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pausing and resuming replication
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
Pausing and resuming of replication is only supported for Geo installations using a
Linux package-managed database. External databases are not supported.
+{{< /alert >}}
+
In some circumstances, like during [upgrades](upgrading_the_geo_sites.md) or a
[planned failover](../disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary.
diff --git a/doc/administration/geo/replication/remove_geo_site.md b/doc/administration/geo/replication/remove_geo_site.md
index 1cb0126dc90478d43daedd46cd88e85ec437579e..93d516e6ff760622610d942030957cda005dc8dd 100644
--- a/doc/administration/geo/replication/remove_geo_site.md
+++ b/doc/administration/geo/replication/remove_geo_site.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Removing secondary Geo sites
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
**Secondary** sites can be removed from the Geo cluster using the Geo administration page of the **primary** site. To remove a **secondary** site:
@@ -27,8 +30,11 @@ stop and uninstall this site. For each node on your secondary Geo site:
1. Uninstall GitLab:
- NOTE:
- If GitLab data has to be cleaned from the instance as well, see how to [uninstall the Linux package and all its data](https://docs.gitlab.com/omnibus/installation/#uninstall-the-linux-package-omnibus).
+ {{< alert type="note" >}}
+
+If GitLab data has to be cleaned from the instance as well, see how to [uninstall the Linux package and all its data](https://docs.gitlab.com/omnibus/installation/#uninstall-the-linux-package-omnibus).
+
+ {{< /alert >}}
```shell
# Stop gitlab and remove its supervision process
@@ -49,8 +55,11 @@ When GitLab has been uninstalled from each node on the **secondary** site, the r
sudo gitlab-psql
```
- NOTE:
- Using `gitlab-rails dbconsole` does not work, because managing replication slots requires superuser permissions.
+ {{< alert type="note" >}}
+
+Using `gitlab-rails dbconsole` does not work, because managing replication slots requires superuser permissions.
+
+ {{< /alert >}}
1. Find the name of the relevant replication slot. This is the slot that is specified with `--slot-name` when running the replicate command: `gitlab-ctl replicate-geo-database`.
diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md
index a1cc0c5d8adc1d8cc3a2a84f18919b7ed68013cb..a3efc6ba05ba0fcc9e67691265140546f8a87624 100644
--- a/doc/administration/geo/replication/security_review.md
+++ b/doc/administration/geo/replication/security_review.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo security review (Q&A)
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following security review of the Geo feature set focuses on security aspects of
the feature as they apply to customers running their own GitLab instances. The review
diff --git a/doc/administration/geo/replication/selective_synchronization.md b/doc/administration/geo/replication/selective_synchronization.md
index dbcedabc352deec6ce009a515d1a81f0a9e15d95..491b016362c6c6653b1ee7ad9359b08809cb270c 100644
--- a/doc/administration/geo/replication/selective_synchronization.md
+++ b/doc/administration/geo/replication/selective_synchronization.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Selective synchronization
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Geo supports selective synchronization, which allows administrators to choose
which projects should be synchronized by **secondary** sites.
@@ -16,9 +19,12 @@ former is ideal for replicating data belonging to a subset of users, while the
latter is more suited to progressively rolling out Geo to a large GitLab
instance.
-NOTE:
+{{< alert type="note" >}}
+
Geo's synchronization logic is outlined in the [documentation](../_index.md). Both the solution and the documentation is subject to change from time to time. You must independently determine your legal obligations in regard to privacy and cybersecurity laws, and applicable trade control law on an ongoing basis.
+{{< /alert >}}
+
Selective synchronization:
1. Does not restrict permissions from **secondary** sites.
diff --git a/doc/administration/geo/replication/single_sign_on.md b/doc/administration/geo/replication/single_sign_on.md
index b1fa3dd1fba46b183d12d21d64f76ed6a793b817..7ca1e2676000a55e83ad25d75a5e0d1e8df1f989 100644
--- a/doc/administration/geo/replication/single_sign_on.md
+++ b/doc/administration/geo/replication/single_sign_on.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo with Single Sign On (SSO)
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This documentation only discusses Geo-specific SSO considerations and configuration. For more information on general authentication, see [GitLab authentication and authorization](../../auth/_index.md).
@@ -33,10 +36,13 @@ If you have configured SAML on the primary site correctly, then it should work o
### SAML with separate URL with proxying enabled
-NOTE:
+{{< alert type="note" >}}
+
When proxying is enabled, SAML can only be used to sign in the secondary site if your SAML Identity Provider (IdP) allows an
application to have multiple callback URLs configured. Check with your IdP provider support team to confirm if this is the case.
+{{< /alert >}}
+
If a secondary site uses a different `external_url` to the primary site, then configure your SAML Identity Provider (IdP) to allow the secondary site's SAML callback URL. For example, to configure Okta:
1. [Sign in to Okta](https://login.okta.com/).
@@ -131,7 +137,10 @@ in most cases, it should work without an issue:
If you use LDAP on your **primary** site, you should also set up secondary LDAP servers on each **secondary** site. Otherwise, users cannot perform Git operations over HTTP(s) on the **secondary** site using HTTP basic authentication. However, users can still use Git with SSH and personal access tokens.
-NOTE:
+{{< alert type="note" >}}
+
It is possible for all **secondary** sites to share an LDAP server, but additional latency can be an issue. Also, consider what LDAP server is available in a [disaster recovery](../disaster_recovery/_index.md) scenario if a **secondary** site is promoted to be a **primary** site.
+{{< /alert >}}
+
Check your LDAP service documentation for instructions on how to set up replication in your LDAP service. The process differs depending on the software or service used. For example, OpenLDAP provides this [replication documentation](https://www.openldap.org/doc/admin24/replication.html).
diff --git a/doc/administration/geo/replication/troubleshooting/_index.md b/doc/administration/geo/replication/troubleshooting/_index.md
index ec65005833611e231c9697a42c5ee3ef178b76bd..041e998ca4b28e97bbb15cafa42a740ccd714af8 100644
--- a/doc/administration/geo/replication/troubleshooting/_index.md
+++ b/doc/administration/geo/replication/troubleshooting/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Geo
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When working with Geo, you might encounter the following issues:
diff --git a/doc/administration/geo/replication/troubleshooting/client_http.md b/doc/administration/geo/replication/troubleshooting/client_http.md
index e7fa9b3f3920cbe3215281992f7cec668551c341..4d6d548bd391e9878f036bf5944dbbaabeff54c5 100644
--- a/doc/administration/geo/replication/troubleshooting/client_http.md
+++ b/doc/administration/geo/replication/troubleshooting/client_http.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Geo client and HTTP response code errors
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
## Fixing client errors
diff --git a/doc/administration/geo/replication/troubleshooting/common.md b/doc/administration/geo/replication/troubleshooting/common.md
index ce96c4f22ff9a820a0f4d1563ba5d04d95a29643..d4d268fc800c354b0fb86e975602174b4050036c 100644
--- a/doc/administration/geo/replication/troubleshooting/common.md
+++ b/doc/administration/geo/replication/troubleshooting/common.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting common Geo errors
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
## Basic troubleshooting
@@ -63,7 +66,11 @@ health check manually to get this information and a few more details.
#### Health check Rake task
-> - The use of a custom NTP server was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105514) in GitLab 15.7.
+{{< history >}}
+
+- The use of a custom NTP server was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105514) in GitLab 15.7.
+
+{{< /history >}}
This Rake task can be run on a **Rails** node in the **primary** or **secondary**
Geo sites:
@@ -669,9 +676,9 @@ Increasing the interval means that your Geo metrics are updated less frequently.
The following example sets the job to run every 30 minutes. Adjust the cron schedule based on your needs.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Add or modify the following setting in `/etc/gitlab/gitlab.rb`:
@@ -685,7 +692,9 @@ The following example sets the job to run every 30 minutes. Adjust the cron sche
sudo gitlab-ctl reconfigure
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -706,4 +715,6 @@ The following example sets the job to run every 30 minutes. Adjust the cron sche
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/administration/geo/replication/troubleshooting/failover.md b/doc/administration/geo/replication/troubleshooting/failover.md
index 76341021e7bfa01e7db9cfb223b23067dfe40f05..da7fe5c4959227d7c583ae286e828f69a0638ab7 100644
--- a/doc/administration/geo/replication/troubleshooting/failover.md
+++ b/doc/administration/geo/replication/troubleshooting/failover.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../../disaster_recovery/failover_troubleshooting.md'
-remove_date: '2025-08-02'
+redirect_to: ../../disaster_recovery/failover_troubleshooting.md
+remove_date: "2025-08-02"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/geo/replication/troubleshooting/postgresql_replication.md b/doc/administration/geo/replication/troubleshooting/postgresql_replication.md
index f53ba320fe876ba12f6a0c00715c6067bfea0fd1..3d39c7a0a12c02ae1d051281419f92b58240a393 100644
--- a/doc/administration/geo/replication/troubleshooting/postgresql_replication.md
+++ b/doc/administration/geo/replication/troubleshooting/postgresql_replication.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Geo PostgreSQL replication
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following sections outline troubleshooting steps for fixing replication error messages (indicated by `Database replication working? ... no` in the
[`geo:check` output](common.md#health-check-rake-task).
@@ -25,8 +28,11 @@ If the secondary site is not able to reconnect, use the following steps to remov
sudo gitlab-psql -d gitlabhq_production
```
- NOTE:
- Using `gitlab-rails dbconsole` does not work, because managing replication slots requires superuser permissions.
+ {{< alert type="note" >}}
+
+Using `gitlab-rails dbconsole` does not work, because managing replication slots requires superuser permissions.
+
+ {{< /alert >}}
1. View the replication slots and remove them if they are inactive:
diff --git a/doc/administration/geo/replication/troubleshooting/replication.md b/doc/administration/geo/replication/troubleshooting/replication.md
index a1faf8ee08d3c7af8ef575d06031232bc52093f5..952f0ac12600b49b369e69a76c804d5542be7a2d 100644
--- a/doc/administration/geo/replication/troubleshooting/replication.md
+++ b/doc/administration/geo/replication/troubleshooting/replication.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'synchronization_verification.md'
-remove_date: '2025-01-16'
+redirect_to: synchronization_verification.md
+remove_date: "2025-01-16"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/geo/replication/troubleshooting/synchronization.md b/doc/administration/geo/replication/troubleshooting/synchronization.md
index 87690f811d5c0cd7bb693a37b11b4aa09eac3139..049a19ddecb20f5d69c3beb2701524ec8404afc3 100644
--- a/doc/administration/geo/replication/troubleshooting/synchronization.md
+++ b/doc/administration/geo/replication/troubleshooting/synchronization.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'synchronization_verification.md'
-remove_date: '2025-01-16'
+redirect_to: synchronization_verification.md
+remove_date: "2025-01-16"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/geo/replication/troubleshooting/synchronization_verification.md b/doc/administration/geo/replication/troubleshooting/synchronization_verification.md
index 98a0fd8df237673a18c8ba566f3ac339dde08983..d5fae1a629b2f0d4ab1f0bdfe5631f773921f10a 100644
--- a/doc/administration/geo/replication/troubleshooting/synchronization_verification.md
+++ b/doc/administration/geo/replication/troubleshooting/synchronization_verification.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Geo synchronization and verification errors
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you notice replication or verification failures in `Admin > Geo > Sites` or the [Sync status Rake task](common.md#sync-status-rake-task), you can try to resolve the failures with the following general steps:
@@ -37,10 +40,13 @@ replication or verification for individual records synchronously or asynchronous
#### Obtaining a Replicator instance
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions.
Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
Before you can perform any sync or verify operations, you need to obtain a Replicator instance.
First, [start a Rails console session](../../../operations/rails_console.md#starting-a-rails-console-session)
@@ -241,12 +247,19 @@ models that correspond to Geo registry tables that can be queried are:
### Resync and reverify multiple components
-> - Bulk resync and reverify [added](https://gitlab.com/gitlab-org/gitlab/-/issues/364729) in GitLab 16.5.
+{{< history >}}
+
+- Bulk resync and reverify [added](https://gitlab.com/gitlab-org/gitlab/-/issues/364729) in GitLab 16.5.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
Commands that change data can cause damage if not run correctly or under the right conditions.
Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
The following sections describe how to use internal application commands in the
[Rails console](../../../operations/rails_console.md#starting-a-rails-console-session) to cause bulk
replication or verification.
@@ -265,10 +278,13 @@ Alternatively,
**on the secondary Geo site** to gather more information, or execute these operations manually using
the snippets below.
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions.
Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
##### Sync all resources of one component that failed to sync
The following script:
@@ -409,9 +425,12 @@ If you encounter these errors in your primary site `geo.log`, they're also refle
1. In a Puma or Sidekiq node in the primary site, [open a Rails console](../../../operations/rails_console.md#starting-a-rails-console-session).
1. Run the following snippet to find the affected artifacts containing the `File is not checksummable` message:
-NOTE:
+{{< alert type="note" >}}
+
The example provided below uses `JobArtifact` blob type; however, the same solution applies to any blob type that Geo uses.
+{{< /alert >}}
+
```ruby
artifacts = Ci::JobArtifact.verification_failed.where("verification_failure like '%File is not checksummable%'");1
@@ -542,11 +561,14 @@ is [enabled on the secondary site](../../../packages/container_registry.md#enabl
### Message: `Synchronization failed - Error syncing repository`
-WARNING:
+{{< alert type="warning" >}}
+
If large repositories are affected by this problem,
their resync may take a long time and cause significant load on your Geo sites,
storage and network systems.
+{{< /alert >}}
+
The following error message indicates a consistency check error when syncing the repository:
```plaintext
@@ -704,9 +726,12 @@ to transfer each affected repository from the primary to the secondary site.
## Find repository check failures in a Geo secondary site
-NOTE:
+{{< alert type="note" >}}
+
All repositories data types have been migrated to the Geo Self-Service Framework in GitLab 16.3. There is an [issue to implement this functionality back in the Geo Self-Service Framework](https://gitlab.com/gitlab-org/gitlab/-/issues/426659).
+{{< /alert >}}
+
For GitLab 16.2 and earlier:
When [enabled for all projects](../../../repository_checks.md#enable-repository-checks-for-all-projects), [Repository checks](../../../repository_checks.md) are also performed on Geo secondary sites. The metadata is stored in the Geo tracking database.
@@ -723,9 +748,12 @@ Repository check failures on a Geo secondary site do not necessarily imply a rep
[Start a Rails console session](../../../operations/rails_console.md#starting-a-rails-console-session)
to enact the following, basic troubleshooting steps.
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
### Get the number of repositories that failed the repository check
```ruby
@@ -768,16 +796,18 @@ to start again from scratch, there are a few steps that can help you:
1. Clear Gitaly/Gitaly Cluster data.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Gitaly
+ {{< tab title="Gitaly" >}}
```shell
mv /var/opt/gitlab/git-data/repositories /var/opt/gitlab/git-data/repositories.old
sudo gitlab-ctl reconfigure
```
- :::TabTitle Gitaly Cluster
+ {{< /tab >}}
+
+ {{< tab title="Gitaly Cluster" >}}
1. Optional. Disable the Praefect internal load balancer.
1. Stop Praefect on each Praefect server:
@@ -814,18 +844,26 @@ to start again from scratch, there are a few steps that can help you:
1. Optional. If you disabled it, reactivate the Praefect internal load balancer.
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
- NOTE:
- You may want to remove the `/var/opt/gitlab/git-data/repositories.old` in the future
+ {{< alert type="note" >}}
+
+You may want to remove the `/var/opt/gitlab/git-data/repositories.old` in the future
as soon as you confirmed that you don't need it anymore, to save disk space.
+ {{< /alert >}}
+
1. Optional. Rename other data folders and create new ones.
- WARNING:
+ {{< alert type="warning" >}}
+
You may still have files on the **secondary** site that have been removed from the **primary** site, but this
removal has not been reflected. If you skip this step, these files are not removed from the Geo **secondary** site.
+ {{< /alert >}}
+
Any uploaded content (like file attachments, avatars, or LFS objects) is stored in a
subfolder in one of these paths:
@@ -856,9 +894,12 @@ to start again from scratch, there are a few steps that can help you:
1. Reset the Tracking Database.
- WARNING:
+ {{< alert type="warning" >}}
+
If you skipped the optional step 3, be sure both `geo-postgresql` and `postgresql` services are running.
+ {{< /alert >}}
+
```shell
gitlab-rake db:drop:geo DISABLE_DATABASE_ENVIRONMENT_CHECK=1 # on a secondary app node
gitlab-ctl reconfigure # on the tracking database node
diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md
index 89d6f66ef4e0b558a607b370a739c541c0f39010..17bc237585309d963c5c5edb504b3f815230f5ff 100644
--- a/doc/administration/geo/replication/tuning.md
+++ b/doc/administration/geo/replication/tuning.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Tuning Geo
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can limit the number of concurrent operations the sites can run
in the background.
diff --git a/doc/administration/geo/replication/upgrading_the_geo_sites.md b/doc/administration/geo/replication/upgrading_the_geo_sites.md
index fce686ada031b4227d9b4b4b4014674c897b2ce8..b881cfc77bea912bd2224b8fa290f36c33ce1917 100644
--- a/doc/administration/geo/replication/upgrading_the_geo_sites.md
+++ b/doc/administration/geo/replication/upgrading_the_geo_sites.md
@@ -5,11 +5,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Upgrading the Geo sites
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
Read these sections carefully before updating your Geo sites. Not following
version-specific upgrade steps may result in unexpected downtime. If you have
any specific questions, [contact Support](https://about.gitlab.com/support/#contact-support).
@@ -17,6 +21,8 @@ A database major version upgrade requires [re-initializing the PostgreSQL replic
to Geo secondaries. This applies to both Linux-packaged and externally-managed databases.
This may result in a larger than expected downtime.
+{{< /alert >}}
+
Upgrading Geo sites involves performing:
1. Version-specific upgrade steps, depending on the version being upgraded to or from:
@@ -27,10 +33,13 @@ Upgrading Geo sites involves performing:
## General upgrade steps
-NOTE:
+{{< alert type="note" >}}
+
These general upgrade steps require downtime in a multi-node setup.
If you want to avoid downtime, consider using [zero-downtime upgrades](../../../update/zero_downtime.md#multi-node--ha-deployment-with-geo).
+{{< /alert >}}
+
To upgrade the Geo sites when a new GitLab version is released, upgrade **primary**
and all **secondary** sites:
diff --git a/doc/administration/geo/replication/usage.md b/doc/administration/geo/replication/usage.md
index 9b69661db7f06d1ec0872c04d051e695ba93d167..fce6085066a4d9e466033764417e91cf8ce8b32e 100644
--- a/doc/administration/geo/replication/usage.md
+++ b/doc/administration/geo/replication/usage.md
@@ -7,9 +7,12 @@ title: Using a Geo Site
<!-- Please update EE::GitLab::GeoGitAccess::GEO_SERVER_DOCS_URL if this file is moved) -->
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
After you set up the [database replication and configure the Geo nodes](../setup/_index.md), use your closest GitLab site as you would do with the primary one.
@@ -31,7 +34,8 @@ remote:
Everything up-to-date
```
-NOTE:
+{{< alert type="note" >}}
+
If you're using HTTPS instead of [SSH](../../../user/ssh.md) to push to the secondary,
you can't store credentials in the URL like `user:password@URL`. Instead, you can use a
[`.netrc` file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html)
@@ -39,6 +43,8 @@ for Unix-like operating systems or `_netrc` for Windows. In that case, the crede
are stored as a plain text. If you're looking for a more secure way to store credentials,
you can use [Git Credential Storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage).
+{{< /alert >}}
+
## Web user interface
The web user interface on the **secondary** site is read/write. As a user, all actions permitted on the **primary** site can be performed on the **secondary** site without limitations.
diff --git a/doc/administration/geo/secondary_proxy/_index.md b/doc/administration/geo/secondary_proxy/_index.md
index 54186a28885478d1e40cfc57c429c300390c2326..7eb2f452f598a9d3246dce14a659243be12163f9 100644
--- a/doc/administration/geo/secondary_proxy/_index.md
+++ b/doc/administration/geo/secondary_proxy/_index.md
@@ -5,19 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo proxying for secondary sites
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - HTTP proxying for secondary sites with separate URLs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in GitLab 14.5 [with a flag](../../feature_flags.md) named `geo_secondary_proxy_separate_urls`. Disabled by default.
-> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in GitLab 15.1.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- HTTP proxying for secondary sites with separate URLs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in GitLab 14.5 [with a flag](../../feature_flags.md) named `geo_secondary_proxy_separate_urls`. Disabled by default.
+- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in GitLab 15.1.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
The `geo_secondary_proxy_separate_urls` feature flag is planned to be deprecated and removed in a future release.
Support for read-only Geo secondary sites is proposed in [issue 366810](https://gitlab.com/gitlab-org/gitlab/-/issues/366810).
+{{< /alert >}}
+
Secondary sites behave as full read-write GitLab instances. They transparently proxy all operations to the primary site, with [some notable exceptions](#features-accelerated-by-secondary-geo-sites).
This behavior enables use-cases including:
@@ -157,9 +167,12 @@ In Kubernetes, you can [use the same domain under `global.hosts.domain` as for t
You can use different external URLs per site. You can use this to offer a specific site to a specific set of users. Alternatively, you can give users control over which site they use, though they must understand the implications of their choice.
-NOTE:
+{{< alert type="note" >}}
+
GitLab does not support multiple external URLs, see [issue 21319](https://gitlab.com/gitlab-org/gitlab/-/issues/21319). An inherent problem is there are many cases where a site needs to produce an absolute URL outside of the context of an HTTP request, such as when sending emails that were not triggered by a request.
+{{< /alert >}}
+
### Configure a secondary Geo site to a different external URL than the primary site
If your secondary site uses the same external URL as the primary site:
@@ -209,20 +222,20 @@ In this context, accelerated reads refer to read requests served from the second
| Feature / component | Accelerated reads? | Notes |
| :-------------------------------------------------- | :--------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Project, wiki, design repository (using the web UI) | **{dotted-circle}** No | |
-| Project, wiki repository (using Git) | **{check-circle}** Yes | Git reads are served from the local secondary while pushes get proxied to the primary. Selective sync or cases where repositories don't exist locally on the Geo secondary throw a "not found" error. |
-| Project, Personal Snippet (using the web UI) | **{dotted-circle}** No | |
-| Project, Personal Snippet (using Git) | **{check-circle}** Yes | Git reads are served from the local secondary while pushes get proxied to the primary. Selective sync or cases where repositories don't exist locally on the Geo secondary throw a "not found" error. |
-| Group wiki repository (using the web UI) | **{dotted-circle}** No | |
-| Group wiki repository (using Git) | **{check-circle}** Yes | Git reads are served from the local secondary while pushes get proxied to the primary. Selective sync or cases where repositories don't exist locally on the Geo secondary throw a "not found" error. |
-| User uploads | **{dotted-circle}** No | |
-| LFS objects (using the web UI) | **{dotted-circle}** No | |
-| LFS objects (using Git) | **{check-circle}** Yes | |
-| Pages | **{dotted-circle}** No | Pages can use the same URL (without access control), but must be configured separately and are not proxied. |
-| Advanced search (using the web UI) | **{dotted-circle}** No | |
-| Container registry | **{dotted-circle}** No | The container registry is only recommended for Disaster Recovery scenarios. If the secondary site's container registry is not up to date, the read request is served with old data as the request is not forwarded to the primary site. Accelerating the container registry is planned, please upvote or comment in the [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/365864) to indicate your interest or ask your GitLab representative to do so on your behalf. |
-| Dependency Proxy | **{dotted-circle}** No | Read requests to a Geo secondary site's Dependency Proxy are always proxied to the primary site. |
-| All other data | **{dotted-circle}** No | Read requests for components not listed in this table are always automatically forwarded to the primary site. |
+| Project, wiki, design repository (using the web UI) | {{< icon name="dotted-circle" >}} No | |
+| Project, wiki repository (using Git) | {{< icon name="check-circle" >}} Yes | Git reads are served from the local secondary while pushes get proxied to the primary. Selective sync or cases where repositories don't exist locally on the Geo secondary throw a "not found" error. |
+| Project, Personal Snippet (using the web UI) | {{< icon name="dotted-circle" >}} No | |
+| Project, Personal Snippet (using Git) | {{< icon name="check-circle" >}} Yes | Git reads are served from the local secondary while pushes get proxied to the primary. Selective sync or cases where repositories don't exist locally on the Geo secondary throw a "not found" error. |
+| Group wiki repository (using the web UI) | {{< icon name="dotted-circle" >}} No | |
+| Group wiki repository (using Git) | {{< icon name="check-circle" >}} Yes | Git reads are served from the local secondary while pushes get proxied to the primary. Selective sync or cases where repositories don't exist locally on the Geo secondary throw a "not found" error. |
+| User uploads | {{< icon name="dotted-circle" >}} No | |
+| LFS objects (using the web UI) | {{< icon name="dotted-circle" >}} No | |
+| LFS objects (using Git) | {{< icon name="check-circle" >}} Yes | |
+| Pages | {{< icon name="dotted-circle" >}} No | Pages can use the same URL (without access control), but must be configured separately and are not proxied. |
+| Advanced search (using the web UI) | {{< icon name="dotted-circle" >}} No | |
+| Container registry | {{< icon name="dotted-circle" >}} No | The container registry is only recommended for Disaster Recovery scenarios. If the secondary site's container registry is not up to date, the read request is served with old data as the request is not forwarded to the primary site. Accelerating the container registry is planned, please upvote or comment in the [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/365864) to indicate your interest or ask your GitLab representative to do so on your behalf. |
+| Dependency Proxy | {{< icon name="dotted-circle" >}} No | Read requests to a Geo secondary site's Dependency Proxy are always proxied to the primary site. |
+| All other data | {{< icon name="dotted-circle" >}} No | Read requests for components not listed in this table are always automatically forwarded to the primary site. |
To request acceleration of a feature, check if an issue already exists in [epic 8239](https://gitlab.com/groups/gitlab-org/-/epics/8239) and upvote or comment on it to indicate your interest or ask your GitLab representative to do so on your behalf. If an applicable issue doesn't exist, open one and mention it in the epic.
@@ -232,9 +245,9 @@ Secondary site HTTP proxying is enabled by default on a secondary site when it u
HTTP proxying is enabled by default in GitLab 15.1 on a secondary site even without a unified URL. If proxying needs to be disabled on all secondary sites, it is easiest to disable the feature flag:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. SSH into a node which is running Puma or Sidekiq on your primary Geo site and run:
@@ -248,7 +261,9 @@ HTTP proxying is enabled by default in GitLab 15.1 on a secondary site even with
sudo gitlab-ctl restart puma
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. On your primary Geo site, run this command in the Toolbox pod:
@@ -262,13 +277,15 @@ HTTP proxying is enabled by default in GitLab 15.1 on a secondary site even with
kubectl rollout restart deployment -l app=webservice
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To revert the changes so secondary site proxying is enabled again:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. SSH into a node which is running Puma or Sidekiq on your primary Geo site and run:
@@ -282,7 +299,9 @@ To revert the changes so secondary site proxying is enabled again:
sudo gitlab-ctl restart puma
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. On your primary Geo site, run this command in the Toolbox pod:
@@ -296,15 +315,17 @@ To revert the changes so secondary site proxying is enabled again:
kubectl rollout restart deployment -l app=webservice
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Disable secondary site HTTP proxying per site
If there are multiple secondary sites, you can disable HTTP proxying on each secondary site separately, by following these steps:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. SSH into each application node (serving user traffic directly) on your secondary Geo site
and add the following environment variable:
@@ -325,7 +346,9 @@ If there are multiple secondary sites, you can disable HTTP proxying on each sec
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
You can use `--set gitlab.webservice.extraEnv.GEO_SECONDARY_PROXY="0"`,
or specify the following in your values file:
@@ -337,7 +360,9 @@ gitlab:
GEO_SECONDARY_PROXY: "0"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Disable secondary site Git proxying
diff --git a/doc/administration/geo/secondary_proxy/runners.md b/doc/administration/geo/secondary_proxy/runners.md
index 85783656925b4ae4043547d5e3ddc75e49c153fc..36868e8e1a9be4c4c933ab9cf2afb5b3d5bcce48 100644
--- a/doc/administration/geo/secondary_proxy/runners.md
+++ b/doc/administration/geo/secondary_proxy/runners.md
@@ -5,18 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Secondary runners
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9779) in GitLab 16.8 [with a flag](../../feature_flags.md) named `geo_proxy_check_pipeline_refs`. Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/434041) in GitLab 16.9.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9779) in GitLab 16.8 [with a flag](../../feature_flags.md) named `geo_proxy_check_pipeline_refs`. Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/434041) in GitLab 16.9.
+
+{{< /history >}}
With [Geo proxying for secondary sites](_index.md), it is possible to register a `gitlab-runner` with a secondary site. This offloads load from the primary instance.
-NOTE:
+{{< alert type="note" >}}
+
The jobs that start during the first stage of a pipeline almost always have their Git clone requests forwarded to the primary site. This is because those clones usually occur before the Git data is replicated and verified by the secondary site. Later stages are not guaranteed to be served by the secondary site either, for example if the Git change is large, bandwidth is small, or pipeline stages are short. In most cases, the subsequent stages of the pipeline serve Git data from the secondary site. [Issue 446176](https://gitlab.com/gitlab-org/gitlab/-/issues/446176) proposes an enhancement to increase the chance of the first stage clone request is served from the secondary site.
+{{< /alert >}}
+
## Use secondary runners with a Location Aware public URL (Unified URL)
Using [Location-Aware DNS](_index.md#configure-location-aware-dns), with the feature flag enabled works with no extra configuration. After you install and register a runner in the same location as a secondary site, it automatically talks to the closest site, and only proxies to the primary if the secondary is out of date.
diff --git a/doc/administration/geo/setup/_index.md b/doc/administration/geo/setup/_index.md
index 84dd9319ccf21c535b3d364c00e5af12fc564bfb..50700fadfe56c3e84d07a88d318ac52ad5c3b894 100644
--- a/doc/administration/geo/setup/_index.md
+++ b/doc/administration/geo/setup/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Setting up Geo
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
## Prerequisites
@@ -15,8 +18,11 @@ DETAILS:
- One GitLab site serves as the Geo **primary** site. Use the [GitLab reference architectures documentation](../../reference_architectures/_index.md) to set this up. You can use different reference architecture sizes for each Geo site. If you already have a working GitLab instance that is in-use, it can be used as a **primary** site.
- The second GitLab site serves as the Geo **secondary** site. Use the [GitLab reference architectures documentation](../../reference_architectures/_index.md) to set this up. It's a good idea to sign in and test it. However, be aware that **all of the data on the secondary are lost** as part of the process of replicating from the **primary** site.
- NOTE:
- Geo supports multiple secondaries. You can follow the same steps and make any changes accordingly.
+ {{< alert type="note" >}}
+
+Geo supports multiple secondaries. You can follow the same steps and make any changes accordingly.
+
+ {{< /alert >}}
- Ensure the **primary** site has a [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) subscription to unlock Geo. You only need one license for all the sites.
- Confirm the [requirements for running Geo](../_index.md#requirements-for-running-geo) are met by all sites. For example, sites must use the same GitLab version, and sites must be able to communicate with each other over certain ports.
diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md
index 91002373a6d75a7c7240e7232480099da04244c0..b7693a4dd18e885b1a916ea261606d7c31840b05 100644
--- a/doc/administration/geo/setup/database.md
+++ b/doc/administration/geo/setup/database.md
@@ -5,22 +5,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo database replication
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This document describes the minimal required steps to replicate your primary
GitLab database to a secondary site's database. You may have to change some
values, based on attributes including your database's setup and size.
-NOTE:
+{{< alert type="note" >}}
+
If your GitLab installation uses external PostgreSQL instances (not managed by a Linux package installation),
the roles cannot perform all necessary configuration steps. In this case, use the
[Geo with external PostgreSQL instances](external_database.md) process instead.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The stages of the setup process must be completed in the documented order.
If not, [complete all prior stages](../setup/_index.md#using-linux-package-installations) before proceeding.
+{{< /alert >}}
Ensure the **secondary** site is running the same version of GitLab Enterprise Edition as the **primary** site. Confirm you have added a license for a [Premium or Ultimate subscription](https://about.gitlab.com/pricing/) to your **primary** site.
@@ -60,10 +68,13 @@ The following guide assumes that:
[versions of PostgreSQL](../_index.md#requirements-for-running-geo),
OS, and GitLab on all sites.
-WARNING:
+{{< alert type="warning" >}}
+
Geo works with streaming replication. Logical replication is not supported at this time.
There is an [issue where support is being discussed](https://gitlab.com/gitlab-org/gitlab/-/issues/7420).
+{{< /alert >}}
+
#### Step 1. Configure the **primary** site
1. SSH into your GitLab **primary** site and sign in as root:
@@ -166,8 +177,11 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
connect to the **primary** site's database. For this reason, you need the IP address of
each site.
- NOTE:
- For external PostgreSQL instances, see [additional instructions](external_database.md).
+ {{< alert type="note" >}}
+
+For external PostgreSQL instances, see [additional instructions](external_database.md).
+
+ {{< /alert >}}
If you are using a cloud provider, you can look up the addresses for each
Geo site through your cloud provider's management console.
@@ -203,11 +217,14 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
corresponding to the given address. See [the PostgreSQL documentation](https://www.postgresql.org/docs/12/runtime-config-connection.html)
for more details.
- NOTE:
- If you need to use `0.0.0.0` or `*` as the `listen_address`, you also must add
+ {{< alert type="note" >}}
+
+If you need to use `0.0.0.0` or `*` as the `listen_address`, you also must add
`127.0.0.1/32` to the `postgresql['md5_auth_cidr_addresses']` setting, to allow Rails to connect through
`127.0.0.1`. For more information, see [issue 5258](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5258).
+ {{< /alert >}}
+
Depending on your network configuration, the suggested addresses may
be incorrect. If your **primary** and **secondary** sites connect over a local
area network, or a virtual network connecting availability zones like the
@@ -338,8 +355,11 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
gitlab-ctl stop sidekiq
```
- NOTE:
- This step is important so you don't try to execute anything before the site is fully configured.
+ {{< alert type="note" >}}
+
+This step is important so you don't try to execute anything before the site is fully configured.
+
+ {{< /alert >}}
1. [Check TCP connectivity](../../raketasks/maintenance.md) to the **primary** site's PostgreSQL server:
@@ -347,13 +367,16 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
gitlab-rake gitlab:tcp_check[<primary_site_ip>,5432]
```
- NOTE:
- If this step fails, you may be using the wrong IP address, or a firewall may
+ {{< alert type="note" >}}
+
+If this step fails, you may be using the wrong IP address, or a firewall may
be preventing access to the site. Check the IP address, paying close
attention to the difference between public and private addresses. Ensure
that, if a firewall is present, the **secondary** site is permitted to connect to the
**primary** site on port 5432.
+ {{< /alert >}}
+
1. Create a file `server.crt` in the **secondary** site, with the content you got on the last step of the **primary** site's setup:
```shell
@@ -390,12 +413,15 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o
-h <primary_site_ip>
```
- NOTE:
- If you are using manually generated certificates and want to use
+ {{< alert type="note" >}}
+
+If you are using manually generated certificates and want to use
`sslmode=verify-full` to benefit from the full hostname verification,
replace `verify-ca` with `verify-full` when
running the command.
+ {{< /alert >}}
+
When prompted, enter the _plaintext_ password you set in the first step for the
`gitlab_replicator` user. If all worked correctly, you should see
the list of the **primary** site's databases.
@@ -463,10 +489,13 @@ needed files for streaming replication.
The directories used are the defaults that are set up in a Linux package installation. If you have
changed any defaults, configure the script accordingly (replacing any directories and paths).
-WARNING:
+{{< alert type="warning" >}}
+
Make sure to run this on the **secondary** site as it removes all PostgreSQL's
data before running `pg_basebackup`.
+{{< /alert >}}
+
1. SSH into your GitLab **secondary** site and sign in as root:
```shell
@@ -481,13 +510,19 @@ data before running `pg_basebackup`.
1. Execute the command below to start a backup/restore and begin the replication
- WARNING:
+ {{< alert type="warning" >}}
+
Each Geo **secondary** site must have its own unique replication slot name.
Using the same slot name between two secondaries breaks PostgreSQL replication.
- NOTE:
+ {{< /alert >}}
+
+ {{< alert type="note" >}}
+
Replication slot names must only contain lowercase letters, numbers, and the underscore character.
+ {{< /alert >}}
+
When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator`
user in the first step.
@@ -498,13 +533,16 @@ data before running `pg_basebackup`.
--sslmode=verify-ca
```
- NOTE:
+ {{< alert type="note" >}}
+
If you have generated custom PostgreSQL certificates, you need to use
`--sslmode=verify-full` (or omit the `sslmode` line entirely), to benefit from the extra
validation of the full host name in the certificate CN / SAN for additional security.
Otherwise, using the automatically created certificate with `verify-full` fails,
as it has a generic `PostgreSQL` CN which doesn't match the `--host` value in this command.
+ {{< /alert >}}
+
This command also takes a number of additional options. You can use `--help`
to list them all, but here are some tips:
@@ -536,9 +574,12 @@ data before running `pg_basebackup`.
The replication process is now complete.
-NOTE:
+{{< alert type="note" >}}
+
The replication process only copies the data from the primary site's database to the secondary site's database. To complete your secondary site configuration, [add the secondary site on your primary site](../replication/configuration.md#step-3-add-the-secondary-site).
+{{< /alert >}}
+
### PgBouncer support (optional)
[PgBouncer](https://www.pgbouncer.org/) may be used with GitLab Geo to pool
@@ -672,9 +713,9 @@ and other database best practices.
Set up a persistent replication slot on the primary database to ensure continuous data replication from the primary
database to the Patroni cluster on the secondary node.
-::Tabs
+{{< tabs >}}
-:::TabTitle Primary with Patroni cluster
+{{< tab title="Primary with Patroni cluster" >}}
To set up database replication with Patroni on a secondary site, you must
configure a _permanent replication slot_ on the primary site's Patroni cluster,
@@ -739,7 +780,9 @@ Leader instance**:
gitlab-ctl reconfigure
```
-:::TabTitle Primary with single PostgreSQL instance
+{{< /tab >}}
+
+{{< tab title="Primary with single PostgreSQL instance" >}}
1. SSH into your single node instance and sign in as root:
@@ -801,7 +844,9 @@ Leader instance**:
GRANT EXECUTE ON FUNCTION public.pg_shadow_lookup(text) TO pgbouncer;
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
##### Step 2. Configure the internal load balancer on the primary site
@@ -912,10 +957,13 @@ On each node running a PgBouncer instance on the **secondary** site:
##### Step 4. Configure a Standby cluster on the secondary site
-NOTE:
+{{< alert type="note" >}}
+
If you are converting a secondary site with a single PostgreSQL instance to a Patroni Cluster, you must start on the PostgreSQL instance. It becomes the Patroni Standby Leader instance,
and then you can switch over to another replica if you need to.
+{{< /alert >}}
+
For each node running a Patroni instance on the secondary site:
1. SSH into your Patroni node and sign in as root:
diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md
index e6d382277b150cf479a33dcf40ec6e94dcf72723..a73c0d9dcfece04e90afcd94a8b760e9e58828fc 100644
--- a/doc/administration/geo/setup/external_database.md
+++ b/doc/administration/geo/setup/external_database.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo with external PostgreSQL instances
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This document is relevant if you are using a PostgreSQL instance that is not
managed by the Linux package. This includes
@@ -19,12 +22,15 @@ the [Linux package ships with](../../package_information/postgresql_versions.md)
to [avoid version mismatches](../_index.md#requirements-for-running-geo)
in case a Geo site has to be rebuilt.
-NOTE:
+{{< alert type="note" >}}
+
If you’re using GitLab Geo, we strongly recommend running instances installed by using the Linux package or using
[validated cloud-managed instances](../../reference_architectures/_index.md#recommended-cloud-providers-and-services),
as we actively develop and test based on those.
We cannot guarantee compatibility with other external databases.
+{{< /alert >}}
+
## **Primary** site
1. SSH into a **Rails node on your primary** site and login as root:
@@ -85,11 +91,14 @@ cloud providers:
When your read-only replica is set up, you can skip to [configure your secondary site](#configure-secondary-site-to-use-the-external-read-replica)
-WARNING:
+{{< alert type="warning" >}}
+
The use of logical replication methods such as [AWS Database Migration Service](https://aws.amazon.com/dms/)
or [Google Cloud Database Migration Service](https://cloud.google.com/database-migration) to, for instance,
replicate from an on-premise primary database to an RDS secondary are not supported.
+{{< /alert >}}
+
#### Manually configure the primary database for replication
The [`geo_primary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles)
@@ -212,13 +221,16 @@ to grant additional roles to your tracking database user (by default, this is
This is for the installation of extensions during installation and upgrades. As an alternative,
[ensure the extensions are installed manually, and read about the problems that may arise during future GitLab upgrades](../../../install/postgresql_extensions.md).
-NOTE:
+{{< alert type="note" >}}
+
If you want to use Amazon RDS as a tracking database, make sure it has access to
the secondary database. Unfortunately, just assigning the same security group is not enough as
outbound rules do not apply to RDS PostgreSQL databases. Therefore, you need to explicitly add an inbound
rule to the read-replica's security group allowing any TCP traffic from
the tracking database on port 5432.
+{{< /alert >}}
+
#### Create the tracking database
Create and configure the tracking database in your PostgreSQL instance:
diff --git a/doc/administration/geo/setup/two_single_node_external_services.md b/doc/administration/geo/setup/two_single_node_external_services.md
index e152e68c0989776a85e4638d45bc8361eccaccad..9551ff4b3bf75b76d6029c15325ce4ee5df64042 100644
--- a/doc/administration/geo/setup/two_single_node_external_services.md
+++ b/doc/administration/geo/setup/two_single_node_external_services.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Set up Geo for two single-node sites (with external PostgreSQL services)
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following guide provides concise instructions on how to deploy GitLab Geo for a two single-node site installation using two Linux package instances and external PostgreSQL databases like RDS, Azure Database, or Google Cloud SQL.
@@ -280,11 +283,14 @@ After the initial replication process is complete, follow the steps to
Fast lookup is [required for Geo](../../operations/fast_ssh_key_lookup.md#fast-lookup-is-required-for-geo).
-NOTE:
+{{< alert type="note" >}}
+
Authentication is handled by the primary site. Don't set up custom authentication for the secondary site.
Any change that requires access to the **Admin** area should be made in the primary site, because the
secondary site is a read-only copy.
+{{< /alert >}}
+
#### Add the secondary site
1. SSH into each Rails and Sidekiq node on your secondary site and sign in as root:
@@ -395,9 +401,12 @@ site **Geo Sites** dashboard in your browser.
## Configure the tracking database
-NOTE:
+{{< alert type="note" >}}
+
This step is optional in case you also want to have your tracking database set up externally on another server.
+{{< /alert >}}
+
**Secondary** sites use a separate PostgreSQL installation as a tracking
database to keep track of replication status and automatically recover from
potential replication issues. The Linux package automatically configures a tracking database
@@ -417,13 +426,16 @@ to grant additional roles to your tracking database user (by default, this is
Additional roles are needed for the installation of extensions during installation and upgrades. As an alternative,
[ensure the extensions are installed manually, and read about the problems that may arise during future GitLab upgrades](../../../install/postgresql_extensions.md).
-NOTE:
+{{< alert type="note" >}}
+
If you want to use Amazon RDS as a tracking database, make sure it has access to
the secondary database. Unfortunately, just assigning the same security group is not enough as
outbound rules do not apply to RDS PostgreSQL databases. Therefore, you need to explicitly add an inbound
rule to the read-replica's security group allowing any TCP traffic from
the tracking database on port 5432.
+{{< /alert >}}
+
### Create the tracking database
Create and configure the tracking database in your PostgreSQL instance:
diff --git a/doc/administration/geo/setup/two_single_node_sites.md b/doc/administration/geo/setup/two_single_node_sites.md
index bc3f97c6ffe67776e676f849e8f51a3032c45372..cd2b9d4385e3f46529463a53a7dd9a79e7a9b630 100644
--- a/doc/administration/geo/setup/two_single_node_sites.md
+++ b/doc/administration/geo/setup/two_single_node_sites.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Set up Geo for two single-node sites
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following guide provides concise instructions on how to deploy GitLab Geo for a two single-node site installation using two Linux package instances with no external services set up.
@@ -62,11 +65,14 @@ Prerequisites:
1. Create a password for the `gitlab` database user and update Rail to use the new password.
- NOTE:
+ {{< alert type="note" >}}
+
The values configured for the `gitlab_rails['db_password']` and `postgresql['sql_user_password']` settings need to match.
However, only the `postgresql['sql_user_password']` value should be the MD5 encrypted password.
Changes to this are being discussed in [Rethink how we handle PostgreSQL passwords in cookbooks](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5713).
+ {{< /alert >}}
+
1. Generate a MD5 hash of the desired password:
```shell
@@ -156,11 +162,14 @@ Prerequisites:
private addresses (which correspond to "internal address" for Google Cloud Platform) for
`postgresql['md5_auth_cidr_addresses']` and `postgresql['listen_address']`.
- NOTE:
+ {{< alert type="note" >}}
+
If you need to use `0.0.0.0` or `*` as the `listen_address`, you also must add
`127.0.0.1/32` to the `postgresql['md5_auth_cidr_addresses']` setting, to allow
Rails to connect through `127.0.0.1`. For more information, see [issue 5258](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5258).
+ {{< /alert >}}
+
Depending on your network configuration, the suggested addresses might
be incorrect. If your primary and secondary sites connect over a local
area network, or a virtual network connecting availability zones like the
@@ -354,11 +363,14 @@ The script uses the default Linux package directories.
If you changed the defaults, replace the directory and path
names in the script below with your own names.
-WARNING:
+{{< alert type="warning" >}}
+
Run the replication script on only the secondary site.
The script removes all PostgreSQL data before it runs `pg_basebackup`,
which can lead to data loss.
+{{< /alert >}}
+
To replicate the database:
1. SSH into your GitLab secondary site and sign in as root:
@@ -375,10 +387,13 @@ To replicate the database:
1. Execute the following command to back up and restore the database, and begin the replication.
- WARNING:
+ {{< alert type="warning" >}}
+
Each Geo secondary site must have its own unique replication slot name.
Using the same slot name between two secondaries breaks PostgreSQL replication.
+ {{< /alert >}}
+
```shell
gitlab-ctl replicate-geo-database \
--slot-name=<secondary_site_name> \
@@ -400,11 +415,14 @@ Follow the documentation to [configure fast lookup of authorized SSH keys](../..
Fast lookup is [required for Geo](../../operations/fast_ssh_key_lookup.md#fast-lookup-is-required-for-geo).
-NOTE:
+{{< alert type="note" >}}
+
Authentication is handled by the primary site. Don't set up custom authentication for the secondary site.
Any change that requires access to the **Admin** area should be made in the primary site, because the
secondary site is a read-only copy.
+{{< /alert >}}
+
### Manually replicate secret GitLab values
GitLab stores a number of secret values in `/etc/gitlab/gitlab-secrets.json`.
diff --git a/doc/administration/geo_sites.md b/doc/administration/geo_sites.md
index 14fdf4c081e5d9044a4728a5dc367ac078da9e84..9169c2ad92e0c689cf1fdaff1a65a73a66faeb3e 100644
--- a/doc/administration/geo_sites.md
+++ b/doc/administration/geo_sites.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo sites Admin area
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can configure various settings for GitLab Geo sites. For more information, see
[Geo documentation](geo/_index.md).
@@ -82,12 +85,15 @@ The internal URL defaults to external URL. To change it:
When enabled, the **Admin** area for Geo shows replication details for each site directly
from the primary site's UI, and through the Geo secondary proxy, if enabled.
-WARNING:
+{{< alert type="warning" >}}
+
We recommend using an HTTPS connection while configuring the Geo sites. To avoid
breaking communication between **primary** and **secondary** sites when using
HTTPS, customize your Internal URL to point to a load balancer with TLS
terminated at the load balancer.
+{{< /alert >}}
+
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md
index 769ee0c9a07df575a8f45bd8488082fc4713d093..e8e754f57023fd061d34160715ab5264cd290065 100644
--- a/doc/administration/get_started.md
+++ b/doc/administration/get_started.md
@@ -1,14 +1,17 @@
---
stage: none
group: Tutorials
-description: Administration overview.
info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Administration overview.
title: Get started administering GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Get started with GitLab administration. Configure your organization and its authentication, then secure, monitor,
and back up GitLab.
@@ -192,9 +195,12 @@ It is common for a VM snapshot to require you to power down the server.
#### Option 2: GitLab Geo
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Geo provides local, read-only instances of your GitLab instances.
diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md
index 69a35b7de5c94d81257ab0efd1e9927f34ee4909..a3c2d2ebcf4cd8ada199fdf955b526ca16479076 100644
--- a/doc/administration/git_protocol.md
+++ b/doc/administration/git_protocol.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Set and configure Git protocol v2 for GitLab Self-Managed."
+description: Set and configure Git protocol v2 for GitLab Self-Managed.
title: Configuring Git Protocol v2
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Git protocol v2 improves the v1 wire protocol in several ways and is
enabled by default in GitLab for HTTP requests. To enable SSH, additional
diff --git a/doc/administration/gitaly/_index.md b/doc/administration/gitaly/_index.md
index f6eebfd50ed460fc4ae25658f071a0779acf3854..d7876cad4b47855a9c861658b64776706bb7bc6c 100644
--- a/doc/administration/gitaly/_index.md
+++ b/doc/administration/gitaly/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Gitaly and Gitaly Cluster
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
[Gitaly](https://gitlab.com/gitlab-org/gitaly) provides high-level RPC access to Git repositories.
It is used by GitLab to read and write Git data.
@@ -121,9 +124,12 @@ your assumptions, resulting in performance degradation, instability, and even da
[distributed reads](#distributed-reads), that depend on the gRPC interface and database
to determine repository state.
-WARNING:
+{{< alert type="warning" >}}
+
Accessing Git repositories directly is done at your own risk and is not supported.
+{{< /alert >}}
+
## Gitaly
The following shows GitLab set up to use direct access to Gitaly:
@@ -184,7 +190,11 @@ best suited by using Gitaly Cluster.
### Gitaly CLI
-> - `gitaly git` subcommand [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/7119) in GitLab 17.4.
+{{< history >}}
+
+- `gitaly git` subcommand [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/7119) in GitLab 17.4.
+
+{{< /history >}}
The `gitaly` command is a command-line interface that provides additional subcommands for Gitaly administrators. For example,
the Gitaly CLI is used to:
@@ -233,10 +243,13 @@ Using a Gitaly Cluster increases fault tolerance by:
- Detecting Gitaly node failures.
- Automatically routing Git requests to an available Gitaly node.
-NOTE:
+{{< alert type="note" >}}
+
Technical support for Gitaly clusters is limited to GitLab Premium and Ultimate
customers.
+{{< /alert >}}
+
The following shows GitLab set up to access `storage-1`, a virtual storage provided by Gitaly
Cluster:
@@ -266,10 +279,13 @@ The availability objectives for Gitaly clusters assuming a single node failure a
Improvements to RPO and RTO are proposed in epic [8903](https://gitlab.com/groups/gitlab-org/-/epics/8903).
-WARNING:
+{{< alert type="warning" >}}
+
If complete cluster failure occurs, disaster recovery plans should be executed. These can affect the
RPO and RTO discussed above.
+{{< /alert >}}
+
### Comparison to Geo
Gitaly Cluster and [Geo](../geo/_index.md) both provide redundancy. However the redundancy of:
@@ -321,11 +337,14 @@ As with standard Gitaly storages, virtual storages can be sharded.
### Storage layout
-WARNING:
+{{< alert type="warning" >}}
+
The storage layout is an internal detail of Gitaly Cluster and is not guaranteed to remain stable between releases.
The information here is only for informational purposes and to help with debugging. Performing changes in the
repositories directly on the disk is not supported and may lead to breakage or the changes being overwritten.
+{{< /alert >}}
+
Gitaly Cluster's virtual storages provide an abstraction that looks like a single storage but actually consists of
multiple physical storages. Gitaly Cluster has to replicate each operation to each physical storage. Operations
may succeed on some of the physical storages but fail on others.
@@ -361,10 +380,14 @@ follow the [hashed storage](../repository_storage_paths.md#hashed-storage) schem
#### Praefect-generated replica paths
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4218) in GitLab 15.0 [with a flag](../feature_flags.md) named `gitaly_praefect_generated_replica_paths`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitaly/-/issues/4218) in GitLab 15.2.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4809) in GitLab 15.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4941) in GitLab 15.6. Feature flag `gitaly_praefect_generated_replica_paths` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4218) in GitLab 15.0 [with a flag](../feature_flags.md) named `gitaly_praefect_generated_replica_paths`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitaly/-/issues/4218) in GitLab 15.2.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4809) in GitLab 15.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4941) in GitLab 15.6. Feature flag `gitaly_praefect_generated_replica_paths` removed.
+
+{{< /history >}}
When Gitaly Cluster creates a repository, it assigns the repository a unique and permanent ID called the _repository ID_. The repository ID is
internal to Gitaly Cluster and doesn't relate to any IDs elsewhere in GitLab. If a repository is removed from Gitaly Cluster and later moved
@@ -585,9 +608,12 @@ To downgrade a Gitaly Cluster (assuming multiple Praefect nodes):
### Migrate to Gitaly Cluster
-WARNING:
+{{< alert type="warning" >}}
+
Some [known issues](#known-issues) exist in Gitaly Cluster. Review the following information before you continue.
+{{< /alert >}}
+
Before migrating to Gitaly Cluster:
- Review [Before deploying Gitaly Cluster](#before-deploying-gitaly-cluster).
diff --git a/doc/administration/gitaly/bundle_uris.md b/doc/administration/gitaly/bundle_uris.md
index 000712c252d922b20e0e1bad8ef24fc13d6c7aa5..79cf69b30045b4de639c0c94df7579301daf7efb 100644
--- a/doc/administration/gitaly/bundle_uris.md
+++ b/doc/administration/gitaly/bundle_uris.md
@@ -5,18 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Bundle URIs
---
-DETAILS:
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8939) in GitLab 17.0 [with a flag](../feature_flags.md) named `gitaly_bundle_uri`. Disabled by default.
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8939) in GitLab 17.0 [with a flag](../feature_flags.md) named `gitaly_bundle_uri`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available.
To make it available, an administrator can [enable the feature flag](../feature_flags.md)
named `gitaly_bundle_uri`.
On GitLab.com and GitLab Dedicated, this feature is not available. This feature
is not ready for production use.
+{{< /alert >}}
+
Gitaly supports Git [bundle URIs](https://git-scm.com/docs/bundle-uri). Bundle
URIs are locations where Git can download one or more bundles to bootstrap the
object database before fetching the remaining objects from a remote. Bundle URIs
@@ -56,9 +66,9 @@ installation you have. For self-compiled installations, you must set the
`AZURE_STORAGE_ACCOUNT` and `AZURE_STORAGE_KEY` environment variables outside of
GitLab.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and configure the `bundle_uri.go_cloud_url`:
@@ -74,7 +84,9 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
@@ -83,7 +95,9 @@ Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
go_cloud_url = "azblob://<bucket>"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure Google Cloud storage
@@ -100,9 +114,9 @@ For more information, see
The destination bucket is configured using the `go_cloud_url` option.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and configure the `go_cloud_url`:
@@ -117,7 +131,9 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
@@ -126,7 +142,9 @@ Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
go_cloud_url = "gs://<bucket>"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure S3 storage
@@ -142,9 +160,9 @@ For more information, see
The destination bucket and region are configured using the `go_cloud_url` option.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and configure the `go_cloud_url`:
@@ -160,7 +178,9 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
@@ -169,7 +189,9 @@ Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
go_cloud_url = "s3://<bucket>?region=us-west-1"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Configure S3-compatible servers
@@ -183,9 +205,9 @@ The following parameters are supported:
- `disabledSSL`: A value of `true` disables SSL.
- `s3ForcePathStyle`: A value of `true` forces path-style addressing.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and configure the `go_cloud_url`:
@@ -201,7 +223,9 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
@@ -210,7 +234,9 @@ Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
go_cloud_url = "s3://<bucket>?region=minio&endpoint=my.minio.local:8080&disableSSL=true&s3ForcePathStyle=true"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Generating bundles
diff --git a/doc/administration/gitaly/concurrency_limiting.md b/doc/administration/gitaly/concurrency_limiting.md
index f9eb9662f1bdd3723c49575c99751266de12866e..c86033f6c869ee5c947862f8d23acb8c1789dc95 100644
--- a/doc/administration/gitaly/concurrency_limiting.md
+++ b/doc/administration/gitaly/concurrency_limiting.md
@@ -12,13 +12,16 @@ To avoid overwhelming the servers running Gitaly, you can limit concurrency of:
These limits can be fixed, or set as adaptive.
-WARNING:
+{{< alert type="warning" >}}
+
Enabling limits on your environment should be done with caution and only
in select circumstances, such as to protect against unexpected traffic.
When reached, limits _do_ result in disconnects that negatively impact users.
For consistent and stable performance, you should first explore other options such as
adjusting node specifications, and [reviewing large repositories](../../user/project/repository/monorepos/_index.md) or workloads.
+{{< /alert >}}
+
## Limit RPC concurrency
When cloning or pulling repositories, various RPCs run in the background. In particular, the Git pack RPCs:
@@ -72,16 +75,23 @@ repository. In the example above:
- If a request waits in the queue for more than 1 second, it is rejected with an error.
- If the queue grows beyond 10, subsequent requests are rejected with an error.
-NOTE:
+{{< alert type="note" >}}
+
When these limits are reached, users are disconnected.
+{{< /alert >}}
+
You can observe the behavior of this queue using the Gitaly logs and Prometheus. For more
information, see the [relevant documentation](monitoring.md#monitor-gitaly-concurrency-limiting).
## Limit pack-objects concurrency
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7891) in GitLab 15.11 [with a flag](../feature_flags.md) named `gitaly_pack_objects_limiting_remote_ip`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5772) in GitLab 16.0. Feature flag `gitaly_pack_objects_limiting_remote_ip` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7891) in GitLab 15.11 [with a flag](../feature_flags.md) named `gitaly_pack_objects_limiting_remote_ip`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5772) in GitLab 16.0. Feature flag `gitaly_pack_objects_limiting_remote_ip` removed.
+
+{{< /history >}}
Gitaly triggers `git-pack-objects` processes when handling both SSH and HTTPS traffic to clone or pull repositories. These processes generate a `pack-file` and can
consume a significant amount of resources, especially in situations such as unexpectedly high traffic or concurrent pulls from a large repository. On GitLab.com, we also
@@ -90,11 +100,14 @@ observe problems with clients that have slow internet connections.
You can limit these processes from overwhelming your Gitaly server by setting pack-objects concurrency limits in the Gitaly configuration file. This setting limits the
number of in-flight pack-object processes per remote IP address.
-WARNING:
+{{< alert type="warning" >}}
+
Only enable these limits on your environment with caution and only in select circumstances, such as to protect against unexpected traffic. When reached, these limits
disconnect users. For consistent and stable performance, you should first explore other options such as adjusting node specifications, and
[reviewing large repositories](../../user/project/repository/monorepos/_index.md) or workloads.
+{{< /alert >}}
+
Example configuration:
```ruby
@@ -124,7 +137,11 @@ You can observe the behavior of this queue using Gitaly logs and Prometheus. For
## Adaptive concurrency limiting
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6.
+
+{{< /history >}}
Gitaly supports two concurrency limits:
diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md
index a9acfc5c38fa69886f946aae1fd268055c9cff0c..4e3c49147948283f0a0b0d15a5cc000887fc4089 100644
--- a/doc/administration/gitaly/configure_gitaly.md
+++ b/doc/administration/gitaly/configure_gitaly.md
@@ -5,31 +5,40 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure Gitaly
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Configure Gitaly in one of two ways:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add or change the
[Gitaly settings](https://gitlab.com/gitlab-org/gitaly/-/blob/master/config.toml.example).
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Configure the [Gitaly chart](https://docs.gitlab.com/charts/charts/gitlab/gitaly/).
1. [Upgrade your Helm release](https://docs.gitlab.com/charts/installation/deployment.html).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitaly/config.toml` and add or change the [Gitaly settings](https://gitlab.com/gitlab-org/gitaly/blob/master/config.toml.example).
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
The following configuration options are also available:
@@ -55,12 +64,17 @@ this default configuration used by:
However, Gitaly can be deployed to its own server, which can benefit GitLab installations that span
multiple machines.
-NOTE:
+{{< alert type="note" >}}
+
When configured to run on their own servers, Gitaly servers must be
[upgraded](../../update/package/_index.md) before Gitaly clients in your cluster.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
[Disk requirements](_index.md#disk-requirements) apply to Gitaly nodes.
+{{< /alert >}}
The process for setting up Gitaly on its own server is:
@@ -100,11 +114,14 @@ the default ports for HTTP and HTTPs communication.
-WARNING:
+{{< alert type="warning" >}}
+
Gitaly servers must not be exposed to the public internet as Gitaly network traffic is unencrypted
by default. The use of firewall is highly recommended to restrict access to the Gitaly server.
Another option is to [use TLS](tls_support.md).
+{{< /alert >}}
+
In the following sections, we describe how to configure two Gitaly servers with secret token
`abc123secret`:
@@ -147,9 +164,9 @@ Gitaly and GitLab use two shared secrets for authentication:
- _Gitaly token_: used to authenticate gRPC requests to Gitaly.
- _GitLab Shell token_: used for authentication callbacks from GitLab Shell to the GitLab internal API.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. To configure the _Gitaly token_, edit `/etc/gitlab/gitlab.rb`:
@@ -190,7 +207,9 @@ Gitaly and GitLab use two shared secrets for authentication:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Copy `/home/git/gitlab/.gitlab_shell_secret` from the Gitaly client to the same path on the
Gitaly servers (and any other Gitaly clients).
@@ -212,7 +231,9 @@ Gitaly and GitLab use two shared secrets for authentication:
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Configure Gitaly server
@@ -226,9 +247,9 @@ Updates to example must be made at:
Configure Gitaly server.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -323,7 +344,9 @@ Configure Gitaly server.
- For GitLab 15.3 and later, run `sudo -u git -- /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml`.
- For GitLab 15.2 and earlier, run `sudo -u git -- /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml`.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitaly/config.toml`:
@@ -371,23 +394,31 @@ Configure Gitaly server.
- For GitLab 15.3 and later, run `sudo -u git -- /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml`.
- For GitLab 15.2 and earlier, run `sudo -u git -- /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml`.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
+
+{{< alert type="warning" >}}
-WARNING:
If directly copying repository data from a GitLab server to Gitaly, ensure that the metadata file,
default path `/var/opt/gitlab/git-data/repositories/.gitaly-metadata`, is not included in the transfer.
Copying this file causes GitLab to use the direct disk access to repositories hosted on the Gitaly server,
leading to `Error creating pipeline` and `Commit not found` errors, or stale data.
+{{< /alert >}}
+
### Configure Gitaly clients
As the final step, you must update Gitaly clients to switch from using local Gitaly service to use
the Gitaly servers you just configured.
-NOTE:
+{{< alert type="note" >}}
+
GitLab requires a `default` repository storage to be configured.
[Read more about this limitation](#gitlab-requires-a-default-repository-storage).
+{{< /alert >}}
+
This can be risky because anything that prevents your Gitaly clients from reaching the Gitaly
servers causes all Gitaly requests to fail. For example, any sort of network, firewall, or name
resolution problems.
@@ -408,9 +439,9 @@ server (with `gitaly_address`) unless you use
Configure Gitaly clients in one of two ways. These instructions are for unencrypted connections but you can also enable [TLS support](tls_support.md):
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -444,7 +475,9 @@ Configure Gitaly clients in one of two ways. These instructions are for unencryp
sudo gitlab-ctl tail gitaly
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -472,16 +505,21 @@ Configure Gitaly clients in one of two ways. These instructions are for unencryp
tail -f /home/git/gitlab/log/gitaly.log
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
When you tail the Gitaly logs on your Gitaly server, you should see requests coming in. One sure way
to trigger a Gitaly request is to clone a repository from GitLab over HTTP or HTTPS.
-WARNING:
+{{< alert type="warning" >}}
+
If you have [server hooks](../server_hooks.md) configured, either per repository or globally, you
must move these to the Gitaly servers. If you have multiple Gitaly servers, copy your server hooks
to all Gitaly servers.
+{{< /alert >}}
+
#### Mixed configuration
GitLab can reside on the same server as one of many Gitaly servers, but doesn't support
@@ -557,9 +595,9 @@ a valid configuration (some machines much act as Gitaly servers).
Disable Gitaly on a GitLab server in one of two ways:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -569,7 +607,9 @@ Disable Gitaly on a GitLab server in one of two ways:
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/etc/default/gitlab`:
@@ -579,17 +619,22 @@ Disable Gitaly on a GitLab server in one of two ways:
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Control groups
-WARNING:
+{{< alert type="warning" >}}
+
Enabling limits on your environment should be done with caution and only
in select circumstances, such as to protect against unexpected traffic.
When reached, limits _do_ result in disconnects that negatively impact users.
For consistent and stable performance, you should first explore other options such as
adjusting node specifications, and [reviewing large repositories](../../user/project/repository/monorepos/_index.md) or workloads.
+{{< /alert >}}
+
When enabling cgroups for memory, you should ensure that no swap is configured on the Gitaly nodes as
processes may switch to using that instead of being terminated. This situation could lead to notably compromised
performance.
@@ -618,15 +663,22 @@ When a repository cgroup reaches its:
- Memory limit, the kernel looks through the processes for a candidate to kill.
- CPU limit, processes are not killed, but the processes are prevented from consuming more CPU than allowed.
-NOTE:
+{{< alert type="note" >}}
+
When these limits are reached, performance may be reduced and users may be disconnected.
+{{< /alert >}}
+
### Configure repository cgroups
-> - This method of configuring repository cgroups was introduced in GitLab 15.1.
-> - `cpu_quota_us`[introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5422) in GitLab 15.10.
-> - `max_cgroups_per_repo` [introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5689) in GitLab 16.7.
-> - Documentation for the legacy method was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176694) in GitLab 17.8.
+{{< history >}}
+
+- This method of configuring repository cgroups was introduced in GitLab 15.1.
+- `cpu_quota_us`[introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5422) in GitLab 15.10.
+- `max_cgroups_per_repo` [introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5689) in GitLab 16.7.
+- Documentation for the legacy method was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176694) in GitLab 17.8.
+
+{{< /history >}}
To configure repository cgroups in Gitaly, use the following settings for `gitaly['configuration'][:cgroups]` in `/etc/gitlab/gitlab.rb`:
@@ -713,15 +765,18 @@ Empty directories and unneeded configuration settings may accumulate in a reposi
slow down Git operations. Gitaly can schedule a daily background task with a maximum duration
to clean up these items and improve performance.
-WARNING:
+{{< alert type="warning" >}}
+
Background repository optimization is an experimental feature and may place significant load on the host while running.
Make sure to schedule this during off-peak hours and keep the duration short (for example, 30-60 minutes).
+{{< /alert >}}
+
Configure background repository optimization in one of two ways:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and add:
@@ -738,7 +793,9 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and add:
@@ -750,7 +807,9 @@ duration = '30m'
storages = ["default"]
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Rotate Gitaly authentication token
@@ -855,9 +914,12 @@ gitaly['configuration'] = {
}
```
-WARNING:
+{{< alert type="warning" >}}
+
Without completing this step, you have **no Gitaly authentication**.
+{{< /alert >}}
+
### Verify authentication is enforced
Refresh your [Prometheus query](#verify-authentication-monitoring). You should now see a similar
@@ -871,9 +933,12 @@ result as you did at the start. For example:
## Pack-objects cache
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
[Gitaly](_index.md), the service that provides storage for Git
repositories, can be configured to cache a short rolling window of Git
@@ -958,10 +1023,13 @@ should be:
- On a disk with enough IO bandwidth. If the cache disk runs out of IO bandwidth, all
fetches, and probably the entire server, slows down.
-WARNING:
+{{< alert type="warning" >}}
+
All existing data in the specified directory will be removed.
Take care not to use a directory with existing data.
+{{< /alert >}}
+
By default, the cache storage directory is set to a subdirectory of the first Gitaly storage
defined in the configuration file.
@@ -1005,7 +1073,11 @@ the deleted file have closed it.
#### Minimum key occurrences `min_occurrences`
-> - [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/2222) in GitLab 15.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/2222) in GitLab 15.11.
+
+{{< /history >}}
The `min_occurrences` setting controls how often an identical request
must occur before we create a new cache entry. The default value is `1`,
@@ -1024,7 +1096,11 @@ the cache hit rate.
### Observe the cache
-> - Logs for pack-objects caching was [changed](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5719) in GitLab 16.0.
+{{< history >}}
+
+- Logs for pack-objects caching was [changed](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5719) in GitLab 16.0.
+
+{{< /history >}}
You can observe the cache [using metrics](monitoring.md#pack-objects-cache) and in the following logged information. These logs are part of the gRPC logs and can
be discovered when a call is executed.
@@ -1113,16 +1189,23 @@ Configure the `cat-file` cache in the [Gitaly configuration file](reference.md).
## Configure commit signing for GitLab UI commits
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19185) in GitLab 15.4.
-> - Displaying **Verified** badge for signed GitLab UI commits [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124218) in GitLab 16.3 [with a flag](../feature_flags.md) named `gitaly_gpg_signing`. Disabled by default.
-> - Verifying the signatures using multiple keys specified in `rotated_signing_keys` option [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6163) in GitLab 16.3.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6876) on GitLab Self-Managed and GitLab Dedicated in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19185) in GitLab 15.4.
+- Displaying **Verified** badge for signed GitLab UI commits [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124218) in GitLab 16.3 [with a flag](../feature_flags.md) named `gitaly_gpg_signing`. Disabled by default.
+- Verifying the signatures using multiple keys specified in `rotated_signing_keys` option [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6163) in GitLab 16.3.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6876) on GitLab Self-Managed and GitLab Dedicated in GitLab 17.0.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is available. To hide the feature,
an administrator can [disable the feature flag](../feature_flags.md) named `gitaly_gpg_signing`.
On GitLab.com, this feature is not available. On GitLab Dedicated, this feature is available.
+{{< /alert >}}
+
By default, Gitaly doesn't sign commits made using GitLab UI. For example, commits made using:
- Web editor.
@@ -1146,9 +1229,9 @@ the rotated keys one by one until it succeeds. Set the `rotated_signing_keys` op
Configure Gitaly to sign commits made with the GitLab UI in one of two ways:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. [Create a GPG key](../../user/project/repository/signed_commits/gpg.md#create-a-gpg-key)
and export it, or [create an SSH key](../../user/ssh.md#generate-an-ssh-key-pair). For optimal performance, use an EdDSA key.
@@ -1184,7 +1267,9 @@ Configure Gitaly to sign commits made with the GitLab UI in one of two ways:
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. [Create a GPG key](../../user/project/repository/signed_commits/gpg.md#create-a-gpg-key)
and export it, or [create an SSH key](../../user/ssh.md#generate-an-ssh-key-pair). For optimal performance, use an EdDSA key.
@@ -1214,11 +1299,17 @@ Configure Gitaly to sign commits made with the GitLab UI in one of two ways:
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Generate configuration using an external command
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4828) in GitLab 15.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4828) in GitLab 15.11.
+
+{{< /history >}}
You can generate parts of the Gitaly configuration using an external command. You might do this:
@@ -1240,9 +1331,9 @@ JSON.generate({"gitlab": {"http_settings": {"password": `aws get-secret-value --
You must then make the script path known to Gitaly in one of two ways:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and configure the `config_command`:
@@ -1252,7 +1343,9 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and configure `config_command`:
@@ -1260,7 +1353,9 @@ Edit `/home/git/gitaly/config.toml` and configure `config_command`:
config_command = "/path/to/config_command"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
After configuration, Gitaly executes the command on startup and parses its
standard output as JSON. The resulting configuration is then merged back into
@@ -1273,10 +1368,14 @@ Gitaly fails to start up if either:
## Configure server-side backups
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4941) in GitLab 16.3.
-> - Server-side support for restoring a specified backup instead of the latest backup [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132188) in GitLab 16.6.
-> - Server-side support for creating incremental backups [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6475) in GitLab 16.6.
-> - Server-side support added to Helm chart installations in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4941) in GitLab 16.3.
+- Server-side support for restoring a specified backup instead of the latest backup [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132188) in GitLab 16.6.
+- Server-side support for creating incremental backups [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6475) in GitLab 16.6.
+- Server-side support added to Helm chart installations in GitLab 17.0.
+
+{{< /history >}}
Repository backups can be configured so that the Gitaly node that hosts each
repository is responsible for creating the backup and streaming it to
@@ -1293,9 +1392,9 @@ After configuring server-side backups, you can
How you configure Azure Blob storage for backups depends on the type of installation you have. For self-compiled installations, you must set
the `AZURE_STORAGE_ACCOUNT` and `AZURE_STORAGE_KEY` environment variables outside of GitLab.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and configure the `go_cloud_url`:
@@ -1311,12 +1410,16 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
For Helm-based deployments, see the
[server-side backup documentation for Gitaly chart](https://docs.gitlab.com/charts/charts/gitlab/gitaly/#server-side-backups).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
@@ -1325,7 +1428,9 @@ Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
go_cloud_url = "azblob://<bucket>"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure Google Cloud storage
@@ -1339,9 +1444,9 @@ For more information, see [Application Default Credentials](https://cloud.google
The destination bucket is configured using the `go_cloud_url` option.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and configure the `go_cloud_url`:
@@ -1356,12 +1461,16 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
For Helm-based deployments, see the
[server-side backup documentation for Gitaly chart](https://docs.gitlab.com/charts/charts/gitlab/gitaly/#server-side-backups).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
@@ -1370,7 +1479,9 @@ Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
go_cloud_url = "gs://<bucket>"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure S3 storage
@@ -1384,9 +1495,9 @@ For more information, see [AWS Session documentation](https://docs.aws.amazon.co
The destination bucket and region are configured using the `go_cloud_url` option.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and configure the `go_cloud_url`:
@@ -1402,12 +1513,16 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
For Helm-based deployments, see the
[server-side backup documentation for Gitaly chart](https://docs.gitlab.com/charts/charts/gitlab/gitaly/#server-side-backups).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
@@ -1416,7 +1531,9 @@ Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
go_cloud_url = "s3://<bucket>?region=us-west-1"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Configure S3-compatible servers
@@ -1429,14 +1546,16 @@ The following parameters are supported:
- `disabledSSL`: A value of `true` disables SSL.
- `s3ForcePathStyle`: A value of `true` forces path-style addressing.
-::Tabs
+{{< tabs >}}
-:::TabTitle Helm chart (Kubernetes)
+{{< tab title="Helm chart (Kubernetes)" >}}
For Helm-based deployments, see the
[server-side backup documentation for Gitaly chart](https://docs.gitlab.com/charts/charts/gitlab/gitaly/#server-side-backups).
-:::TabTitle Linux package (Omnibus)
+{{< /tab >}}
+
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb` and configure the `go_cloud_url`:
@@ -1452,7 +1571,9 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
@@ -1461,4 +1582,6 @@ Edit `/home/git/gitaly/config.toml` and configure `go_cloud_url`:
go_cloud_url = "s3://<bucket>?region=minio&endpoint=my.minio.local:8080&disableSSL=true&s3ForcePathStyle=true"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/administration/gitaly/kubernetes.md b/doc/administration/gitaly/kubernetes.md
index d93c63e7d59e8b7561c31598a80b5dacc0c1a220..b34660509601eb1eb318830115f6d8c871c36aef 100644
--- a/doc/administration/gitaly/kubernetes.md
+++ b/doc/administration/gitaly/kubernetes.md
@@ -5,10 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Gitaly on Kubernetes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
Running Gitaly on Kubernetes has availability trade-offs, so consider these trade-offs when planing a production environment and set expectations accordingly.
This document describes and provides guidance on how to minimize, and plan for existing limitations.
diff --git a/doc/administration/gitaly/monitoring.md b/doc/administration/gitaly/monitoring.md
index 30fe0c447d1b78ae0e963bb6f7429ef17a2e1417..6b630bb1609558786635fe3b4af2c5a58527b655 100644
--- a/doc/administration/gitaly/monitoring.md
+++ b/doc/administration/gitaly/monitoring.md
@@ -18,10 +18,13 @@ Metric definitions are available:
## Monitor Gitaly rate limiting (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/gitlab-org/gitaly/-/issues/5011) in GitLab 17.7
and is planned for removal in 18.0. Use [concurrency limiting](concurrency_limiting.md) instead.
+{{< /alert >}}
+
Gitaly can be configured to limit requests based on:
- Concurrency of requests.
@@ -99,7 +102,11 @@ In Prometheus, look for the following metrics:
## Monitor Gitaly adaptive concurrency limiting
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6.
+
+{{< /history >}}
You can observe specific behavior of [adaptive concurrency limiting](concurrency_limiting.md#adaptive-concurrency-limiting) using Gitaly logs and Prometheus.
@@ -185,7 +192,11 @@ gitaly_streamcache_index_entries{dir="/var/opt/gitlab/git-data/repositories/+git
## Monitor Gitaly server-side backups
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5358) in GitLab 16.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5358) in GitLab 16.7.
+
+{{< /history >}}
Monitor [server-side repository backups](configure_gitaly.md#configure-server-side-backups) with the following metrics:
diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md
index dabe3698cce8f538ccdccca3ade5601681efd913..73a1eb87e2e3a74e9ecd279332fe651a137382b9 100644
--- a/doc/administration/gitaly/praefect.md
+++ b/doc/administration/gitaly/praefect.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure Gitaly Cluster
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Configure Gitaly Cluster using either:
@@ -22,10 +25,13 @@ Configure Gitaly Cluster using either:
Smaller GitLab installations may need only [Gitaly itself](_index.md).
-NOTE:
+{{< alert type="note" >}}
+
Gitaly Cluster is not yet supported in Kubernetes, Amazon ECS, or similar container environments. For more information, see
[epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127).
+{{< /alert >}}
+
## Requirements
The minimum recommended configuration for a Gitaly Cluster requires:
@@ -35,19 +41,25 @@ The minimum recommended configuration for a Gitaly Cluster requires:
- 3 Praefect nodes
- 3 Gitaly nodes (1 primary, 2 secondary)
-NOTE:
+{{< alert type="note" >}}
+
[Disk requirements](_index.md#disk-requirements) apply to Gitaly nodes.
+{{< /alert >}}
+
You should configure an odd number of Gitaly nodes so that transactions have a tie-breaker in case one of the
Gitaly nodes fails in a mutating RPC call.
See the [design document](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/design_ha.md)
for implementation details.
-NOTE:
+{{< alert type="note" >}}
+
If not set in GitLab, feature flags are read as false from the console and Praefect uses their
default value. The default value depends on the GitLab version.
+{{< /alert >}}
+
### Network latency and connectivity
Network latency for Gitaly Cluster should ideally be measurable in single-digit milliseconds. Latency is particularly
@@ -80,11 +92,14 @@ allow the following for Gitaly Cluster to function properly:
| Gitaly | Praefect | `2305` | `3305` |
| Gitaly | Gitaly | `8075` | `9999` |
-NOTE:
+{{< alert type="note" >}}
+
Gitaly does not directly connect to Praefect. However, requests from Gitaly to the Praefect
load balancer may still be blocked unless firewalls on the Praefect nodes allow traffic from
the Gitaly nodes.
+{{< /alert >}}
+
### Praefect database storage
The requirements are relatively low because the database contains only metadata of:
@@ -165,9 +180,12 @@ with secure tokens as you complete the setup process.
We note in the instructions below where these secrets are required.
-NOTE:
+{{< alert type="note" >}}
+
Linux package installations can use `gitlab-secrets.json` for `GITLAB_SHELL_SECRET_TOKEN`.
+{{< /alert >}}
+
### Customize time server setting
By default, Gitaly and Praefect nodes use the time server at `pool.ntp.org` for time synchronization checks. You can customize this setting by adding the
@@ -178,12 +196,15 @@ following to `gitlab.rb` on each node:
### PostgreSQL
-NOTE:
+{{< alert type="note" >}}
+
Do not store the GitLab application database and the Praefect
database on the same PostgreSQL server if using [Geo](../geo/_index.md).
The replication state is internal to each instance of GitLab and should
not be replicated.
+{{< /alert >}}
+
These instructions help set up a single PostgreSQL database, which creates a single point of failure. To avoid this, you can configure your own clustered
PostgreSQL. Support for PostgreSQL replication and failover using the Linux package is proposed in [epic 7814](https://gitlab.com/groups/gitlab-org/-/epics/7814).
Clustered database support for other databases (for example, Praefect and Geo databases) is proposed in
@@ -454,12 +475,15 @@ praefect['configuration'] = {
With this configuration, Praefect uses PgBouncer for both connection types.
-NOTE:
+{{< alert type="note" >}}
+
Linux package installations handle the authentication requirements (using `auth_query`), but if you are preparing
your databases manually and configuring an external PgBouncer, you must include `praefect` user and
its password in the file used by PgBouncer. For example, `userlist.txt` if the [`auth_file`](https://www.pgbouncer.org/config.html#auth_file)
configuration option is set. For more details, consult the PgBouncer documentation.
+{{< /alert >}}
+
#### Configure Praefect to connect directly to PostgreSQL
As an alternative to configuring PgBouncer with `session` pool mode, Praefect can be configured to use different
@@ -501,10 +525,13 @@ If there are multiple Praefect nodes:
To complete this section you need a [configured PostgreSQL server](#postgresql), including:
-WARNING:
+{{< alert type="warning" >}}
+
Praefect should be run on a dedicated node. Do not run Praefect on the
application server, or a Gitaly node.
+{{< /alert >}}
+
On the **Praefect** node:
1. Disable all other services by editing `/etc/gitlab/gitlab.rb`:
@@ -621,12 +648,15 @@ Updates to example must be made at:
so we use `default` here as well. This cluster has three Gitaly nodes `gitaly-1`,
`gitaly-2`, and `gitaly-3`, which are intended to be replicas of each other.
- WARNING:
+ {{< alert type="warning" >}}
+
If you have data on an already existing storage called
`default`, you should configure the virtual storage with another name and
[migrate the data to the Gitaly Cluster storage](_index.md#migrate-to-gitaly-cluster)
afterwards.
+ {{< /alert >}}
+
Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which is used by
Praefect when communicating with Gitaly nodes in the cluster. This token is
distinct from the `PRAEFECT_EXTERNAL_TOKEN`.
@@ -636,11 +666,14 @@ Updates to example must be made at:
More Gitaly nodes can be added to the cluster to increase the number of
replicas. More clusters can also be added for very large GitLab instances.
- NOTE:
- When adding additional Gitaly nodes to a virtual storage, all storage names
+ {{< alert type="note" >}}
+
+When adding additional Gitaly nodes to a virtual storage, all storage names
in that virtual storage must be unique. Additionally, all Gitaly node
addresses referenced in the Praefect configuration must be unique.
+ {{< /alert >}}
+
```ruby
# Name of storage hash must match storage name in gitlab_rails['repositories_storages'] on GitLab
# server ('default') and in gitaly['configuration'][:storage][INDEX][:name] on Gitaly nodes ('gitaly-1')
@@ -870,7 +903,11 @@ For self-compiled installations:
#### Service discovery
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8971) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8971) in GitLab 15.10.
+
+{{< /history >}}
Prerequisites:
@@ -937,9 +974,9 @@ You can also appoint an authoritative name server by setting it in this format:
- `dns://[authority_host]:[authority_port]/[host]:[port]`
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Add the IP address for each Praefect node to the DNS service discovery address.
1. On the Praefect clients (except Gitaly servers), edit `gitlab_rails['repositories_storages']` in
@@ -957,7 +994,9 @@ You can also appoint an authoritative name server by setting it in this format:
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Install a DNS service discovery service. Register all Praefect nodes with the service.
1. On the Praefect clients (except Gitaly servers), edit `storages` in
@@ -973,7 +1012,9 @@ You can also appoint an authoritative name server by setting it in this format:
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
##### Configure service discovery with Consul
@@ -1026,9 +1067,12 @@ Prerequisites:
### Gitaly
-NOTE:
+{{< alert type="note" >}}
+
Complete these steps for **each** Gitaly node.
+{{< /alert >}}
+
To complete this section you need:
- [Configured Praefect node](#praefect)
@@ -1195,10 +1239,13 @@ internal traffic from the GitLab application to the Praefect nodes. The
specifics on which load balancer to use or the exact configuration is beyond the
scope of the GitLab documentation.
-NOTE:
+{{< alert type="note" >}}
+
The load balancer must be configured to accept traffic from the Gitaly nodes in
addition to the GitLab nodes.
+{{< /alert >}}
+
We hope that if you're managing fault-tolerant systems like GitLab, you have a load balancer
of choice already. Some examples include [HAProxy](https://www.haproxy.org/)
(open-source), [Google Internal Load Balancer](https://cloud.google.com/load-balancing/docs/internal/),
@@ -1307,11 +1354,14 @@ Particular attention should be shown to:
1. Disable the default Gitaly service running on the GitLab host. It isn't needed
because GitLab connects to the configured cluster.
- WARNING:
+ {{< alert type="warning" >}}
+
If you have existing data stored on the default Gitaly storage,
you should [migrate the data to your Gitaly Cluster storage](_index.md#migrate-to-gitaly-cluster)
first.
+ {{< /alert >}}
+
```ruby
gitaly['enable'] = false
```
@@ -1490,9 +1540,12 @@ cluster.
Praefect supports configuring a replication factor on a per-repository basis, by assigning
specific storage nodes to host a repository.
-WARNING:
+{{< alert type="warning" >}}
+
Configurable replication factors requires [repository-specific primary nodes](#repository-specific-primary-nodes).
+{{< /alert >}}
+
Praefect does not store the actual replication factor, but assigns enough storages to host the repository
so the desired replication factor is met. If a storage node is later removed from the virtual storage,
the replication factor of repositories assigned to the storage is decreased accordingly.
@@ -1565,7 +1618,11 @@ For a replication factor:
## Repository verification
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4080) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4080) in GitLab 15.0.
+
+{{< /history >}}
Praefect stores metadata about the repositories in a database. If the repositories are modified on disk
without going through Praefect, the metadata can become inaccurate. For example if a Gitaly node is
@@ -1637,14 +1694,21 @@ praefect['configuration'] = {
#### Enable deletions
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4080) and disabled by default in GitLab 15.0
-> - [Default enabled](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5321) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4080) and disabled by default in GitLab 15.0
+- [Default enabled](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5321) in GitLab 15.9.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
Deletions were disabled by default prior to GitLab 15.9 due to a race condition with repository renames
that can cause incorrect deletions, which is especially prominent in Geo instances as Geo performs more renames
than instances without Geo. In GitLab 15.0 to 15.5, you should enable deletions only if the [`gitaly_praefect_generated_replica_paths` feature flag](_index.md#praefect-generated-replica-paths) is enabled. The feature flag was removed in GitLab 15.6 making deletions always safe to enable.
+{{< /alert >}}
+
By default, the worker deletes invalid metadata records. It also logs the deleted records and outputs Prometheus
metrics.
diff --git a/doc/administration/gitaly/recovery.md b/doc/administration/gitaly/recovery.md
index 62cec382beb97ecf406efcd41340d84cd89c0c1c..f6b6df97729100979d839c7fca7da9c6588c846f 100644
--- a/doc/administration/gitaly/recovery.md
+++ b/doc/administration/gitaly/recovery.md
@@ -129,9 +129,12 @@ The following parameters are available:
that specifies whether to include in the output repositories that are available but have
some assigned copies that are not available.
-NOTE:
+{{< alert type="note" >}}
+
`dataloss` is still in [beta](../../policy/development_stages_support.md#beta) and the output format is subject to change.
+{{< /alert >}}
+
To check for repositories with outdated primaries or for unavailable repositories, run:
```shell
@@ -232,10 +235,13 @@ To check a project's repository checksums across on all Gitaly nodes, run the
### Accept data loss
-WARNING:
+{{< alert type="warning" >}}
+
`accept-dataloss` causes permanent data loss by overwriting other versions of the repository. Data
[recovery efforts](#data-recovery) must be performed before using it.
+{{< /alert >}}
+
If it is not possible to bring one of the up to date replicas back online, you may have to accept data
loss. When accepting data loss, Praefect marks the chosen replica of the repository as the latest version
and replicates it to the other assigned Gitaly nodes. This process overwrites any other version of the
@@ -248,10 +254,13 @@ sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefec
### Enable writes or accept data loss
-WARNING:
+{{< alert type="warning" >}}
+
`accept-dataloss` causes permanent data loss by overwriting other versions of the repository.
Data [recovery efforts](#data-recovery) must be performed before using it.
+{{< /alert >}}
+
Praefect provides the following subcommands to re-enable writes or accept data loss. If it is not possible to bring one
of the up-to-date nodes back online, you might have to accept data loss:
@@ -315,7 +324,11 @@ praefect['configuration'] = {
### Manually remove repositories
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4715) in GitLab 15.3, support for removing repositories from the Praefect tracking database.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4715) in GitLab 15.3, support for removing repositories from the Praefect tracking database.
+
+{{< /history >}}
The `remove-repository` Praefect sub-command removes a repository from a Gitaly Cluster, and all state associated with a given repository including:
@@ -379,7 +392,11 @@ Common maintenance tasks on the Praefect tracking database are documented in thi
### List untracked repositories
-> - `older-than` option added in GitLab 15.0.
+{{< history >}}
+
+- `older-than` option added in GitLab 15.0.
+
+{{< /history >}}
The `list-untracked-repositories` Praefect sub-command lists repositories of the Gitaly Cluster that both:
@@ -415,11 +432,14 @@ sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefec
### Manually add a single repository to the tracking database
-WARNING:
+{{< alert type="warning" >}}
+
Because of a [known issue](https://gitlab.com/gitlab-org/gitaly/-/issues/5402), you can't add repositories to the
Praefect tracking database with Praefect-generated replica paths (`@cluster`). These repositories are not associated with the repository path used by GitLab and are
inaccessible.
+{{< /alert >}}
+
The `track-repository` Praefect sub-command adds repositories on disk to the Praefect tracking database to be tracked.
```shell
@@ -471,13 +491,20 @@ This command fails if:
### Manually add many repositories to the tracking database
-> - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/6319) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/6319) in GitLab 15.4.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
Because of a [known issue](https://gitlab.com/gitlab-org/gitaly/-/issues/5402), you can't add repositories to the
Praefect tracking database with Praefect-generated replica paths (`@cluster`). These repositories are not associated with the repository path used by GitLab and are
inaccessible.
+{{< /alert >}}
+
Migrations using the API automatically add repositories to the Praefect tracking database.
If you are instead manually copying repositories over from existing infrastructure, you can use the `track-repositories`
@@ -516,7 +543,11 @@ If any entry fails these checks, the command aborts prior to attempting to track
### List virtual storage details
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4609) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4609) in GitLab 15.1.
+
+{{< /history >}}
The `list-storages` Praefect sub-command lists virtual storages and their associated storage nodes. If a virtual storage is:
diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md
index fb4f2b39eadd40ac654d617f52c27d6cb28abbe8..5db73a46b2348fe841b2d4195e23b9efd5bb0e52 100644
--- a/doc/administration/gitaly/reference.md
+++ b/doc/administration/gitaly/reference.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Example configuration files
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Gitaly and Gitaly Cluster are configured by using configuration files. The default location of the configuration files
depends on the type of installation you have:
diff --git a/doc/administration/gitaly/tls_support.md b/doc/administration/gitaly/tls_support.md
index 3575e7b6527576e324773e136362584ea7e75766..0c71e828a283c776227cdd037b35b482b357e408 100644
--- a/doc/administration/gitaly/tls_support.md
+++ b/doc/administration/gitaly/tls_support.md
@@ -38,9 +38,9 @@ If you use a load balancer, it must be able to negotiate HTTP/2 using the ALPN T
The process for configuring TLS support depends on your installation type.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Create certificates for Gitaly servers.
1. On the Gitaly clients, copy the certificates (or their certificate authority) into
@@ -109,7 +109,9 @@ The process for configuring TLS support depends on your installation type.
1. Saving the file.
1. [Reconfiguring GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Create certificates for Gitaly servers.
1. On the Gitaly clients, copy the certificates into the system trusted certificates:
@@ -136,10 +138,13 @@ The process for configuring TLS support depends on your installation type.
path: /some/local/path
```
- NOTE:
- `/some/local/path` should be set to a local folder that exists, however no data is stored
- in this folder. This requirement is scheduled to be removed when
- [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved.
+ {{< alert type="note" >}}
+
+ `/some/local/path` should be set to a local folder that exists, however no data is stored
+ in this folder. This requirement is scheduled to be removed when
+ [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved.
+
+ {{< /alert >}}
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations).
1. On the Gitaly servers, create or edit `/etc/default/gitlab` and add:
@@ -188,15 +193,17 @@ The process for configuring TLS support depends on your installation type.
1. Saving the file.
1. [Restarting GitLab](../restart_gitlab.md#self-compiled-installations).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Update the certificates
To update the Gitaly certificates after initial configuration:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, but no configuration changes have been made to
`/etc/gitlab/gitlab.rb`, then reconfiguring GitLab doesn’t affect Gitaly. Instead, you must restart Gitaly manually for the certificates to be loaded
@@ -215,7 +222,9 @@ If you change or update the certificates in `/etc/gitlab/trusted-certs` without
sudo gitlab-ctl restart gitaly
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, you must
[restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process.
@@ -225,7 +234,9 @@ If you change or update the certificates in `/usr/local/share/ca-certificates`,
1. Run `sudo update-ca-certificates` to update the system's trusted store.
1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Observe type of Gitaly connections
diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md
index 1d6949b915c4a25cb3accfd661d841cd36856659..041cdb20dc67ca0d29dc767207bf94f83912d0f9 100644
--- a/doc/administration/gitaly/troubleshooting.md
+++ b/doc/administration/gitaly/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Gitaly
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Refer to the information below when troubleshooting Gitaly. For information on troubleshooting Gitaly Cluster (Praefect),
see [Troubleshooting Gitaly Cluster](troubleshooting_gitaly_cluster.md).
@@ -516,12 +519,19 @@ go tool trace heap.bin
### Profile Git operations
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5700) in GitLab 16.9 [with a flag](../feature_flags.md) named `log_git_traces`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5700) in GitLab 16.9 [with a flag](../feature_flags.md) named `log_git_traces`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../feature_flags.md)
named `log_git_traces`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. On GitLab Dedicated, this feature is not available.
+{{< /alert >}}
+
You can profile Git operations that Gitaly performs by sending additional information about Git operations to Gitaly logs. With this information, users have more insight
for performance optimization, debugging, and general telemetry collection. For more information, see the [Git Trace2 API reference](https://git-scm.com/docs/api-trace2).
@@ -602,16 +612,23 @@ The new rule takes effect after the daemon restarts.
## Update repositories after removing a storage with a duplicate path
-> - Rake task `gitlab:gitaly:update_removed_storage_projects` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153008) in GitLab 17.1.
+{{< history >}}
+
+- Rake task `gitlab:gitaly:update_removed_storage_projects` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153008) in GitLab 17.1.
+
+{{< /history >}}
In GitLab 17.0, support for configuring storages with duplicate paths [was removed](https://gitlab.com/gitlab-org/gitaly/-/issues/5598). This can mean that you
must remove duplicate storage configuration from `gitaly` configuration.
-WARNING:
+{{< alert type="warning" >}}
+
Only use this Rake task when the old and new storages share the same disk path on the same Gitaly server. Using the this Rake task in any other situation
causes the repository to become unavailable. Use the [project repository storage moves API](../../api/project_repository_storage_moves.md) to transfer
projects between storages in all other situations.
+{{< /alert >}}
+
When removing from the Gitaly configuration a storage that used the same path as another storage,
the projects associated with the old storage must be reassigned to the new one.
@@ -635,18 +652,22 @@ gitaly['configuration'] = {
If you were removing `duplicate-path` from the configuration, you would run the following
Rake task to associate any projects assigned to it to `default` instead:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package installations
+{{< tab title="Linux package installations" >}}
```shell
sudo gitlab-rake "gitlab:gitaly:update_removed_storage_projects[duplicate-path, default]"
```
-:::TabTitle Self-compiled installations
+{{< /tab >}}
+
+{{< tab title="Self-compiled installations" >}}
```shell
sudo -u git -H bundle exec rake "gitlab:gitaly:update_removed_storage_projects[duplicate-path, default]" RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/administration/gitaly/troubleshooting_gitaly_cluster.md b/doc/administration/gitaly/troubleshooting_gitaly_cluster.md
index 60e79126f9f4d52adb4e4773112ac8c83b9de738..8e5aaef39c8d7aff954d1077768b51c2a0d44bd7 100644
--- a/doc/administration/gitaly/troubleshooting_gitaly_cluster.md
+++ b/doc/administration/gitaly/troubleshooting_gitaly_cluster.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Gitaly Cluster
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Refer to the information below when troubleshooting Gitaly Cluster (Praefect). For information on troubleshooting Gitaly,
see [Troubleshooting Gitaly](troubleshooting.md).
diff --git a/doc/administration/gitlab_duo_self_hosted/_index.md b/doc/administration/gitlab_duo_self_hosted/_index.md
index 4f91e580acdf4e23b3aa7982268414e21fda746b..ccaaad85c1d5c67401771f830c1b823cfc0e562f 100644
--- a/doc/administration/gitlab_duo_self_hosted/_index.md
+++ b/doc/administration/gitlab_duo_self_hosted/_index.md
@@ -1,20 +1,27 @@
---
stage: AI-Powered
group: Custom Models
-description: Get started with GitLab Duo Self-Hosted.
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
+description: Get started with GitLab Duo Self-Hosted.
title: GitLab Duo Self-Hosted
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Feature flag `ai_custom_model` removed in GitLab 17.8
-> - Generally available in GitLab 17.9
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Feature flag `ai_custom_model` removed in GitLab 17.8
+- Generally available in GitLab 17.9
+
+{{< /history >}}
To maintain full control over your data privacy, security, and the deployment of large language models (LLMs) in your own infrastructure, use GitLab Duo Self-Hosted.
@@ -68,9 +75,12 @@ Before setting up the GitLab Duo Self-Hosted infrastructure, you must have:
The configuration for GitLab Duo Self-Hosted is different to the default configuration
that uses GitLab external AI vendors.
-NOTE:
+{{< alert type="note" >}}
+
Both of the following configuration types are for GitLab Self-Managed instances.
+{{< /alert >}}
+
### Self-hosted AI gateway and LLMs
In a fully self-hosted configuration, you deploy your own AI gateway and LLMs in your infrastructure, without relying on external public services. This gives you full control over your data and security.
diff --git a/doc/administration/gitlab_duo_self_hosted/configuration_types.md b/doc/administration/gitlab_duo_self_hosted/configuration_types.md
index 7732526557b32614161ae4d2dc624f49c26357a9..96d3668e2e321f4b48fe88cf1995c2748b0a86e6 100644
--- a/doc/administration/gitlab_duo_self_hosted/configuration_types.md
+++ b/doc/administration/gitlab_duo_self_hosted/configuration_types.md
@@ -1,20 +1,27 @@
---
stage: AI-Powered
group: Custom Models
-description: Get started with GitLab Duo Self-Hosted.
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
+description: Get started with GitLab Duo Self-Hosted.
title: GitLab Duo Self-Hosted configuration and authentication
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Feature flag `ai_custom_model` removed in GitLab 17.8
+- Generally available in GitLab 17.9
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Feature flag `ai_custom_model` removed in GitLab 17.8
-> - Generally available in GitLab 17.9
+{{< /history >}}
There are two configuration options for self-managed customers:
diff --git a/doc/administration/gitlab_duo_self_hosted/configure_duo_features.md b/doc/administration/gitlab_duo_self_hosted/configure_duo_features.md
index d124dc89afde04d6b20be4f9c624a0e26e0b841f..b6c5ff21b73c845c5872264fbd73c39ca554a32f 100644
--- a/doc/administration/gitlab_duo_self_hosted/configure_duo_features.md
+++ b/doc/administration/gitlab_duo_self_hosted/configure_duo_features.md
@@ -1,21 +1,28 @@
---
stage: AI-Powered
group: Custom Models
-description: Configure your GitLab instance to use GitLab Duo Self-Hosted.
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
+description: Configure your GitLab instance to use GitLab Duo Self-Hosted.
title: Configure GitLab to access GitLab Duo Self-Hosted
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Feature flag `ai_custom_model` removed in GitLab 17.8
-> - Ability to set AI gateway URL using UI [added](https://gitlab.com/gitlab-org/gitlab/-/issues/473143) in GitLab 17.9.
-> - Generally available in GitLab 17.9
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Feature flag `ai_custom_model` removed in GitLab 17.8
+- Ability to set AI gateway URL using UI [added](https://gitlab.com/gitlab-org/gitlab/-/issues/473143) in GitLab 17.9.
+- Generally available in GitLab 17.9
+
+{{< /history >}}
Prerequisites:
@@ -52,7 +59,7 @@ To configure a self-hosted model:
subscription after purchase:
1. On the left sidebar, select **Subscription**.
1. In **Subscription details**, to the right of **Last sync**, select
- synchronize subscription (**{retry}**).
+ synchronize subscription ({{< icon name="retry" >}}).
1. Select **Add self-hosted model**.
1. Complete the fields:
- **Deployment name**: Enter a name to uniquely identify the model deployment, for example, `Mixtral-8x7B-it-v0.1 on GCP`.
@@ -90,9 +97,12 @@ To enable self-hosted [beta](../../policy/development_stages_support.md#beta) mo
1. Under **Self-hosted AI models**, select **Use beta self-hosted models features**.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
Turning on beta self-hosted models features also accepts the [GitLab Testing Agreement](https://handbook.gitlab.com/handbook/legal/testing-agreement/).
+{{< /alert >}}
+
For more information, see the [list of available beta models](supported_models_and_hardware_requirements.md) under evaluation.
## Configure GitLab Duo features to use self-hosted models
@@ -111,7 +121,7 @@ Prerequisites:
subscription after purchase:
1. On the left sidebar, select **Subscription**.
1. In **Subscription details**, to the right of **Last sync**, select
- synchronize subscription (**{retry}**).
+ synchronize subscription ({{< icon name="retry" >}}).
1. Select the **AI-powered features** tab.
### Configure the feature to use a self-hosted model
diff --git a/doc/administration/gitlab_duo_self_hosted/logging.md b/doc/administration/gitlab_duo_self_hosted/logging.md
index b7852ab070ea613155d94839399d4f5df5c09874..68219ff4a094560e19c6c26b7a56b4bced3d76c0 100644
--- a/doc/administration/gitlab_duo_self_hosted/logging.md
+++ b/doc/administration/gitlab_duo_self_hosted/logging.md
@@ -1,20 +1,27 @@
---
stage: AI-Powered
group: Custom Models
-description: Enable logging for self-hosted models.
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
+description: Enable logging for self-hosted models.
title: Enable logging for self-hosted models
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Feature flag `ai_custom_model` removed in GitLab 17.8
+- Generally available in GitLab 17.9
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Feature flag `ai_custom_model` removed in GitLab 17.8
-> - Generally available in GitLab 17.9
+{{< /history >}}
Prerequisites:
diff --git a/doc/administration/gitlab_duo_self_hosted/supported_llm_serving_platforms.md b/doc/administration/gitlab_duo_self_hosted/supported_llm_serving_platforms.md
index 6156d300292c23ec39a9dcb471180238ccc77a04..490ba788e69ee33ec48fb0f18899335736fb2f2f 100644
--- a/doc/administration/gitlab_duo_self_hosted/supported_llm_serving_platforms.md
+++ b/doc/administration/gitlab_duo_self_hosted/supported_llm_serving_platforms.md
@@ -1,20 +1,27 @@
---
stage: AI-Powered
group: Custom Models
-description: Supported LLM Serving Platforms.
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
+description: Supported LLM Serving Platforms.
title: GitLab Duo Self-Hosted supported platforms
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Feature flag `ai_custom_model` removed in GitLab 17.8
+- Generally available in GitLab 17.9
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Feature flag `ai_custom_model` removed in GitLab 17.8
-> - Generally available in GitLab 17.9
+{{< /history >}}
There are multiple platforms available to host your self-hosted Large Language Models (LLMs). Each platform has unique features and benefits that can cater to different needs. The following documentation summarises the currently supported options:
diff --git a/doc/administration/gitlab_duo_self_hosted/supported_models_and_hardware_requirements.md b/doc/administration/gitlab_duo_self_hosted/supported_models_and_hardware_requirements.md
index 673f3380ccd09ce49ca0d2514abfb8cee989e35e..c9ade39da1deed8286d5a0e97b6d364c16467441 100644
--- a/doc/administration/gitlab_duo_self_hosted/supported_models_and_hardware_requirements.md
+++ b/doc/administration/gitlab_duo_self_hosted/supported_models_and_hardware_requirements.md
@@ -1,20 +1,27 @@
---
stage: AI-Powered
group: Custom Models
-description: Supported Models and Hardware Requirements.
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
+description: Supported Models and Hardware Requirements.
title: Supported GitLab Duo Self-Hosted models and hardware requirements
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Feature flag `ai_custom_model` removed in GitLab 17.8
+- Generally available in GitLab 17.9
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Feature flag `ai_custom_model` removed in GitLab 17.8
-> - Generally available in GitLab 17.9
+{{< /history >}}
The following table shows the supported models along with their specific features and hardware requirements to help you select the model that best fits your infrastructure needs for optimal performance.
@@ -30,14 +37,14 @@ The following GitLab-supported large language models (LLMs) are generally availa
| Model Family | Model | Supported Platforms | Code completion | Code generation | GitLab Duo Chat |
|-------------|-------|---------------------|-----------------|-----------------|-----------------|
-| Mistral Codestral | [Codestral 22B v0.1](https://huggingface.co/mistralai/Codestral-22B-v0.1) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible | N/A |
-| Mistral | [Mistral 7B-it v0.3](https://huggingface.co/mistralai/Mistral-7B-Instruct-v0.3) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible | **{dash-circle}** Not compatible |
-| Mistral | [Mixtral 8x7B-it v0.1](https://huggingface.co/mistralai/Mixtral-8x7B-Instruct-v0.1) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments), [AWS Bedrock](https://aws.amazon.com/bedrock/mistral/) | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible | **{check-circle-dashed}** Limited compatibility |
-| Mistral | [Mixtral 8x22B-it v0.1](https://huggingface.co/mistralai/Mixtral-8x22B-Instruct-v0.1) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible | **{check-circle-dashed}** Limited compatibility |
-| Claude 3 | [Claude 3.5 Sonnet](https://www.anthropic.com/news/claude-3-5-sonnet) | [AWS Bedrock](https://aws.amazon.com/bedrock/claude/) | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible |
-| GPT | [GPT-4 Turbo](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4) | [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview) | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible | **{check-circle-dashed}** Limited compatibility |
-| GPT | [GPT-4o](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo) | [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview) | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible |
-| GPT | [GPT-4o-mini](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo) | [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview) | **{check-circle-filled}** Fully compatible | **{check-circle-filled}** Fully compatible | **{check-circle-dashed}** Limited compatibility |
+| Mistral Codestral | [Codestral 22B v0.1](https://huggingface.co/mistralai/Codestral-22B-v0.1) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible | N/A |
+| Mistral | [Mistral 7B-it v0.3](https://huggingface.co/mistralai/Mistral-7B-Instruct-v0.3) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="dash-circle" >}} Not compatible |
+| Mistral | [Mixtral 8x7B-it v0.1](https://huggingface.co/mistralai/Mixtral-8x7B-Instruct-v0.1) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments), [AWS Bedrock](https://aws.amazon.com/bedrock/mistral/) | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-dashed" >}} Limited compatibility |
+| Mistral | [Mixtral 8x22B-it v0.1](https://huggingface.co/mistralai/Mixtral-8x22B-Instruct-v0.1) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-dashed" >}} Limited compatibility |
+| Claude 3 | [Claude 3.5 Sonnet](https://www.anthropic.com/news/claude-3-5-sonnet) | [AWS Bedrock](https://aws.amazon.com/bedrock/claude/) | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible |
+| GPT | [GPT-4 Turbo](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4) | [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview) | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-dashed" >}} Limited compatibility |
+| GPT | [GPT-4o](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo) | [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview) | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible |
+| GPT | [GPT-4o-mini](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo) | [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview) | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-filled" >}} Fully compatible | {{< icon name="check-circle-dashed" >}} Limited compatibility |
### Experimental and beta models
@@ -45,13 +52,13 @@ The following models are configurable for the functionalities marked below, but
| Model family | Model | Supported platforms | Status | Code completion | Code generation | GitLab Duo Chat |
|--------------- |-------|---------------------|--------|-----------------|-----------------|-----------------|
-| CodeGemma | [CodeGemma 2b](https://huggingface.co/google/codegemma-2b) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| CodeGemma | [CodeGemma 7b-it](https://huggingface.co/google/codegemma-7b-it) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| CodeGemma | [CodeGemma 7b-code](https://huggingface.co/google/codegemma-7b) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Code Llama | [Code-Llama 13b](https://huggingface.co/meta-llama/CodeLlama-13b-Instruct-hf) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| DeepSeek Coder | [DeepSeek Coder 33b Instruct](https://huggingface.co/deepseek-ai/deepseek-coder-33b-instruct) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| DeepSeek Coder | [DeepSeek Coder 33b Base](https://huggingface.co/deepseek-ai/deepseek-coder-33b-base) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Mistral | [Mistral 7B-it v0.2](https://huggingface.co/mistralai/Mistral-7B-Instruct-v0.2) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) <br> [AWS Bedrock](https://aws.amazon.com/bedrock/mistral/) | Beta | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
+| CodeGemma | [CodeGemma 2b](https://huggingface.co/google/codegemma-2b) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| CodeGemma | [CodeGemma 7b-it](https://huggingface.co/google/codegemma-7b-it) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| CodeGemma | [CodeGemma 7b-code](https://huggingface.co/google/codegemma-7b) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Code Llama | [Code-Llama 13b](https://huggingface.co/meta-llama/CodeLlama-13b-Instruct-hf) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| DeepSeek Coder | [DeepSeek Coder 33b Instruct](https://huggingface.co/deepseek-ai/deepseek-coder-33b-instruct) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| DeepSeek Coder | [DeepSeek Coder 33b Base](https://huggingface.co/deepseek-ai/deepseek-coder-33b-base) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) | Beta | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Mistral | [Mistral 7B-it v0.2](https://huggingface.co/mistralai/Mistral-7B-Instruct-v0.2) | [vLLM](supported_llm_serving_platforms.md#for-self-hosted-model-deployments) <br> [AWS Bedrock](https://aws.amazon.com/bedrock/mistral/) | Beta | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
<!-- vale gitlab_base.Spelling = YES -->
diff --git a/doc/administration/gitlab_duo_self_hosted/troubleshooting.md b/doc/administration/gitlab_duo_self_hosted/troubleshooting.md
index 2f471c48b5f5f037100b9ad99a1b1bc287570f32..eb53e5c38a0573c1e204f9149be12b3a8eba040d 100644
--- a/doc/administration/gitlab_duo_self_hosted/troubleshooting.md
+++ b/doc/administration/gitlab_duo_self_hosted/troubleshooting.md
@@ -1,20 +1,27 @@
---
stage: AI-Powered
group: Custom Models
-description: Troubleshooting tips for deploying GitLab Duo Self-Hosted
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
+description: Troubleshooting tips for deploying GitLab Duo Self-Hosted
title: Troubleshooting GitLab Duo Self-Hosted
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Feature flag `ai_custom_model` removed in GitLab 17.8
-> - Generally available in GitLab 17.9
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Feature flag `ai_custom_model` removed in GitLab 17.8
+- Generally available in GitLab 17.9
+
+{{< /history >}}
When working with GitLab Duo Self-Hosted, you might encounter issues.
@@ -96,9 +103,12 @@ We provide two debugging scripts to help administrators verify their self-hosted
After troubleshooting is complete, stop and restart the AI gateway container **without** `AIGW_AUTH__BYPASS_EXTERNAL=true`.
-WARNING:
+{{< alert type="warning" >}}
+
You must not bypass authentication in production.
+{{< /alert >}}
+
Verify the output of the commands, and fix accordingly.
If both commands are successful, but GitLab Duo Code Suggestions is still not working,
diff --git a/doc/administration/guest_users.md b/doc/administration/guest_users.md
index 58bc8fa48357493d18fc2d0b901843ca661d428e..9a34d8d0429bd9d2ca6b94d20dfc5fe1c2e2c5e8 100644
--- a/doc/administration/guest_users.md
+++ b/doc/administration/guest_users.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Guest users
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Users assigned the Guest role have limited access and capabilities compared to other user roles. Their permissions are restricted and are designed to provide basic visibility and interaction without compromising sensitive project data. For more information, see [Roles and permissions](../user/permissions.md).
@@ -15,8 +18,11 @@ In GitLab Free and Premium, Guest users count towards the license seat usage.
## Unlimited seat usage
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
In GitLab Ultimate, users with the Guest role do not count towards the license seat usage. You can add Guest users to your GitLab instance without impacting your billable seats.
diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md
index c9cd43915b3b33d4f565ac5fd0cf5bf898d9acb8..fd1a1686de0754ce168ab4c04ccc3efee285f363 100644
--- a/doc/administration/housekeeping.md
+++ b/doc/administration/housekeeping.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Housekeeping
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab supports and automates housekeeping tasks in Git repositories to ensure
that they can be served as efficiently as possible. Housekeeping tasks include:
@@ -18,11 +21,14 @@ that they can be served as efficiently as possible. Housekeeping tasks include:
- Maintaining data structures that improve performance.
- Updating object pools to improve object deduplication across forks.
-WARNING:
+{{< alert type="warning" >}}
+
Do not manually execute Git commands to perform housekeeping in Git
repositories that are controlled by GitLab. Doing so may lead to corrupt
repositories and data loss.
+{{< /alert >}}
+
## Housekeeping strategy
Gitaly can perform housekeeping tasks in a Git repository in two ways:
@@ -48,9 +54,13 @@ be slow.
### Heuristical housekeeping
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2634) in GitLab 14.9 for the [manual trigger](#manual-trigger) and the push-based trigger [with a flag](feature_flags.md) named `optimized_housekeeping`. Enabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353607) in GitLab 14.10.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107661) in GitLab 15.8. Feature flag `optimized_housekeeping` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2634) in GitLab 14.9 for the [manual trigger](#manual-trigger) and the push-based trigger [with a flag](feature_flags.md) named `optimized_housekeeping`. Enabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353607) in GitLab 14.10.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107661) in GitLab 15.8. Feature flag `optimized_housekeeping` removed.
+
+{{< /history >}}
The heuristical (or "opportunistic") housekeeping strategy analyzes the
repository's state and executes housekeeping tasks only when it finds one or
@@ -130,7 +140,8 @@ information. Triggering housekeeping prunes unreachable objects with a grace per
two weeks. When you manually trigger the pruning of unreachable objects, the grace period
is reduced to 30 minutes.
-WARNING:
+{{< alert type="warning" >}}
+
If a concurrent process (like `git push`) has created an object but hasn't created
a reference to the object yet, your repository can become corrupted if a reference
to the object is added after the object is deleted. The grace period exists to
@@ -140,6 +151,8 @@ then the risk that comes with pruning unreachable objects is much higher than in
environment where the project can be accessed only from inside the company with a performant
connection. Consider the project usage profile when using this option and select a quiet period.
+{{< /alert >}}
+
To trigger a manual prune of unreachable objects:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -182,9 +195,9 @@ the repository list to process.
The following snippet enables daily background repository maintenance starting at
23:00 for 1 hour for the `default` storage:
-::Tabs
+{{< tabs >}}
-:::TabTitle Self-compiled (source)
+{{< tab title="Self-compiled (source)" >}}
```toml
[daily_maintenance]
@@ -202,7 +215,9 @@ maintenance:
disabled = true
```
-:::TabTitle Linux package (Omnibus)
+{{< /tab >}}
+
+{{< tab title="Linux package (Omnibus)" >}}
```ruby
gitaly['configuration'] = {
@@ -227,7 +242,9 @@ gitaly['configuration'] = {
}
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
When the scheduled housekeeping is executed, you can see the following entries in
your [Gitaly log](logs/_index.md#gitaly-logs):
diff --git a/doc/administration/inactive_project_deletion.md b/doc/administration/inactive_project_deletion.md
index 7ba692edd18057db502c949d1972d09fe3fc2e60..80b15cc74fbace07c08a34b9fb7622369f12f6fe 100644
--- a/doc/administration/inactive_project_deletion.md
+++ b/doc/administration/inactive_project_deletion.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Inactive project deletion
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0 [with a flag](feature_flags.md) named `inactive_projects_deletion`. Disabled by default.
-> - [Feature flag `inactive_projects_deletion`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96803) removed in GitLab 15.4.
-> - Configuration through GitLab UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85575) in GitLab 15.1.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0 [with a flag](feature_flags.md) named `inactive_projects_deletion`. Disabled by default.
+- [Feature flag `inactive_projects_deletion`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96803) removed in GitLab 15.4.
+- Configuration through GitLab UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85575) in GitLab 15.1.
+
+{{< /history >}}
Administrators of large GitLab instances can find that over time, projects become inactive and are no longer used.
These projects take up unnecessary disk space.
diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md
index d48362819505f4b7c4a19650fde2e5fb6724caf2..96e2ae00805cd47a93abaa80011dcbfb16730ab0 100644
--- a/doc/administration/incoming_email.md
+++ b/doc/administration/incoming_email.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Incoming email
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab has several features based on receiving incoming email messages:
@@ -46,13 +49,16 @@ Gmail, Google Apps, Yahoo! Mail, Outlook.com, and iCloud, as well as the
Microsoft Exchange Server [does not support sub-addressing](#microsoft-exchange-server),
and Microsoft Office 365 [does not support sub-addressing by default](#microsoft-office-365).
-NOTE:
+{{< alert type="note" >}}
+
If your provider or server supports email sub-addressing, we recommend using it.
A dedicated email address only supports Reply by Email functionality.
A catch-all mailbox supports the same features as sub-addressing,
but sub-addressing is still preferred because only one email address is used,
leaving a catch-all available for other purposes beyond GitLab.
+{{< /alert >}}
+
### Catch-all mailbox
A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain
@@ -71,10 +77,14 @@ this method only supports replies, and not the other features of incoming email.
## Accepted headers
-> - Accepting `Cc` headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348572) in GitLab 16.5.
-> - Accepting `X-Original-To` headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149874) in GitLab 17.0.
-> - Accepting `X-Forwarded-To` headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/168716) in GitLab 17.6.
-> - Accepting `X-Delivered-To` headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170221) in GitLab 17.6.
+{{< history >}}
+
+- Accepting `Cc` headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348572) in GitLab 16.5.
+- Accepting `X-Original-To` headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149874) in GitLab 17.0.
+- Accepting `X-Forwarded-To` headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/168716) in GitLab 17.6.
+- Accepting `X-Delivered-To` headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170221) in GitLab 17.6.
+
+{{< /history >}}
Email is processed correctly when a configured email address is present in one of the following headers
(sorted in the order they are checked):
@@ -128,9 +138,12 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the
### Security concerns
-WARNING:
+{{< alert type="warning" >}}
+
Be careful when choosing the domain used for receiving incoming email.
+{{< /alert >}}
+
For example, suppose your top-level company domain is `hooli.com`.
All employees in your company have an email address at that domain through Google
Workspace, and your company's private Slack instance requires a valid `@hooli.com`
@@ -155,7 +168,8 @@ Alternatively, use a dedicated domain for GitLab email communications such as
See GitLab issue [#30366](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30366)
for a real-world example of this exploit.
-WARNING:
+{{< alert type="warning" >}}
+
Use a mail server that has been configured to reduce
spam.
A Postfix mail server that is running on a default configuration, for example,
@@ -165,8 +179,12 @@ If the sender's address is spoofed, the reject notice is delivered to the spoofe
`FROM` address, which can cause the mail server's IP or domain to appear on a block
list.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
Users can use the incoming email features without having to use two-factor authentication (2FA) to authenticate themselves first. This applies even if you have [enforced two-factor authentication](../security/two_factor_authentication.md) for your instance.
+{{< /alert >}}
### Linux package installations
@@ -205,9 +223,13 @@ Reply by email should now be working.
gem install gitlab-mail_room
```
- NOTE: This step is necessary to avoid thread deadlocks and to support the latest MailRoom features. See
+ {{< alert type="note" >}}
+
+This step is necessary to avoid thread deadlocks and to support the latest MailRoom features. See
[this explanation](../development/emails.md#mailroom-gem-updates) for more details.
+ {{< /alert >}}
+
1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature
and fill in the details for your specific IMAP server and email account (see [examples](#configuration-examples) below).
@@ -371,9 +393,12 @@ incoming_email:
Example configuration for Gmail/Google Workspace. Assumes mailbox `gitlab-incoming@gmail.com`.
-NOTE:
+{{< alert type="note" >}}
+
`incoming_email_email` cannot be a Gmail alias account.
+{{< /alert >}}
+
Example for Linux package installations:
```ruby
@@ -539,10 +564,13 @@ incoming_email:
##### Dedicated email address
-NOTE:
+{{< alert type="note" >}}
+
Supports [Reply by Email](reply_by_email.md) only.
Cannot support [Service Desk](../user/project/service_desk/_index.md).
+{{< /alert >}}
+
Assumes the dedicated email address `incoming@exchange.example.com`.
Example for Linux package installations:
@@ -607,11 +635,14 @@ Example configurations for Microsoft Office 365 with IMAP enabled.
##### Sub-addressing mailbox
-NOTE:
+{{< alert type="note" >}}
+
As of September 2020 sub-addressing support
[has been added to Office 365](https://support.microsoft.com/en-us/office/uservoice-pages-430e1a78-e016-472a-a10f-dc2a3df3450a). This feature is not
enabled by default, and must be enabled through PowerShell.
+{{< /alert >}}
+
This series of PowerShell commands enables [sub-addressing](#email-sub-addressing)
at the organization level in Office 365. This allows all mailboxes in the organization
to receive sub-addressed mail.
@@ -751,10 +782,13 @@ incoming_email:
##### Dedicated email address
-NOTE:
+{{< alert type="note" >}}
+
Supports [Reply by Email](reply_by_email.md) only.
Cannot support [Service Desk](../user/project/service_desk/_index.md).
+{{< /alert >}}
+
This example for Linux package installations assumes the dedicated email address `incoming@office365.example.com`:
```ruby
@@ -835,7 +869,11 @@ This example for Linux package installations assumes you're using the following
##### Configure Microsoft Graph
-> - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9.
+{{< history >}}
+
+- Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9.
+
+{{< /history >}}
```ruby
gitlab_rails['incoming_email_enabled'] = true
@@ -879,7 +917,11 @@ The Microsoft Graph API is not yet supported in self-compiled installations. See
### Use encrypted credentials
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9.
+
+{{< /history >}}
Instead of having the incoming email credentials stored in plaintext in the configuration files, you can optionally
use an encrypted file for the incoming email credentials.
@@ -894,9 +936,9 @@ The supported configuration items for the encrypted file are:
- `user`
- `password`
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. If initially your incoming email configuration in `/etc/gitlab/gitlab.rb` looked like:
@@ -925,12 +967,16 @@ The supported configuration items for the encrypted file are:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the incoming email password. For more information,
read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-incoming-emails).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. If initially your incoming email configuration in `docker-compose.yml` looked like:
@@ -968,7 +1014,9 @@ read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secre
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. If initially your incoming email configuration in `/home/git/gitlab/config/gitlab.yml` looked like:
@@ -1003,7 +1051,9 @@ read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secre
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Troubleshooting
@@ -1016,9 +1066,9 @@ This issue was fixed in 16.6.1. See [issue 432257](https://gitlab.com/gitlab-org
The workaround is to run the following commands in your GitLab installation
to patch the affected files:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
@@ -1026,7 +1076,9 @@ patch -p1 -d /opt/gitlab/embedded/service/gitlab-rails < /tmp/mailroom.patch
gitlab-ctl restart mailroom
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
@@ -1035,7 +1087,9 @@ patch -p1 < /tmp/mailroom.patch
gitlab-ctl restart mailroom
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Incoming emails are rejected by providers with email address limit
diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md
index 9ac53c6cd0c76c5dede16da52034544e3e1b8820..b993daf49fd7b4cb6aae10695c072af7a591631a 100644
--- a/doc/administration/instance_limits.md
+++ b/doc/administration/instance_limits.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab application limits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab, like most large applications, enforces limits in certain features to maintain a
minimum quality of performance. Allowing some features to be limitless could affect security,
@@ -32,7 +35,7 @@ information that is relevant to them.
To visit the instance configuration page:
-1. On the left sidebar, select **Help** (**{question-o}**) > **Help**.
+1. On the left sidebar, select **Help** ({{< icon name="question-o" >}}) > **Help**.
1. On the Help page, select **Check the current instance configuration**.
The direct URL is `<gitlab_url>/help/instance_configuration`. For GitLab.com,
@@ -143,7 +146,11 @@ Limit the maximum daily member invitations allowed per group hierarchy.
### Webhook rate limit
-> - [Limit changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89591) from per-hook to per-top-level namespace in GitLab 15.1.
+{{< history >}}
+
+- [Limit changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89591) from per-hook to per-top-level namespace in GitLab 15.1.
+
+{{< /history >}}
Limit the number of times a webhook can be called per minute, per top-level namespace.
This only applies to project and group webhooks.
@@ -166,8 +173,12 @@ Set the limit to `0` to disable it.
### Search rate limit
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104208) in GitLab 15.9 to include issue, merge request, and epic searches in the rate limit.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118525) in GitLab 16.0 to apply rate limits to [search scopes](../user/search/_index.md#disable-global-search-scopes) for authenticated requests.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104208) in GitLab 15.9 to include issue, merge request, and epic searches in the rate limit.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118525) in GitLab 16.0 to apply rate limits to [search scopes](../user/search/_index.md#disable-global-search-scopes) for authenticated requests.
+
+{{< /history >}}
This setting limits search requests as follows:
@@ -184,7 +195,11 @@ This endpoint has been requested too many times. Try again later.
### Pipeline creation rate limit
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362475) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362475) in GitLab 15.0.
+
+{{< /history >}}
This setting limits the request rate to the pipeline creation endpoints.
@@ -337,7 +352,11 @@ Blocked recursive webhook calls are logged in `auth.log` with the message `"Recu
## Import placeholder user limits
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/455903) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/455903) in GitLab 17.4.
+
+{{< /history >}}
The number of [placeholder users](../user/project/import/_index.md#placeholder-users) created during an import can be limited per top-level namespace.
@@ -360,7 +379,7 @@ The [minimum wait time between pull refreshes](../user/project/repository/mirror
defaults to 300 seconds (5 minutes). For example, a pull refresh only runs once in a given 300 second period, regardless of how many times you trigger it.
This setting applies in the context of pull refreshes invoked by using the [projects API](../api/project_pull_mirroring.md#start-the-pull-mirroring-process-for-a-project),
-or when forcing an update by selecting **Update now** (**{retry}**) in **Settings > Repository > Mirroring repositories**.
+or when forcing an update by selecting **Update now** ({{< icon name="retry" >}}) in **Settings > Repository > Mirroring repositories**.
This setting has no effect on the automatic 30 minute interval schedule used by Sidekiq for [pull mirroring](../user/project/repository/mirror/pull.md).
To change this limit for a GitLab Self-Managed instance, run the following in the
@@ -380,7 +399,11 @@ header. Such emails don't create comments on issues or merge requests.
## Amount of data sent from Sentry through Error Tracking
-> - [Limiting all Sentry responses](https://gitlab.com/gitlab-org/gitlab/-/issues/356448) introduced in GitLab 15.6.
+{{< history >}}
+
+- [Limiting all Sentry responses](https://gitlab.com/gitlab-org/gitlab/-/issues/356448) introduced in GitLab 15.6.
+
+{{< /history >}}
Sentry payloads sent to GitLab have a 1 MB maximum limit, both for security reasons
and to limit memory consumption.
@@ -563,7 +586,11 @@ This limit is [enabled on GitLab.com](../user/gitlab_com/_index.md#gitlab-cicd).
### Limit the number of schedule rules defined for security policy project
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335659) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335659) in GitLab 15.1.
+
+{{< /history >}}
You can limit the total number of schedule rules per security policy project. This limit is
checked each time policies with schedule rules are updated. If a new schedule rule would
@@ -583,7 +610,11 @@ This limit is [enabled on GitLab.com](../user/gitlab_com/_index.md#gitlab-cicd).
### CI/CD variable limits
-> - Group and project variable limits [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7.
+{{< history >}}
+
+- Group and project variable limits [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7.
+
+{{< /history >}}
The number of [CI/CD variables](../ci/variables/_index.md) that can be defined in project,
group, and instance settings are all limited for the entire instance. These limits are checked
@@ -613,8 +644,12 @@ To update the `default` plan of one of these limits on a GitLab Self-Managed ins
### Maximum file size per type of artifact
-> - `ci_max_artifact_size_annotations` limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38337) in GitLab 16.3.
-> - `ci_max_artifact_size_lsif` limit [increased](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175684) in GitLab 17.8.
+{{< history >}}
+
+- `ci_max_artifact_size_annotations` limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38337) in GitLab 16.3.
+- `ci_max_artifact_size_lsif` limit [increased](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175684) in GitLab 17.8.
+
+{{< /history >}}
Job artifacts defined with [`artifacts:reports`](../ci/yaml/_index.md#artifactsreports)
that are uploaded by the runner are rejected if the file size exceeds the maximum
@@ -698,7 +733,11 @@ of parallel Pages deployments permitted for a top-level namespace is 1000.
### Number of registered runners per scope
-> - Runner stale timeout [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155795) from 3 months to 7 days in GitLab 17.1.
+{{< history >}}
+
+- Runner stale timeout [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155795) from 3 months to 7 days in GitLab 17.1.
+
+{{< /history >}}
The total number of registered runners is limited for groups and projects. Each time a new runner is registered,
GitLab checks these limits against runners created or active in the last 7 days.
@@ -840,7 +879,11 @@ Plan.default.actual_limits.update!(dotenv_size: 5.kilobytes)
### Limit CI/CD job annotations
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38337) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38337) in GitLab 16.3.
+
+{{< /history >}}
You can set a limit on the maximum number of [annotations](../ci/yaml/artifacts_reports.md#artifactsreportsannotations)
per CI/CD job.
@@ -856,7 +899,11 @@ Plan.default.actual_limits.update!(ci_job_annotations_num: 100)
### Limit CI/CD job annotations file size
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38337) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38337) in GitLab 16.3.
+
+{{< /history >}}
You can set a limit on the maximum size of a CI/CD job [annotation](../ci/yaml/artifacts_reports.md#artifactsreportsannotations).
@@ -917,9 +964,12 @@ panel_groups:
## Environment Dashboard limits
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
See [Environment Dashboard](../ci/environments/environments_dashboard.md#adding-a-project-to-the-dashboard) for the maximum number of displayed projects.
@@ -992,9 +1042,13 @@ Set the limit to `0` to disable it.
## Math rendering limits
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132939) in GitLab 16.5.
-> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/368009) the 50-node limit from Wiki and repository files.
-> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/368009) a group-level setting to allow disabling math rendering limits, and re-enabled by default the math limits for wiki and repository files in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132939) in GitLab 16.5.
+- [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/368009) the 50-node limit from Wiki and repository files.
+- [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/368009) a group-level setting to allow disabling math rendering limits, and re-enabled by default the math limits for wiki and repository files in GitLab 16.9.
+
+{{< /history >}}
GitLab imposes default limits when rendering math in Markdown fields. These limits provide better security and performance.
@@ -1125,8 +1179,12 @@ varies by file type:
## Maximum number of assignees and reviewers
-> - Maximum assignees [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368936) in GitLab 15.6.
-> - Maximum reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366485) in GitLab 15.9.
+{{< history >}}
+
+- Maximum assignees [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368936) in GitLab 15.6.
+- Maximum reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366485) in GitLab 15.9.
+
+{{< /history >}}
Issues and merge requests enforce these maximums:
@@ -1150,9 +1208,13 @@ The [secure files API](../api/secure_files.md) enforces the following limits:
## Changelog API limits
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89032) in GitLab 15.1 [with a flag](feature_flags.md) named `changelog_commits_limitation`. Disabled by default.
-> - [Enabled on GitLab.com and by default on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/33893) in GitLab 15.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/364101) in GitLab 17.3. Feature flag `changelog_commits_limitation` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89032) in GitLab 15.1 [with a flag](feature_flags.md) named `changelog_commits_limitation`. Disabled by default.
+- [Enabled on GitLab.com and by default on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/33893) in GitLab 15.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/364101) in GitLab 17.3. Feature flag `changelog_commits_limitation` removed.
+
+{{< /history >}}
The [changelog API](../api/repositories.md#add-changelog-data-to-a-changelog-file) enforces the following limits:
diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md
index 3183db3ccd4a89a5f6fcf49891ea383f101d2702..04f073e986919f1da7e4594b61b281f8d2cf7e37 100644
--- a/doc/administration/instance_review.md
+++ b/doc/administration/instance_review.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Instance review
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you run a GitLab Self-Managed instance with 50 or more users on the Free tier
([either Community Edition or unlicensed Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/)),
diff --git a/doc/administration/integration/diagrams_net.md b/doc/administration/integration/diagrams_net.md
index 255b62be507d2aafdbc9b1ddc375af53ef6857c6..c8b68d3e168e1d07c1956bf5db18116a57ad7090 100644
--- a/doc/administration/integration/diagrams_net.md
+++ b/doc/administration/integration/diagrams_net.md
@@ -1,17 +1,24 @@
---
stage: Create
group: Source Code
-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"
-description: "Configure a Diagrams.net integration for GitLab Self-Managed."
+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
+description: Configure a Diagrams.net integration for GitLab Self-Managed.
title: Diagrams.net
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86206) in GitLab 15.10.
-> - Offline environment support [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116281) in GitLab 16.1.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86206) in GitLab 15.10.
+- Offline environment support [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116281) in GitLab 16.1.
+
+{{< /history >}}
With the [diagrams.net](https://www.drawio.com/) integration, you can create and embed SVG diagrams in wikis.
The diagram editor is available in both the plain text editor and the rich text editor.
diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md
index 1ef8bd5fff6adc9fc9bb4e7ec50008ec886d8b80..e60b8914c145beec1e58657854a557be386d7047 100644
--- a/doc/administration/integration/kroki.md
+++ b/doc/administration/integration/kroki.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Kroki
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
With the [Kroki](https://kroki.io) integration,
you can create diagrams-as-code within AsciiDoc, Markdown, reStructuredText, and Textile.
@@ -30,9 +33,12 @@ You can use the free public cloud instance `https://kroki.io` or you can [instal
on your own infrastructure.
After you've installed Kroki, make sure to update the **Kroki URL** in the settings to point to your instance.
-NOTE:
+{{< alert type="note" >}}
+
Kroki diagrams are not stored on GitLab, so standard GitLab access controls and other user permission restrictions are not in force.
+{{< /alert >}}
+
### Docker
With Docker, run a container like this:
diff --git a/doc/administration/integration/mailgun.md b/doc/administration/integration/mailgun.md
index bf170a32b07b56d59099aae2fae4a945ffc27891..9b483cead6d5ec01aa40edc37300c3d709c8e1d1 100644
--- a/doc/administration/integration/mailgun.md
+++ b/doc/administration/integration/mailgun.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Mailgun
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When you use Mailgun to send emails for your GitLab instance and [Mailgun](https://www.mailgun.com/)
integration is enabled and configured in GitLab, you can receive their webhook for
@@ -20,8 +23,12 @@ After completing the integration, Mailgun `temporary_failure` and `permanent_fai
## Configure your Mailgun domain
-> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/359113) the `/-/members/mailgun/permanent_failures` URL in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/359113) the URL to handle both temporary and permanent failures in GitLab 15.0.
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/359113) the `/-/members/mailgun/permanent_failures` URL in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/359113) the URL to handle both temporary and permanent failures in GitLab 15.0.
+
+{{< /history >}}
Before you can enable Mailgun in GitLab, set up your own Mailgun endpoints to receive the webhooks.
diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md
index aab3255790435585e81fcc2826b03438afad712d..670a741da3964049c75a82bbedcbbaa42d69c00b 100644
--- a/doc/administration/integration/plantuml.md
+++ b/doc/administration/integration/plantuml.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Configure PlantUML integration with GitLab Self-Managed."
+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
+description: Configure PlantUML integration with GitLab Self-Managed.
title: PlantUML
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
With the [PlantUML](https://plantuml.com) integration, you can create diagrams in snippets, wikis, and repositories.
This integration is enabled on GitLab.com for all users and does not require any additional configuration.
@@ -271,11 +274,14 @@ PlantUML integration is ready and listening for requests on port `8005`:
To change the Tomcat defaults, edit the `/opt/tomcat/conf/server.xml` file.
-NOTE:
+{{< alert type="note" >}}
+
The default URL is different when using this approach. The Docker-based image
makes the service available at the root URL, with no relative path. Adjust
the configuration below accordingly.
+{{< /alert >}}
+
Next, you can:
1. [Configure local PlantUML access](#configure-local-plantuml-access). Ensure the `proxy_pass` port
diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md
index 0a6975ed68c7e1330bdf97c990a1480f3b0e2348..68947f33d02057844830b000eb95b7a3ab57f500 100644
--- a/doc/administration/integration/terminal.md
+++ b/doc/administration/integration/terminal.md
@@ -5,18 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Web terminals (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
> - [Disabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/353410) in GitLab 15.0.
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
-FLAG:
+{{< /alert >}}
+
+{{< alert type="flag" >}}
+
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../feature_flags.md) named `certificate_based_clusters`.
+{{< /alert >}}
+
- Read more about the non-deprecated [Web Terminals accessible through the Web IDE](../../user/project/web_ide/_index.md).
- Read more about the non-deprecated [Web Terminals accessible from a running CI job](../../ci/interactive_web_terminal/_index.md).
@@ -27,9 +36,12 @@ GitLab can store and use credentials for a Kubernetes cluster.
GitLab uses these credentials to provide access to
[web terminals](../../ci/environments/_index.md#web-terminals-deprecated) for environments.
-NOTE:
+{{< alert type="note" >}}
+
Only users with at least the [Maintainer role](../../user/permissions.md) for the project access web terminals.
+{{< /alert >}}
+
## How it works
A detailed overview of the architecture of web terminals and how they work
@@ -65,12 +77,15 @@ detail below.
## Enabling and disabling terminal support
-NOTE:
+{{< alert type="note" >}}
+
AWS Classic Load Balancers do not support web sockets.
If you want web terminals to work, use AWS Network Load Balancers.
Read [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare)
for more information.
+{{< /alert >}}
+
As web terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of
Workhorse must be configured to pass the `Connection` and `Upgrade` headers
to the next one in the chain. GitLab is configured by default to do so.
diff --git a/doc/administration/internal_users.md b/doc/administration/internal_users.md
index 4eba77a067063f95aa38768933397c9d5068b308..6f8172708f89d4cad6a3406e43d501bea46747ad 100644
--- a/doc/administration/internal_users.md
+++ b/doc/administration/internal_users.md
@@ -5,7 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Internal users
---
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97584) in GitLab 15.4, bots are indicated with a badge in user listings.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97584) in GitLab 15.4, bots are indicated with a badge in user listings.
+
+{{< /history >}}
GitLab uses internal users (sometimes referred to as "bots") to perform actions or functions that cannot be attributed
to a regular user.
diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md
index 257b97d1f5f72734745ffbae2207745ea19c6fff..2d3a31c9296ba8e84e12cfcbb8588256b10e3f81 100644
--- a/doc/administration/invalidate_markdown_cache.md
+++ b/doc/administration/invalidate_markdown_cache.md
@@ -1,13 +1,16 @@
---
stage: Plan
group: Project Management
-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"
+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
title: Markdown cache
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
For performance reasons, GitLab caches the HTML version of Markdown text in fields such as:
diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md
index 0f8bac154589fff031841e8cf3f1d0a49e818bc9..ed1b1b9f8bf9c57c0ed6d5b3260d20333d523f42 100644
--- a/doc/administration/issue_closing_pattern.md
+++ b/doc/administration/issue_closing_pattern.md
@@ -1,20 +1,26 @@
---
stage: Create
group: Code Review
-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"
-description: "Instance administrators can configure a custom issue closing pattern for their GitLab instance."
+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
+description: Instance administrators can configure a custom issue closing pattern for their GitLab instance.
title: Issue closing pattern
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This page explains how an administrator can configure issue closing patterns.
For user documentation about the feature, see
[Closing issues automatically](../user/project/issues/managing_issues.md#closing-issues-automatically).
+{{< /alert >}}
+
When a commit or merge request resolves one or more issues, GitLab can close those issues when the
commit or merge request lands in the project's default branch.
@@ -25,9 +31,9 @@ covers a wide range of words.
To change the default issue closing pattern to suit your needs:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and change the `gitlab_rails['gitlab_issue_closing_pattern']`
value:
@@ -42,7 +48,9 @@ To change the default issue closing pattern to suit your needs:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -64,7 +72,9 @@ To change the default issue closing pattern to suit your needs:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml` and change the `gitlab_rails['gitlab_issue_closing_pattern']`
value:
@@ -84,7 +94,9 @@ To change the default issue closing pattern to suit your needs:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml` and change the `issue_closing_pattern` value:
@@ -104,7 +116,9 @@ To change the default issue closing pattern to suit your needs:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To test the issue closing pattern, use [Rubular](https://rubular.com).
Rubular does not understand `%{issue_ref}`. When you test your patterns,
diff --git a/doc/administration/labels.md b/doc/administration/labels.md
index 75cf7f88775fb4a3dff359b1730ea1e32386a810..55c50986f26ac8803fd705b98fb5377774004816 100644
--- a/doc/administration/labels.md
+++ b/doc/administration/labels.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Labels administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To manage labels for the GitLab instance:
diff --git a/doc/administration/lfs/_index.md b/doc/administration/lfs/_index.md
index ed87ce8311a1bdcabfaac8ef6ceb6b46045ca769..6b35b4cc9a0b5ac5308ecbfcda3c9798861fb80e 100644
--- a/doc/administration/lfs/_index.md
+++ b/doc/administration/lfs/_index.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Configure Git LFS for GitLab Self-Managed."
+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
+description: Configure Git LFS for GitLab Self-Managed.
title: GitLab Git Large File Storage (LFS) Administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page contains information about configuring Git LFS on GitLab Self-Managed.
For user documentation about Git LFS, see [Git Large File Storage](../../topics/git/lfs/_index.md).
@@ -21,9 +24,9 @@ Prerequisites:
LFS is enabled by default. To disable it:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -38,7 +41,9 @@ LFS is enabled by default. To disable it:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -61,7 +66,9 @@ LFS is enabled by default. To disable it:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -80,7 +87,9 @@ LFS is enabled by default. To disable it:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -100,23 +109,28 @@ LFS is enabled by default. To disable it:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Change local storage path
Git LFS objects can be large in size. By default, they are stored on the server
GitLab is installed on.
-NOTE:
+{{< alert type="note" >}}
+
For Docker installations, you can change the path where your data is mounted.
For the Helm chart, use
[object storage](https://docs.gitlab.com/charts/advanced/external-object-storage/).
+{{< /alert >}}
+
To change the default local storage path location:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -131,7 +145,9 @@ To change the default local storage path location:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -152,7 +168,9 @@ To change the default local storage path location:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Storing LFS objects in remote object storage
@@ -170,54 +188,66 @@ processing is done in the background and requires **no downtime**.
1. [Configure the object storage](../object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form).
1. Migrate the LFS objects:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake gitlab:lfs:migrate
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
```shell
sudo docker exec -t <container name> gitlab-rake gitlab:lfs:migrate
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Optional. Track the progress and verify that all job LFS objects migrated
successfully using the PostgreSQL console.
1. Open a PostgreSQL console:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-psql
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
```shell
sudo docker exec -it <container_name> /bin/bash
gitlab-psql
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo -u git -H psql -d gitlabhq_production
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Verify that all LFS files migrated to object storage with the following
SQL query. The number of `objectstg` should be the same as `total`:
@@ -232,15 +262,17 @@ processing is done in the background and requires **no downtime**.
1. Verify that there are no files on disk in the `lfs-objects` directory:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
sudo find /var/opt/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
Assuming you mounted `/var/opt/gitlab` to `/srv/gitlab`:
@@ -248,25 +280,32 @@ processing is done in the background and requires **no downtime**.
sudo find /srv/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo find /home/git/gitlab/shared/lfs-objects -type f | grep -v tmp | wc -l
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
### Migrating back to local storage
-NOTE:
+{{< alert type="note" >}}
+
For the Helm chart, you should use
[object storage](https://docs.gitlab.com/charts/advanced/external-object-storage/).
+{{< /alert >}}
+
To migrate back to local storage:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Migrate the LFS objects:
@@ -288,7 +327,9 @@ To migrate back to local storage:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Migrate the LFS objects:
@@ -313,7 +354,9 @@ To migrate back to local storage:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Migrate the LFS objects:
@@ -341,16 +384,25 @@ To migrate back to local storage:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Pure SSH transfer protocol
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11872) in GitLab 17.2.
-> - [Introduced](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/3845) for Helm chart (Kubernetes) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11872) in GitLab 17.2.
+- [Introduced](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/3845) for Helm chart (Kubernetes) in GitLab 17.3.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature is affected by [a known issue](https://github.com/git-lfs/git-lfs/issues/5880). If you clone a repository with multiple Git LFS objects using the pure SSH protocol, the client might crash due to a `nil` pointer reference.
+{{< /alert >}}
+
[`git-lfs` 3.0.0](https://github.com/git-lfs/git-lfs/blob/main/CHANGELOG.md#300-24-sep-2021)
released support for using SSH as the transfer protocol instead of HTTP.
SSH is handled transparently by the `git-lfs` command line tool.
@@ -368,9 +420,9 @@ Prerequisites:
To switch Git LFS to use pure SSH protocol:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -384,7 +436,9 @@ To switch Git LFS to use pure SSH protocol:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -408,7 +462,9 @@ To switch Git LFS to use pure SSH protocol:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -426,7 +482,9 @@ To switch Git LFS to use pure SSH protocol:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab-shell/config.yml`:
@@ -445,7 +503,9 @@ To switch Git LFS to use pure SSH protocol:
sudo service gitlab-shell restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Storage statistics
@@ -603,9 +663,12 @@ If you encounter this, follow these steps to diagnose and resolve the issue:
1. Repeat the fork operation.
-NOTE:
+{{< alert type="note" >}}
+
If you are using GitLab Helm Chart, use [extraEnv](https://docs.gitlab.com/charts/charts/globals.html#extraenv) to configure the environment variable `GITLAB_LFS_MAX_OID_TO_FETCH`.
+{{< /alert >}}
+
## Known limitations
- Only compatible with the Git LFS client versions 1.1.0 and later, or 1.0.2.
diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md
index 0829487c5738998c41403a384c7b623108f87760..984bf7baa451bba1334889d84b6cb157013aaf97 100644
--- a/doc/administration/libravatar.md
+++ b/doc/administration/libravatar.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using the Libravatar service with GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab by default supports the [Gravatar](https://gravatar.com) avatar service.
diff --git a/doc/administration/license.md b/doc/administration/license.md
index acf5e198d55669290c9234d5fb10030c11a4cac4..c49bdee890dc69e9dc70ec71daf3a100ddb1da1a 100644
--- a/doc/administration/license.md
+++ b/doc/administration/license.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Activate GitLab Enterprise Edition (EE)
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When you install a new GitLab instance without a license, only Free features
are enabled. To enable more features in GitLab Enterprise Edition (EE), activate
@@ -75,7 +78,7 @@ some functionality is locked.
## Verify your GitLab edition
To verify the edition, sign in to GitLab and select
-**Help** (**{question-o}**) > **Help**. The GitLab edition and version are listed
+**Help** ({{< icon name="question-o" >}}) > **Help**. The GitLab edition and version are listed
at the top of the page.
If you are running GitLab Community Edition (CE), you can upgrade your installation to GitLab
diff --git a/doc/administration/license_file.md b/doc/administration/license_file.md
index 081236a269582aee806e5d7f7f7c95ee82fd281d..31ea74ebababc1d794d2f7301f71ffb550621852 100644
--- a/doc/administration/license_file.md
+++ b/doc/administration/license_file.md
@@ -25,7 +25,11 @@ Otherwise, add your license in the Admin area.
## Activate subscription during installation
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114572) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114572) in GitLab 16.0.
+
+{{< /history >}}
To activate your subscription during installation, set the `GITLAB_ACTIVATION_CODE` environment variable with the activation code:
@@ -56,10 +60,13 @@ If you have a license, you can also import it when you install GitLab.
- For Helm Charts installations, use [the `global.gitlab.license` configuration keys](https://docs.gitlab.com/charts/installation/command-line-options.html#basic-configuration).
-WARNING:
+{{< alert type="warning" >}}
+
These methods only add a license at the time of installation. To renew or upgrade
a license, add the license in the **Admin area** in the web user interface.
+{{< /alert >}}
+
## Submit license usage data
If you use a license file or key to activate your instance in an offline environment, you are encouraged to submit your license
@@ -129,10 +136,13 @@ You can also [export](../subscriptions/self_managed/_index.md) your license usag
The following commands can be run in the [Rails console](operations/rails_console.md#starting-a-rails-console-session).
-WARNING:
+{{< alert type="warning" >}}
+
Any command that changes data directly could be damaging if not run correctly, or under the right conditions.
We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case.
+{{< /alert >}}
+
### See current license information
```ruby
diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md
index 7f67a134c8e1e3c2f7794ff494debe9ffa6f762a..f812545480effd17dc7c53e5865bc3a56705f0a6 100644
--- a/doc/administration/load_balancer.md
+++ b/doc/administration/load_balancer.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Load Balancer for multi-node GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
In a multi-node GitLab configuration, you need a load balancer to route
traffic to the application servers. The specifics on which load balancer to use
@@ -118,9 +121,12 @@ Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com`.
It is strongly recommend that multi-node deployments configure load balancers to use the [readiness check](monitoring/health_check.md#readiness) to ensure a node is ready to accept traffic, before routing traffic to it. This is especially important when using Puma, because there is a brief period during a restart where Puma doesn't accept requests.
-WARNING:
+{{< alert type="warning" >}}
+
Using the `all=1` parameter with the readiness check in GitLab versions 15.4 to 15.8 may cause [increased Praefect memory usage](https://gitlab.com/gitlab-org/gitaly/-/issues/4751) and lead to memory errors.
+{{< /alert >}}
+
## Troubleshooting
### The health check is returning a `408` HTTP code via the load balancer
diff --git a/doc/administration/logs/_index.md b/doc/administration/logs/_index.md
index 159dc38b29c72561417eac1079fafff740610a46..00f7142de5401266aef7c1cf03f30cc8b75f07be 100644
--- a/doc/administration/logs/_index.md
+++ b/doc/administration/logs/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Log system
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab has an advanced log system where everything is logged, so you can analyze your instance using various system log
files. The log system is similar to [audit events](../audit_event_reports.md).
@@ -86,25 +89,25 @@ except those captured by `runit`.
| Log type | Managed by logrotate | Managed by svlogd/runit |
|:------------------------------------------------|:------------------------|:------------------------|
-| [Alertmanager logs](#alertmanager-logs) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [crond logs](#crond-logs) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Gitaly](#gitaly-logs) | **{check-circle}** Yes | **{check-circle}** Yes |
-| [GitLab Exporter for Linux package installations](#gitlab-exporter) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [GitLab Pages logs](#pages-logs) | **{check-circle}** Yes | **{check-circle}** Yes |
-| GitLab Rails | **{check-circle}** Yes | **{dotted-circle}** No |
-| [GitLab Shell logs](#gitlab-shelllog) | **{check-circle}** Yes | **{dotted-circle}** No |
-| [Grafana logs](#grafana-logs) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [LogRotate logs](#logrotate-logs) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Mailroom](#mail_room_jsonlog-default) | **{check-circle}** Yes | **{check-circle}** Yes |
-| [NGINX](#nginx-logs) | **{check-circle}** Yes | **{check-circle}** Yes |
-| [PgBouncer logs](#pgbouncer-logs) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [PostgreSQL logs](#postgresql-logs) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Praefect logs](#praefect-logs) | **{dotted-circle}** Yes | **{check-circle}** Yes |
-| [Prometheus logs](#prometheus-logs) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Puma](#puma-logs) | **{check-circle}** Yes | **{check-circle}** Yes |
-| [Redis logs](#redis-logs) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Registry logs](#registry-logs) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Workhorse logs](#workhorse-logs) | **{check-circle}** Yes | **{check-circle}** Yes |
+| [Alertmanager logs](#alertmanager-logs) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [crond logs](#crond-logs) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Gitaly](#gitaly-logs) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [GitLab Exporter for Linux package installations](#gitlab-exporter) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [GitLab Pages logs](#pages-logs) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| GitLab Rails | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [GitLab Shell logs](#gitlab-shelllog) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [Grafana logs](#grafana-logs) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [LogRotate logs](#logrotate-logs) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Mailroom](#mail_room_jsonlog-default) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [NGINX](#nginx-logs) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [PgBouncer logs](#pgbouncer-logs) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [PostgreSQL logs](#postgresql-logs) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Praefect logs](#praefect-logs) | {{< icon name="dotted-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [Prometheus logs](#prometheus-logs) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Puma](#puma-logs) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [Redis logs](#redis-logs) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Registry logs](#registry-logs) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Workhorse logs](#workhorse-logs) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
## `production_json.log`
@@ -214,12 +217,15 @@ The ActionCable connection or channel class is used as the `controller`.
}
```
-NOTE:
+{{< alert type="note" >}}
+
If an error occurs, an
`exception` field is included with `class`, `message`, and
`backtrace`. Previous versions included an `error` field instead of
`exception.class` and `exception.message`. For example:
+{{< /alert >}}
+
```json
{
"method": "GET",
@@ -345,15 +351,22 @@ associated SSH key can download the project in question by using a `git fetch` o
- `params`: Key-value pairs passed in a query string or HTTP body (sensitive parameters, such as passwords and tokens, are filtered out)
- `ua`: The User-Agent of the requester
-NOTE:
+{{< alert type="note" >}}
+
As of [`Grape Logging`](https://github.com/aserafin/grape_logging) v1.8.4,
the `view_duration_s` is calculated by [`duration_s - db_duration_s`](https://github.com/aserafin/grape_logging/blob/v1.8.4/lib/grape_logging/middleware/request_logger.rb#L117-L119).
Therefore, `view_duration_s` can be affected by multiple different factors, like read-write
process on Redis or external HTTP, not only the serialization process.
+{{< /alert >}}
+
## `application.log` (deprecated)
-> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111046) in GitLab 15.10.
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111046) in GitLab 15.10.
+
+{{< /history >}}
This file is located at:
@@ -431,7 +444,11 @@ like this example:
## `kubernetes.log` (deprecated)
-> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+
+{{< /history >}}
This file is located at:
@@ -464,14 +481,20 @@ only. For example:
## `audit_json.log`
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
GitLab Free tracks a small number of different audit events.
GitLab Premium tracks many more.
+{{< /alert >}}
+
This file is located at:
- `/var/log/gitlab/gitlab-rails/audit_json.log` on Linux package installations.
@@ -504,7 +527,11 @@ and as follows.
### `sidekiq.log`
-> - The default log format for Helm chart installations [changed from `text` to `json`](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/3169) in GitLab 16.0 and later.
+{{< history >}}
+
+- The default log format for Helm chart installations [changed from `text` to `json`](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/3169) in GitLab 16.0 and later.
+
+{{< /history >}}
This file is located at:
@@ -730,7 +757,11 @@ are recorded in this file. For example:
## `ci_resource_groups_json.log`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384180) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384180) in GitLab 15.9.
+
+{{< /history >}}
This file is located at:
@@ -796,7 +827,11 @@ GraphQL queries are recorded in the file. For example:
## `clickhouse.log`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133371) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133371) in GitLab 16.5.
+
+{{< /history >}}
The `clickhouse.log` file logs information related to the
[ClickHouse database client](../../integration/clickhouse.md) in GitLab.
@@ -822,7 +857,11 @@ Its name and path are configurable, so the name and path may not match the above
## `web_hooks.log`
-> - Introduced in GitLab 16.3.
+{{< history >}}
+
+- Introduced in GitLab 16.3.
+
+{{< /history >}}
This file is located at:
@@ -870,9 +909,12 @@ are generated in a location based on your installation method:
## `database_load_balancing.log`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Contains details of GitLab [Database Load Balancing](../postgresql/database_load_balancing.md).
This file is located at:
@@ -882,11 +924,18 @@ This file is located at:
## `zoekt.log`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110980) in GitLab 15.9.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110980) in GitLab 15.9.
+
+{{< /history >}}
This file logs information related to [exact code search](../../user/search/exact_code_search.md).
This file is located at:
@@ -896,9 +945,12 @@ This file is located at:
## `elasticsearch.log`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This file logs information related to the Elasticsearch Integration, including
errors during indexing or searching Elasticsearch. This file is located at:
@@ -970,9 +1022,12 @@ For example:
## `geo.log`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Geo stores structured log messages in a `geo.log` file. For Linux package installations,
this file is at `/var/log/gitlab/gitlab-rails/geo.log`.
@@ -1021,24 +1076,38 @@ can be used.
## `llm.log`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120506) in GitLab 16.0.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120506) in GitLab 16.0.
+
+{{< /history >}}
The `llm.log` file logs information related to
[AI features](../../user/ai_features.md). Logging includes information about AI events.
### LLM input and output logging
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13401) in GitLab 17.2 [with a flag](../feature_flags.md) named `expanded_ai_logging`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13401) in GitLab 17.2 [with a flag](../feature_flags.md) named `expanded_ai_logging`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
LLM prompt input and response output can be logged by enabling the `expanded_ai_logging` feature flag.
This flag is disabled by default and can only be enabled:
@@ -1054,11 +1123,18 @@ The log file is located at:
## `epic_work_item_sync.log`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120506) in GitLab 16.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120506) in GitLab 16.9.
+{{< /history >}}
The `epic_work_item_sync.log` file logs information related to syncing and migrating epics as work items.
@@ -1069,11 +1145,18 @@ This file is located at:
## `secret_push_protection.log`
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137812) in GitLab 16.7.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137812) in GitLab 16.7.
+
+{{< /history >}}
The `secret_push_protection.log` file logs information related to [Secret Push Protection](../../user/application_security/secret_detection/secret_push_protection/_index.md) feature.
@@ -1238,9 +1321,12 @@ When [troubleshooting](../troubleshooting/_index.md) issues that aren't localize
previously listed components, it's helpful to simultaneously gather multiple logs and statistics
from a GitLab instance.
-NOTE:
+{{< alert type="note" >}}
+
GitLab Support often asks for one of these, and maintains the required tools.
+{{< /alert >}}
+
### Briefly tail the main logs
If the bug or error is readily reproducible, save the main GitLab logs
diff --git a/doc/administration/logs/log_parsing.md b/doc/administration/logs/log_parsing.md
index 9630ccd33d0828332ea9c1ac56e92089554e7bae..b256e21101bcd63d4a970cf87c1a6976577f27dc 100644
--- a/doc/administration/logs/log_parsing.md
+++ b/doc/administration/logs/log_parsing.md
@@ -5,20 +5,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Parsing GitLab logs with `jq`
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
We recommend using log aggregation and search tools like Kibana and Splunk whenever possible,
but if they are not available you can still quickly parse
[GitLab logs](../logs/_index.md) in JSON format
using [`jq`](https://stedolan.github.io/jq/).
-NOTE:
+{{< alert type="note" >}}
+
Specifically for summarizing error events and basic usage statistics,
the GitLab Support Team provides the specialised
[`fast-stats` tool](https://gitlab.com/gitlab-com/support/toolbox/fast-stats/#when-to-use-it).
+{{< /alert >}}
+
## What is JQ?
As noted in its [manual](https://stedolan.github.io/jq/manual/), `jq` is a command-line JSON processor. The following examples
diff --git a/doc/administration/logs/tracing_correlation_id.md b/doc/administration/logs/tracing_correlation_id.md
index 07c0e29a95400b9eb9eb42b614c8e043aeb283cc..31d5367fc6d3900853e3993d459377d9dd4a0c41 100644
--- a/doc/administration/logs/tracing_correlation_id.md
+++ b/doc/administration/logs/tracing_correlation_id.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Find relevant log entries with a correlation ID
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab instances log a unique request tracking ID (known as the
"correlation ID") for most requests. Each individual request to GitLab gets
diff --git a/doc/administration/maintenance_mode/_index.md b/doc/administration/maintenance_mode/_index.md
index 5580d0f2a4fc5632a9098083f5f077c703c94d2e..79bc457121c094ff88a710373219f4c88c070070 100644
--- a/doc/administration/maintenance_mode/_index.md
+++ b/doc/administration/maintenance_mode/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Maintenance Mode
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
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. The internal state includes the PostgreSQL database, but especially files, Git repositories, and Container repositories.
@@ -60,9 +63,12 @@ An error is displayed when a user tries to perform a write operation that isn't
-NOTE:
+{{< alert type="note" >}}
+
In some cases, the visual feedback from an action could be misleading. For example, when starring a project, the **Star** button changes to show the **Unstar** action. However, this is only the frontend update, and it doesn't take into account the failed status of the POST request. These visual bugs are to be fixed [in follow-up iterations](https://gitlab.com/gitlab-org/gitlab/-/issues/295197).
+{{< /alert >}}
+
### Administrator functions
Systems administrators can edit the application settings. This allows
@@ -114,7 +120,11 @@ For most JSON requests, `POST`, `PUT`, `PATCH`, and `DELETE` are blocked, and th
### GraphQL API
-> - The `GeoRegistriesUpdate` mutation addition in the allowlist was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124259) in GitLab 16.2.
+{{< history >}}
+
+- The `GeoRegistriesUpdate` mutation addition in the allowlist was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124259) in GitLab 16.2.
+
+{{< /history >}}
`POST /api/graphql` requests are allowed but mutations are blocked with the error message `You cannot perform write operations on a read-only instance`.
@@ -134,10 +144,13 @@ After Maintenance Mode is disabled, new jobs are picked up again. Jobs that were
in the `running` state before enabling Maintenance Mode resume and their logs start
updating again.
-NOTE:
+{{< alert type="note" >}}
+
You should restart previously `running` pipelines after Maintenance Mode
is turned off.
+{{< /alert >}}
+
### Deployments
Deployments don't go through because pipelines are unfinished.
diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md
index d44358f1f191c7caed148750715aeefd6f8f2fe4..bd4c76e439ca6661ed83627893b21213fc5baad1 100644
--- a/doc/administration/merge_request_diffs.md
+++ b/doc/administration/merge_request_diffs.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Configure external storage for merge request diffs on your GitLab instance."
+description: Configure external storage for merge request diffs on your GitLab instance.
title: Merge request diffs storage
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Merge request diffs are size-limited copies of diffs associated with merge
requests. When viewing a merge request, diffs are sourced from these copies
@@ -26,9 +29,9 @@ Merge request diffs can be stored:
## Using external storage
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -48,7 +51,9 @@ Merge request diffs can be stored:
1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
GitLab then migrates your existing merge request diffs to external storage.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
@@ -72,20 +77,25 @@ Merge request diffs can be stored:
1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect.
GitLab then migrates your existing merge request diffs to external storage.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Using object storage
-WARNING:
+{{< alert type="warning" >}}
+
Migrating to object storage is not reversible.
+{{< /alert >}}
+
Instead of storing the external diffs on disk, we recommended the use of an object
store like AWS S3 instead. This configuration relies on valid AWS credentials to
be configured already.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -97,7 +107,9 @@ be configured already.
1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
GitLab then migrates your existing merge request diffs to external storage.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
@@ -111,7 +123,9 @@ be configured already.
1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect.
GitLab then migrates your existing merge request diffs to external storage.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
[Read more about using object storage with GitLab](object_storage.md).
@@ -129,9 +143,9 @@ in the database.
To enable this feature, perform the following steps:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -141,7 +155,9 @@ To enable this feature, perform the following steps:
1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
@@ -154,7 +170,9 @@ To enable this feature, perform the following steps:
1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
With this feature enabled, diffs are initially stored in the database, rather
than externally. They are moved to external storage after any of these
diff --git a/doc/administration/merge_requests_approvals.md b/doc/administration/merge_requests_approvals.md
index d9553dfef767ea6762eb81c37dd0cd298d5fcb74..47ef0df1277017947d0ec246943f9134653e12e6 100644
--- a/doc/administration/merge_requests_approvals.md
+++ b/doc/administration/merge_requests_approvals.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Configure merge request approvals for your GitLab instance."
+description: Configure merge request approvals for your GitLab instance.
title: Merge request approvals
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Merge request approval rules prevent users from overriding certain settings for the project.
When enabled for the entire instance, these settings
diff --git a/doc/administration/moderate_users.md b/doc/administration/moderate_users.md
index 9ed351141408f9567ace1f15bf063cb2be1ea400..fcd5d61ebb54af3028e18364d6f07e40c5e88d4f 100644
--- a/doc/administration/moderate_users.md
+++ b/doc/administration/moderate_users.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Moderate users
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you are an instance administrator, you have several options to moderate and control user access.
-NOTE:
+{{< alert type="note" >}}
+
This topic is specifically related to user moderation in GitLab Self-Managed. For information related to groups, see the [group documentation](../user/group/moderate_users.md).
+{{< /alert >}}
+
## Users pending approval
A user in _pending approval_ state requires action by an administrator. A user sign up can be in a
@@ -42,7 +48,11 @@ sign in.
### View user sign ups pending approval
-> - Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+{{< history >}}
+
+- Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+
+{{< /history >}}
To view user sign ups pending approval:
@@ -52,7 +62,11 @@ To view user sign ups pending approval:
### Approve or reject a user sign up
-> - Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+{{< history >}}
+
+- Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+
+{{< /history >}}
A user sign up pending approval can be approved or rejected from the **Admin** area.
@@ -61,7 +75,7 @@ To approve or reject a user sign up:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
1. In the search box, filter by **State=Pending approval** and press <kbd>Enter</kbd>.
-1. For the user sign up you want to approve or reject, select the vertical ellipsis (**{ellipsis_v}**), then **Approve** or **Reject**.
+1. For the user sign up you want to approve or reject, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then **Approve** or **Reject**.
Approving a user:
@@ -111,7 +125,7 @@ To block a user:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
-1. For the user you want to block, select the vertical ellipsis (**{ellipsis_v}**), then **Block**.
+1. For the user you want to block, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then **Block**.
The user receives an email notification that their account has been blocked. After this email, they no longer receive notifications.
@@ -119,21 +133,28 @@ To report abuse from other users, see [report abuse](../user/report_abuse.md). F
### Unblock a user
-> - Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+{{< history >}}
+
+- Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+
+{{< /history >}}
A blocked user can be unblocked from the **Admin** area. To do this:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
1. In the search box, filter by **State=Blocked** and press <kbd>Enter</kbd>.
-1. For the user you want to unblock, select the vertical ellipsis (**{ellipsis_v}**), then **Unblock**.
+1. For the user you want to unblock, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then **Unblock**.
The user's state is set to active and they consume a
[seat](../subscriptions/self_managed/_index.md#billable-users).
-NOTE:
+{{< alert type="note" >}}
+
Users can also be unblocked using the [GitLab API](../api/user_moderation.md#unblock-access-to-a-user).
+{{< /alert >}}
+
The unblock option may be unavailable for LDAP users. To enable the unblock option,
the LDAP identity first needs to be deleted:
@@ -169,7 +190,7 @@ To deactivate a user:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
-1. For the user you want to deactivate, select the vertical ellipsis (**{ellipsis_v}**) and then **Deactivate**.
+1. For the user you want to deactivate, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and then **Deactivate**.
1. On the dialog, select **Deactivate**.
The user receives an email notification that their account has been deactivated. After this email, they no longer receive notifications.
@@ -182,8 +203,12 @@ To remove a user from a GitLab.com subscription, see
### Automatically deactivate dormant users
-> - Customizable time period [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336747) in GitLab 15.4
-> - The lower limit for inactive period set to 90 days [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100793) in GitLab 15.5
+{{< history >}}
+
+- Customizable time period [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336747) in GitLab 15.4
+- The lower limit for inactive period set to 90 days [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100793) in GitLab 15.5
+
+{{< /history >}}
Administrators can enable automatic deactivation of users who either:
@@ -203,17 +228,27 @@ When this feature is enabled, GitLab runs a daily job to deactivate the dormant
A maximum of 100,000 users can be deactivated per day.
-NOTE:
+{{< alert type="note" >}}
+
GitLab generated bots are excluded from the automatic deactivation of dormant users.
+{{< /alert >}}
+
### Automatically delete unconfirmed users
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352514) in GitLab 16.1 [with a flag](feature_flags.md) named `delete_unconfirmed_users_setting`. Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124982) in GitLab 16.2.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352514) in GitLab 16.1 [with a flag](feature_flags.md) named `delete_unconfirmed_users_setting`. Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124982) in GitLab 16.2.
+
+{{< /history >}}
Prerequisites:
@@ -240,7 +275,11 @@ A maximum of 240,000 users can be deleted per day.
### Reactivate a user
-> - Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+{{< history >}}
+
+- Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+
+{{< /history >}}
You can reactivate a deactivated user from the **Admin** area.
@@ -249,20 +288,27 @@ To do this:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
1. In the search box, filter by **State=Deactivated** and press <kbd>Enter</kbd>.
-1. For the user you want to reactivate, select the vertical ellipsis (**{ellipsis_v}**), then **Activate**.
+1. For the user you want to reactivate, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then **Activate**.
The user's state is set to active and they consume a
[seat](../subscriptions/self_managed/_index.md#billable-users).
-NOTE:
+{{< alert type="note" >}}
+
A deactivated user can also reactivate their account themselves by logging back in through the UI.
Users can also be reactivated using the [GitLab API](../api/user_moderation.md#reactivate-a-user).
+{{< /alert >}}
+
## Ban and unban users
-> - Hiding merge requests of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107836) in GitLab 15.8 [with a flag](feature_flags.md) named `hide_merge_requests_from_banned_users`. Disabled by default.
-> - Hiding comments of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112973) in GitLab 15.11 [with a flag](feature_flags.md) named `hidden_notes`. Disabled by default.
-> - Hiding projects of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121488) in GitLab 16.2 [with a flag](feature_flags.md) named `hide_projects_of_banned_users`. Disabled by default.
+{{< history >}}
+
+- Hiding merge requests of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107836) in GitLab 15.8 [with a flag](feature_flags.md) named `hide_merge_requests_from_banned_users`. Disabled by default.
+- Hiding comments of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112973) in GitLab 15.11 [with a flag](feature_flags.md) named `hidden_notes`. Disabled by default.
+- Hiding projects of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121488) in GitLab 16.2 [with a flag](feature_flags.md) named `hide_projects_of_banned_users`. Disabled by default.
+
+{{< /history >}}
GitLab administrators can ban and unban users.
You should ban a user when you want to block them and hide their activity from the instance.
@@ -282,19 +328,23 @@ To ban a user:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
-1. Next to the member you want to ban, select the vertical ellipsis (**{ellipsis_v}**).
+1. Next to the member you want to ban, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. From the dropdown list, select **Ban member**.
### Unban a user
-> - Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+{{< history >}}
+
+- Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+
+{{< /history >}}
To unban a user:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
1. In the search box , filter by **State=Banned** and press <kbd>Enter</kbd>.
-1. Next to the member you want to ban, select the vertical ellipsis (**{ellipsis_v}**).
+1. Next to the member you want to ban, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. From the dropdown list, select **Unban member**.
The user's state is set to active and they consume a
@@ -306,28 +356,38 @@ Use the **Admin** area to delete users.
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
-1. For the user you want to delete, select the vertical ellipsis (**{ellipsis_v}**), then **Delete user**.
+1. For the user you want to delete, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then **Delete user**.
1. Type the username.
1. Select **Delete user**.
-NOTE:
+{{< alert type="note" >}}
+
You can only delete a user if there are inherited or direct owners of a group. You cannot delete a user if they are the only group owner.
+{{< /alert >}}
+
You can also delete a user and their contributions, such as merge requests, issues, and groups of which they are the only group owner.
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
-1. For the user you want to delete, select the vertical ellipsis (**{ellipsis_v}**), then **Delete user and contributions**.
+1. For the user you want to delete, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then **Delete user and contributions**.
1. Type the username.
1. Select **Delete user and contributions**.
-NOTE:
+{{< alert type="note" >}}
+
Before 15.1, additionally groups of which deleted user were the only owner among direct members were deleted.
+{{< /alert >}}
+
## Trust and untrust users
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132402) in GitLab 16.5.
-> - Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132402) in GitLab 16.5.
+- Filter users by state [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238183) in GitLab 17.0.
+
+{{< /history >}}
You can trust and untrust users from the **Admin** area.
@@ -337,9 +397,9 @@ Prerequisites:
- You must be an administrator.
-::Tabs
+{{< tabs >}}
-:::TabTitle Trust a user
+{{< tab title="Trust a user" >}}
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
@@ -349,7 +409,9 @@ Prerequisites:
The user is trusted.
-:::TabTitle Untrust a user
+{{< /tab >}}
+
+{{< tab title="Untrust a user" >}}
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Overview > Users**.
@@ -360,7 +422,9 @@ The user is trusted.
The user is untrusted.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Troubleshooting
@@ -370,9 +434,12 @@ When moderating users, you may need to perform bulk actions on them based on cer
Administrators can deactivate users that have no recent activity.
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
days_inactive = 90
inactive_users = User.active.where("last_activity_on <= ?", days_inactive.days.ago)
@@ -387,9 +454,12 @@ end
Administrators can block users that have no recent activity.
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
days_inactive = 90
inactive_users = User.active.where("last_activity_on <= ?", days_inactive.days.ago)
@@ -404,9 +474,12 @@ end
Administrators can block or delete users that have no projects or groups.
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
users = User.where('id NOT IN (select distinct(user_id) from project_authorizations)')
diff --git a/doc/administration/monitoring/_index.md b/doc/administration/monitoring/_index.md
index acb4821b6365a7652ae646460490d0a5659df368..589b340d4344ce3606323cce5a767a20d3f5e738 100644
--- a/doc/administration/monitoring/_index.md
+++ b/doc/administration/monitoring/_index.md
@@ -1,14 +1,17 @@
---
stage: Monitor
group: Platform Insights
-description: Performance, health, uptime monitoring.
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
+description: Performance, health, uptime monitoring.
title: Monitor GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Explore our features to monitor your GitLab instance:
diff --git a/doc/administration/monitoring/github_imports.md b/doc/administration/monitoring/github_imports.md
index a480fbf9b85df4691b59c5c3befc4b87f5b84bdb..6b5a582015adb6e965013b21398f186ff1b212fa 100644
--- a/doc/administration/monitoring/github_imports.md
+++ b/doc/administration/monitoring/github_imports.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Monitoring GitHub imports
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The GitHub importer exposes various Prometheus metrics that you can use to
monitor the health and progress of the importer.
diff --git a/doc/administration/monitoring/health_check.md b/doc/administration/monitoring/health_check.md
index 7d4d3056931afac3b83d0a71e577214e66fc1bd5..0dac5ce358244c6c8f5f5bdd087322d33ab9b2be 100644
--- a/doc/administration/monitoring/health_check.md
+++ b/doc/administration/monitoring/health_check.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Health check
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides liveness and readiness probes to indicate service health and
reachability to required services. These probes report on the status of the
@@ -120,11 +123,14 @@ This check is being exempt from Rack Attack.
## Liveness
-WARNING:
+{{< alert type="warning" >}}
+
In GitLab [12.4](https://about.gitlab.com/upcoming-releases/)
the response body of the Liveness check was changed
to match the example below.
+{{< /alert >}}
+
Checks whether the application server is running.
This probe is used to know if Rails Controllers
are not deadlocked due to a multi-threading.
diff --git a/doc/administration/monitoring/ip_allowlist.md b/doc/administration/monitoring/ip_allowlist.md
index 5b8ec78675f030bb5121ee465a534cbb19f0f0e2..821bd3f17e2acda378b8c631b33a569b0b755808 100644
--- a/doc/administration/monitoring/ip_allowlist.md
+++ b/doc/administration/monitoring/ip_allowlist.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: IP allowlist
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides some [monitoring endpoints](health_check.md)
that provide health check information when probed.
@@ -15,9 +18,9 @@ that provide health check information when probed.
To control access to those endpoints through IP allowlisting, you can add single
hosts or use IP ranges:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Open `/etc/gitlab/gitlab.rb` and add or uncomment the following:
@@ -27,7 +30,9 @@ hosts or use IP ranges:
1. Save the file and [reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab for the changes to take effect.
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
You can set the required IPs under the `gitlab.webservice.monitoring.ipWhitelist` key. For example:
@@ -40,7 +45,9 @@ gitlab:
- 0.0.0.0/0 # Default
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `config/gitlab.yml`:
@@ -54,4 +61,6 @@ gitlab:
1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/administration/monitoring/performance/_index.md b/doc/administration/monitoring/performance/_index.md
index 656a1b51e02f7887d44010ab1c58947e80dc7ab2..23071e3612259558ba75b829e6f6c2a3c9725fa7 100644
--- a/doc/administration/monitoring/performance/_index.md
+++ b/doc/administration/monitoring/performance/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Performance Monitoring
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab comes with its own application performance measuring system called GitLab Performance Monitoring.
GitLab Performance Monitoring is available in both the Community and Enterprise editions.
diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md
index 037ff8c8b9e62adafc84a655ce297ec53893ee06..a437c1670b74a13e5ce2d6e276a5fee9b161cbaa 100644
--- a/doc/administration/monitoring/performance/grafana_configuration.md
+++ b/doc/administration/monitoring/performance/grafana_configuration.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure Grafana
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Grafana bundled with GitLab was [deprecated](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7772) in GitLab 16.0.
-> - Grafana bundled with GitLab was [removed](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7772) in GitLab 16.3.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Grafana bundled with GitLab was [deprecated](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7772) in GitLab 16.0.
+- Grafana bundled with GitLab was [removed](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7772) in GitLab 16.3.
+
+{{< /history >}}
[Grafana](https://grafana.com/) is a tool that enables you to visualize time
series metrics through graphs and dashboards. GitLab writes performance data to Prometheus,
diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md
index 3b964224166d30d5f0cda5af9e6260d336a0b935..faec305f8cd15a3d935a26e885e297be3edf8282 100644
--- a/doc/administration/monitoring/performance/performance_bar.md
+++ b/doc/administration/monitoring/performance/performance_bar.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Performance bar
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can display the performance bar to see statistics for the performance of a GitLab UI page.
For example:
@@ -16,7 +19,11 @@ For example:
## Available information
-> - Rugged calls [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/421591) in GitLab 16.6.
+{{< history >}}
+
+- Rugged calls [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/421591) in GitLab 16.6.
+
+{{< /history >}}
From left to right, the performance bar displays:
@@ -76,12 +83,15 @@ From left to right, the performance bar displays:
- **Stats** (optional): if the `GITLAB_PERFORMANCE_BAR_STATS_URL` environment variable is set,
this URL is displayed in the bar. Used only on GitLab.com.
-NOTE:
+{{< alert type="note" >}}
+
Not all indicators are available in all environments. For instance, the memory view
requires running Ruby with [specific patches](https://gitlab.com/gitlab-org/gitlab-build-images/-/blob/master/patches/ruby/2.7.4/thread-memory-allocations-2.7.patch)
applied. When running GitLab locally using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit),
this is typically not the case and the memory view cannot be used.
+{{< /alert >}}
+
## Keyboard shortcut
Press the [<kbd>p</kbd> + <kbd>b</kbd> keyboard shortcut](../../../user/shortcuts.md) to display
@@ -92,7 +102,7 @@ For non-administrators to display the performance bar, it must be
## Request warnings
-Requests that exceed predefined limits display a warning **{warning}** icon and
+Requests that exceed predefined limits display a warning {{< icon name="warning" >}} icon and
explanation next to the metric. In this example, the Gitaly call duration
exceeded the threshold.
diff --git a/doc/administration/monitoring/prometheus/_index.md b/doc/administration/monitoring/prometheus/_index.md
index 28f356c8ab5198e51c1c941d9f0ba8f23f429053..245d2decd210d8cb2a1b91f14b600dff81fbcf10 100644
--- a/doc/administration/monitoring/prometheus/_index.md
+++ b/doc/administration/monitoring/prometheus/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Monitoring GitLab with Prometheus
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
[Prometheus](https://prometheus.io) is a powerful time-series monitoring service, providing a flexible
platform for monitoring GitLab and other software products.
@@ -60,11 +63,14 @@ To disable Prometheus and all of its exporters, as well as any added in the futu
### Changing the port and address Prometheus listens on
-WARNING:
+{{< alert type="warning" >}}
+
Although possible, it's not recommended to change the port Prometheus listens
on, as this might affect or conflict with other services running on the GitLab
server. Proceed at your own risk.
+{{< /alert >}}
+
To access Prometheus from outside the GitLab server,
change the address/port that Prometheus
listens on:
@@ -172,9 +178,12 @@ ensure that `prometheus['scrape_configs']` is not set in `/etc/gitlab/gitlab.rb`
### Using an external Prometheus server
-WARNING:
+{{< alert type="warning" >}}
+
Prometheus and most exporters don't support authentication. We don't recommend exposing them outside the local network.
+{{< /alert >}}
+
A few configuration changes are required to allow GitLab to be monitored by an external Prometheus server.
To use an external Prometheus server:
@@ -314,11 +323,14 @@ To use an external Prometheus server:
- 1.1.1.1:5001
```
- WARNING:
+ {{< alert type="warning" >}}
+
The `gitlab-rails` job in the snippet assumes that GitLab is reachable through HTTPS. If your
deployment doesn't use HTTPS, the job configuration is adapted to use the `http` scheme and port
80.
+ {{< /alert >}}
+
1. Reload the Prometheus server.
### Configure the storage retention size
@@ -372,9 +384,12 @@ For a more fully featured dashboard, Grafana can be used and has
Below are some sample Prometheus queries that can be used.
-NOTE:
+{{< alert type="note" >}}
+
These are only examples and may not work on all setups. Further adjustments may be required.
+{{< /alert >}}
+
- **% CPU utilization:** `1 - avg without (mode,cpu) (rate(node_cpu_seconds_total{mode="idle"}[5m]))`
- **% Memory available:** `((node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) or ((node_memory_MemFree_bytes + node_memory_Buffers_bytes + node_memory_Cached_bytes) / node_memory_MemTotal_bytes)) * 100`
- **Data transmitted:** `rate(node_network_transmit_bytes_total{device!="lo"}[5m])`
diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md
index 7bf05be2d001e6c4ac8767217b11eb11a9a78818..7767d662dce5d8b2869b438f20655af2d13cfc81 100644
--- a/doc/administration/monitoring/prometheus/gitlab_exporter.md
+++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab exporter
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The [GitLab exporter](https://gitlab.com/gitlab-org/ruby/gems/gitlab-exporter) enables you to
measure various GitLab metrics pulled from Redis and the database in Linux package
diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md
index c4c7f8e777cd1a7ec2da2dd77c8a15e10bdf0760..107fae76a9557ce1a365deadf82457b939d7c43b 100644
--- a/doc/administration/monitoring/prometheus/gitlab_metrics.md
+++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Prometheus metrics
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To enable the GitLab Prometheus metrics:
@@ -33,7 +36,11 @@ For enabling and viewing metrics from Sidekiq nodes, see [Sidekiq metrics](#side
## Metrics available
-> - `caller_id` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392622) from `redis_hit_miss_operations_total` and `redis_cache_generation_duration_seconds` in GitLab 15.11.
+{{< history >}}
+
+- `caller_id` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392622) from `redis_hit_miss_operations_total` and `redis_cache_generation_duration_seconds` in GitLab 15.11.
+
+{{< /history >}}
The following metrics are available:
@@ -440,9 +447,12 @@ configuration option in `gitlab.yml`. These metrics are served from the
## Database load balancing metrics
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following metrics are available:
@@ -454,9 +464,12 @@ The following metrics are available:
## Database partitioning metrics
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following metrics are available:
diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md
index 6765e8a6d40b86a7636bc381d1332ff7b7b6aafd..59c9dfde1a72e0336ddde6f316f11e39deb3af72 100644
--- a/doc/administration/monitoring/prometheus/node_exporter.md
+++ b/doc/administration/monitoring/prometheus/node_exporter.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Node exporter
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The [node exporter](https://github.com/prometheus/node_exporter) enables you to measure
various machine resources such as memory, disk and CPU utilization.
diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md
index 3ea958ac277b47b1d5cadaf0ea2777009e5f092c..6086d673d3a82367047ee8681724b401f509c13c 100644
--- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md
+++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: PgBouncer exporter
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The [PgBouncer exporter](https://github.com/prometheus-community/pgbouncer_exporter) enables
you to measure various [PgBouncer](https://www.pgbouncer.org/) metrics.
diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md
index 4872e065821242a70f8255e1db58a8fb254040c7..73fef9ba68183f032a17e31bc03d10824b2c1f6c 100644
--- a/doc/administration/monitoring/prometheus/postgres_exporter.md
+++ b/doc/administration/monitoring/prometheus/postgres_exporter.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: PostgreSQL Server Exporter
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The [PostgreSQL Server Exporter](https://github.com/prometheus-community/postgres_exporter) allows you to export various PostgreSQL metrics.
diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md
index f37970057aaa25d8f37c516bc7ed4d34632db928..706b53b37e9f6613d70801221be7c059d2fc1e6c 100644
--- a/doc/administration/monitoring/prometheus/redis_exporter.md
+++ b/doc/administration/monitoring/prometheus/redis_exporter.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Redis exporter
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The [Redis exporter](https://github.com/oliver006/redis_exporter) enables you to measure
various [Redis](https://redis.io) metrics. For more information on what is exported,
diff --git a/doc/administration/monitoring/prometheus/registry_exporter.md b/doc/administration/monitoring/prometheus/registry_exporter.md
index 57f7e2d58e31145a2f27e592c6233eb1ddb96522..86fbf0103a9a7ae1addce59488a957db790fee99 100644
--- a/doc/administration/monitoring/prometheus/registry_exporter.md
+++ b/doc/administration/monitoring/prometheus/registry_exporter.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Registry exporter
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The Registry exporter allows you to measure various Registry metrics.
To enable it:
diff --git a/doc/administration/monitoring/prometheus/web_exporter.md b/doc/administration/monitoring/prometheus/web_exporter.md
index 397dd973198ec7e303392bd3f5b4efa35fab5afd..84d096538d0f832d938d02ec50977817f85a7258 100644
--- a/doc/administration/monitoring/prometheus/web_exporter.md
+++ b/doc/administration/monitoring/prometheus/web_exporter.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Web exporter (dedicated metrics server)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When [monitoring GitLab with Prometheus](_index.md), GitLab runs various collectors that
sample the application for data related to usage, load and performance. GitLab can then make
@@ -15,10 +18,13 @@ this data available to a Prometheus scraper by running one or more Prometheus ex
A Prometheus exporter is an HTTP server that serializes metric data into a format the
Prometheus scraper understands.
-NOTE:
+{{< alert type="note" >}}
+
This page is about web application metrics.
To export background job metrics, learn how to [configure the Sidekiq metrics server](../../sidekiq/_index.md#configure-the-sidekiq-metrics-server).
+{{< /alert >}}
+
We provide two mechanisms by which web application metrics can be exported:
- Through the main Rails application. This means [Puma](../../operations/puma.md), the application server we use,
@@ -57,7 +63,11 @@ Metrics can now be served and scraped from `localhost:8083/metrics`.
## Enable HTTPS
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364771) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364771) in GitLab 15.2.
+
+{{< /history >}}
To serve metrics via HTTPS instead of HTTP, enable TLS in the exporter settings:
diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md
index 0b2e804d7d2f0999599129f5065d6150ba2c7883..642f02ac20921e2ed35e5b52e404eace4dbea877 100644
--- a/doc/administration/nfs.md
+++ b/doc/administration/nfs.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using NFS with GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
NFS can be used as an alternative for object storage but this isn't typically
recommended for performance reasons.
@@ -99,7 +102,8 @@ To disable NFS server delegation, do the following:
1. Restart the NFS server process. For example, on CentOS run `service nfs restart`.
-NOTE:
+{{< alert type="note" >}}
+
The kernel bug may be fixed in
[more recent kernels with this commit](https://github.com/torvalds/linux/commit/95da1b3a5aded124dd1bda1e3cdb876184813140).
Red Hat Enterprise 7 [shipped a kernel update](https://access.redhat.com/errata/RHSA-2019:2029)
@@ -108,6 +112,8 @@ You may not need to disable NFS server delegation if you know you are using a ve
the Linux kernel that has been fixed. That said, GitLab still encourages instance
administrators to keep NFS server delegation disabled.
+{{< /alert >}}
+
## NFS client
The `nfs-common` provides NFS functionality without installing server components which
diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md
index f4f6854b2c2039c6287a8510f93bdd5ccc64dd24..8d09dda53bdc915c134334829a982e1c35b8b136 100644
--- a/doc/administration/object_storage.md
+++ b/doc/administration/object_storage.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Object storage
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab supports using an object storage service for holding numerous types of data.
It's recommended over NFS and
@@ -52,9 +55,12 @@ Most types of objects, such as CI artifacts, LFS files, and upload attachments
can be saved in object storage by specifying a single credential for object
storage with multiple buckets.
-NOTE:
+{{< alert type="note" >}}
+
For GitLab Helm Charts, see how to [configure the consolidated form](https://docs.gitlab.com/charts/charts/globals.html#consolidated-object-storage).
+{{< /alert >}}
+
Configuring the object storage using the consolidated form has a number of advantages:
- It can simplify your GitLab configuration since the connection details are shared
@@ -124,9 +130,9 @@ Within each object type, three parameters can be defined:
| Setting | Required? | Description |
|------------------|------------------------|-------------------------------------|
-| `bucket` | **{check-circle}** Yes\* | Bucket name for the object type. Not required if `enabled` is set to `false`. |
-| `enabled` | **{dotted-circle}** No | Overrides the [common parameter](#configure-the-common-parameters). |
-| `proxy_download` | **{dotted-circle}** No | Overrides the [common parameter](#configure-the-common-parameters). |
+| `bucket` | {{< icon name="check-circle" >}} Yes\* | Bucket name for the object type. Not required if `enabled` is set to `false`. |
+| `enabled` | {{< icon name="dotted-circle" >}} No | Overrides the [common parameter](#configure-the-common-parameters). |
+| `proxy_download` | {{< icon name="dotted-circle" >}} No | Overrides the [common parameter](#configure-the-common-parameters). |
For an example, see how to [use the consolidated form and Amazon S3](#full-example-using-the-consolidated-form-and-amazon-s3).
@@ -156,29 +162,32 @@ except for the storage types not supported by the consolidated form. When workin
The use of [encrypted S3 buckets](#encrypted-s3-buckets) with non-consolidated form is not supported.
You may get [ETag mismatch errors](#etag-mismatch) if you use it.
-NOTE:
+{{< alert type="note" >}}
+
For the storage-specific form,
[direct upload may become the default](https://gitlab.com/gitlab-org/gitlab/-/issues/27331)
because it does not require a shared folder.
+{{< /alert >}}
+
For storage types not
supported by the consolidated form, refer to the following guides:
| Object storage type | Supported by consolidated form? |
|---------------------|------------------------------------------|
-| [Backups](backup_restore/backup_gitlab.md#upload-backups-to-a-remote-cloud-storage) | **{dotted-circle}** No |
-| [Container registry](packages/container_registry.md#use-object-storage) (optional feature) | **{dotted-circle}** No |
-| [Mattermost](https://docs.mattermost.com/configure/file-storage-configuration-settings.html)| **{dotted-circle}** No |
-| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | **{dotted-circle}** No |
-| [Secure Files](cicd/secure_files.md#using-object-storage) | **{check-circle}** Yes |
-| [Job artifacts](cicd/job_artifacts.md#using-object-storage) including archived job logs | **{check-circle}** Yes |
-| [LFS objects](lfs/_index.md#storing-lfs-objects-in-remote-object-storage) | **{check-circle}** Yes |
-| [Uploads](uploads.md#using-object-storage) | **{check-circle}** Yes |
-| [Merge request diffs](merge_request_diffs.md#using-object-storage) | **{check-circle}** Yes |
-| [Packages](packages/_index.md#use-object-storage) (optional feature) | **{check-circle}** Yes |
-| [Dependency Proxy](packages/dependency_proxy.md#using-object-storage) (optional feature) | **{check-circle}** Yes |
-| [Terraform state files](terraform_state.md#using-object-storage) | **{check-circle}** Yes |
-| [Pages content](pages/_index.md#object-storage-settings) | **{check-circle}** Yes |
+| [Backups](backup_restore/backup_gitlab.md#upload-backups-to-a-remote-cloud-storage) | {{< icon name="dotted-circle" >}} No |
+| [Container registry](packages/container_registry.md#use-object-storage) (optional feature) | {{< icon name="dotted-circle" >}} No |
+| [Mattermost](https://docs.mattermost.com/configure/file-storage-configuration-settings.html)| {{< icon name="dotted-circle" >}} No |
+| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | {{< icon name="dotted-circle" >}} No |
+| [Secure Files](cicd/secure_files.md#using-object-storage) | {{< icon name="check-circle" >}} Yes |
+| [Job artifacts](cicd/job_artifacts.md#using-object-storage) including archived job logs | {{< icon name="check-circle" >}} Yes |
+| [LFS objects](lfs/_index.md#storing-lfs-objects-in-remote-object-storage) | {{< icon name="check-circle" >}} Yes |
+| [Uploads](uploads.md#using-object-storage) | {{< icon name="check-circle" >}} Yes |
+| [Merge request diffs](merge_request_diffs.md#using-object-storage) | {{< icon name="check-circle" >}} Yes |
+| [Packages](packages/_index.md#use-object-storage) (optional feature) | {{< icon name="check-circle" >}} Yes |
+| [Dependency Proxy](packages/dependency_proxy.md#using-object-storage) (optional feature) | {{< icon name="check-circle" >}} Yes |
+| [Terraform state files](terraform_state.md#using-object-storage) | {{< icon name="check-circle" >}} Yes |
+| [Pages content](pages/_index.md#object-storage-settings) | {{< icon name="check-circle" >}} Yes |
## Configure the connection settings
@@ -317,9 +326,12 @@ It uses the first of these settings that has a value.
The service account must have permission to access the bucket. For more information,
see the [Cloud Storage authentication documentation](https://cloud.google.com/storage/docs/authentication).
-NOTE:
+{{< alert type="note" >}}
+
To use bucket encryption with [customer-managed encryption keys](https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys), use the [consolidated form](#configure-a-single-storage-connection-for-all-object-types-consolidated-form).
+{{< /alert >}}
+
#### GCS example
For Linux Package installations, this is an example of the `connection` setting in the consolidated form:
@@ -378,9 +390,9 @@ The following are the valid connection parameters for Azure. For more informatio
| `azure_storage_access_key` | Storage account access key used to access the container. This is typically a secret, 512-bit encryption key encoded in base64. This is optional for [Azure workload and managed identities](#azure-workload-and-managed-identities). | `czV2OHkvQj9FKEgrTWJRZVRoV21ZcTN0Nnc5eiRDJkYpSkBOY1JmVWpYbjJy\nNHU3eCFBJUQqRy1LYVBkU2dWaw==\n` |
| `azure_storage_domain` | Domain name used to contact the Azure Blob Storage API (optional). Defaults to `blob.core.windows.net`. Set this if you are using Azure China, Azure Germany, Azure US Government, or some other custom Azure domain. | `blob.core.windows.net` |
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting
the values you want:
@@ -419,7 +431,9 @@ The following are the valid connection parameters for Azure. For more informatio
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `object_storage.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#connection):
@@ -489,7 +503,9 @@ The following are the valid connection parameters for Azure. For more informatio
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -535,7 +551,9 @@ The following are the valid connection parameters for Azure. For more informatio
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
For self-compiled installations, Workhorse also needs to be configured with Azure
credentials. This isn't needed in Linux package installations because the Workhorse
@@ -599,11 +617,17 @@ settings are populated from the previous settings.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Azure workload and managed identities
-> - [Introduced in GitLab 17.9](https://gitlab.com/gitlab-org/gitlab/-/issues/242245)
+{{< history >}}
+
+- [Introduced in GitLab 17.9](https://gitlab.com/gitlab-org/gitlab/-/issues/242245)
+
+{{< /history >}}
To use [Azure workload identities](https://azure.github.io/azure-workload-identity/docs/) or [managed identities](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/), omit
`azure_storage_access_key` from the configuration. When
@@ -619,10 +643,13 @@ assigned to it.
### Storj Gateway (SJ)
-NOTE:
+{{< alert type="note" >}}
+
The Storj Gateway [does not support](https://github.com/storj/gateway-st/blob/4b74c3b92c63b5de7409378b0d1ebd029db9337d/docs/s3-compatibility.md) multi-threaded copying (see `UploadPartCopy` in the table).
While an implementation [is planned](https://github.com/storj/roadmap/issues/40), you must [disable multi-threaded copying](#multi-threaded-copying) until completion.
+{{< /alert >}}
+
The [Storj Network](https://www.storj.io/) provides an S3-compatible API gateway. Use the following configuration example:
```ruby
@@ -643,9 +670,12 @@ For more information, see [issue #4419](https://gitlab.com/gitlab-org/gitlab/-/i
### Hitachi Vantara HCP
-NOTE:
+{{< alert type="note" >}}
+
Connections to HCP may return an error stating `SignatureDoesNotMatch - The request signature we calculated does not match the signature you provided. Check your HCP Secret Access key and signing method.` In these cases, set the `endpoint` to the URL of the tenant instead of the namespace, and ensure bucket paths are configured as `<namespace_name>/<bucket_name>`.
+{{< /alert >}}
+
[HCP](https://docs.hitachivantara.com/r/en-us/content-platform-for-cloud-scale/2.6.x/mk-hcpcs008/getting-started/introducing-hcp-for-cloud-scale/support-for-the-amazon-s3-api) provides an S3-compatible API. Use the following configuration example:
```ruby
@@ -668,9 +698,9 @@ gitlab_rails['object_store']['objects']['artifacts']['bucket'] = '<namespace_nam
The following example uses AWS S3 to enable object storage for all supported services:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting
the values you want:
@@ -718,7 +748,9 @@ The following example uses AWS S3 to enable object storage for all supported ser
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `object_storage.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#connection):
@@ -789,7 +821,9 @@ The following example uses AWS S3 to enable object storage for all supported ser
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -841,7 +875,9 @@ The following example uses AWS S3 to enable object storage for all supported ser
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
@@ -918,7 +954,9 @@ The following example uses AWS S3 to enable object storage for all supported ser
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Migrate to object storage
@@ -1163,7 +1201,11 @@ When the consolidated form is:
#### Google Cloud Storage encryption
-> - [Introduced in GitLab 16.11](https://gitlab.com/gitlab-org/gitlab/-/issues/441782).
+{{< history >}}
+
+- [Introduced in GitLab 16.11](https://gitlab.com/gitlab-org/gitlab/-/issues/441782).
+
+{{< /history >}}
ETag mismatch errors occur also in Google Cloud Storage (GCS) when enabling [data encryption with customer-managed encryption keys (CMEK)](https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys).
diff --git a/doc/administration/operations/_index.md b/doc/administration/operations/_index.md
index 360f9f846b729be35e28e706a45e08205cef5ebf..6f874b613a174e347fb42ffc14b6785bd6ea15fd 100644
--- a/doc/administration/operations/_index.md
+++ b/doc/administration/operations/_index.md
@@ -1,14 +1,17 @@
---
stage: Systems
group: Distribution
-description: Backup and restore, move repos, maintenance tasks.
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
+description: Backup and restore, move repos, maintenance tasks.
title: Maintain GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Keep your GitLab instance up and running.
diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md
index de79f8a1b08135568e6bbbfe5449540b66d699d3..6bf21f2f04a704e022d9c3e25d5d675d14a801cc 100644
--- a/doc/administration/operations/fast_ssh_key_lookup.md
+++ b/doc/administration/operations/fast_ssh_key_lookup.md
@@ -2,18 +2,24 @@
stage: Create
group: Source Code
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
-description: "Configure a faster SSH authorization method for GitLab instances with many users."
+description: Configure a faster SSH authorization method for GitLab instances with many users.
title: Fast lookup of SSH keys
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
For standard (non-deploy key) users, you can also use [SSH certificates](ssh_certificates.md).
They are faster than database lookups but are not a drop-in replacement for the `authorized_keys` file.
+{{< /alert >}}
+
When the number of users grows, SSH operations become slow because OpenSSH performs a
linear search through the `authorized_keys` file to authenticate users.
This process requires significant time and disk I/O, which delays users attempting to
@@ -26,9 +32,12 @@ SSH keys. It is faster because the lookup is indexed in the GitLab database.
## Fast lookup is required for Geo
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Unlike [Cloud Native GitLab](https://docs.gitlab.com/charts/), by default Linux package installations
manage an `authorized_keys` file that is located in the
diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md
index 7211df4f37c190a24ea246a9b73a5844adb20664..6ddacc8bc65e7ce92dde9afe08d7295f0bead626 100644
--- a/doc/administration/operations/filesystem_benchmarking.md
+++ b/doc/administration/operations/filesystem_benchmarking.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: File system performance benchmarking
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
File system performance has a big impact on overall GitLab performance,
especially for actions that read or write to Git repositories. This information
@@ -74,12 +77,15 @@ operations per second.
### Simple benchmarking
-NOTE:
+{{< alert type="note" >}}
+
This test is naive but can be used if `fio` is not
available on the system. It's possible to receive good results on this
test but still have poor performance due to read speed and various other
factors.
+{{< /alert >}}
+
The following one-line commands provide a quick benchmark for file system write and read
performance. This writes 1,000 small files to the directory in which it is
executed, and then reads the same 1,000 files.
diff --git a/doc/administration/operations/gitlab_sshd.md b/doc/administration/operations/gitlab_sshd.md
index cfcad1494e974192305cb2561589e725483f9216..37a1f9bb84bbde3476d6907fcaae9f3708d4da18 100644
--- a/doc/administration/operations/gitlab_sshd.md
+++ b/doc/administration/operations/gitlab_sshd.md
@@ -2,16 +2,23 @@
stage: Create
group: Source Code
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
-description: "Configure `gitlab-sshd`, a lightweight alternative to OpenSSH, for your GitLab instance."
+description: Configure `gitlab-sshd`, a lightweight alternative to OpenSSH, for your GitLab instance.
title: '`gitlab-sshd`'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2540) for use with Cloud Native GitLab in GitLab 15.1.
-> - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5937) for use with Linux packages in GitLab 15.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2540) for use with Cloud Native GitLab in GitLab 15.1.
+- [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5937) for use with Linux packages in GitLab 15.9.
+
+{{< /history >}}
`gitlab-sshd` is [a standalone SSH server](https://gitlab.com/gitlab-org/gitlab-shell/-/tree/main/internal/sshd)
written in Go. It is provided as a part of the `gitlab-shell` package. It has a lower memory
@@ -41,9 +48,9 @@ If you are considering switching from OpenSSH to `gitlab-sshd`, consider these c
To use `gitlab-sshd`:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
The following instructions enable `gitlab-sshd` on a different port than OpenSSH:
@@ -77,7 +84,9 @@ differ from the OpenSSH host keys. Consider disabling host key
generation and copy the existing OpenSSH host keys into
`/var/opt/gitlab/gitlab-sshd` if this is an issue.
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
The following instructions switch OpenSSH in favor of `gitlab-sshd`:
@@ -100,7 +109,9 @@ By default, `gitlab-sshd` listens for:
You can [configure different ports in the Helm chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/#configuration).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## PROXY protocol support
@@ -109,9 +120,9 @@ address of the proxy instead of the actual IP address of the client. `gitlab-ssh
supports the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to
obtain the real IP address.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
To enable the PROXY protocol:
@@ -132,7 +143,9 @@ To enable the PROXY protocol:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Set the [`gitlab.gitlab-shell.config` options](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/#installation-command-line-options). For example:
@@ -146,4 +159,6 @@ To enable the PROXY protocol:
1. Perform a Helm upgrade.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md
index 9122dba754c6dbdad8fbe9d587815e7672453dd7..30667b982a5982c155e8c1822fee439c8a9cb801 100644
--- a/doc/administration/operations/moving_repositories.md
+++ b/doc/administration/operations/moving_repositories.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Moving repositories managed by GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can move all repositories managed by GitLab to another file system or another server.
@@ -125,9 +128,12 @@ To move all snippets by using the API:
#### Move all groups
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To move all groups by using the API:
@@ -175,10 +181,13 @@ We look at three scenarios:
- The target directory contains an outdated copy of the repositories.
- How to deal with thousands of repositories.
-WARNING:
+{{< alert type="warning" >}}
+
Each of the approaches we list can or does overwrite data in the target directory
`/mnt/gitlab/repositories`. Do not mix up the source and the target.
+{{< /alert >}}
+
### Recommended approach in all cases
For either Gitaly or Gitaly Cluster targets, the GitLab [backup and restore capability](../backup_restore/_index.md)
@@ -223,10 +232,13 @@ If you want to compress the data before it goes over the network
### The target directory contains an outdated copy of the repositories: use `rsync`
-WARNING:
+{{< alert type="warning" >}}
+
Using `rsync` to migrate Git data can cause data loss and repository corruption.
[These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422).
+{{< /alert >}}
+
If the target directory already contains a partial or outdated copy of the repositories it may be wasteful to copy all
the data again with `tar`. In this scenario it is better to use `rsync` for Gitaly targets (use
[recommended approach](#recommended-approach-in-all-cases) for Gitaly Cluster targets).
@@ -244,10 +256,13 @@ If you want to see progress, replace `-a` with `-av`.
#### Single `rsync` to another server
-WARNING:
+{{< alert type="warning" >}}
+
Using `rsync` to migrate Git data can cause data loss and repository corruption.
[These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422).
+{{< /alert >}}
+
For Gitaly targets (use [recommended approach](#recommended-approach-in-all-cases) for Gitaly Cluster targets), if the
`git` user on your source system has SSH access to the target server you can send the repositories over the network with
`rsync`.
diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md
index 88e12413cf2c00912faca1390aed8a5c1f056536..e5d3fca05007079cf1cf2f48b3c9198bfb58fd2c 100644
--- a/doc/administration/operations/puma.md
+++ b/doc/administration/operations/puma.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure the bundled Puma instance of the GitLab package
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Puma is a fast, multi-threaded, and highly concurrent HTTP 1.1 server for
Ruby applications. It runs the core Rails application that provides the user-facing
@@ -80,9 +83,12 @@ RSS limit set through `per_worker_max_memory_mb`.
The default Puma [timeout is 60 seconds](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/rack_timeout.rb).
-NOTE:
+{{< alert type="note" >}}
+
The `puma['worker_timeout']` setting does not set the maximum request duration.
+{{< /alert >}}
+
To change the worker timeout to 600 seconds:
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -101,12 +107,15 @@ To change the worker timeout to 600 seconds:
## Disable Puma clustered mode in memory-constrained environments
-WARNING:
+{{< alert type="warning" >}}
+
This feature is an [experiment](../../policy/development_stages_support.md#experiment) and subject to change without notice. This feature
is not ready for production use. If you want to use this feature, you should test
outside of production first. See the [known issues](#puma-single-mode-known-issues)
for additional details.
+{{< /alert >}}
+
In a memory-constrained environment with less than 4 GB of RAM available, consider disabling Puma
[clustered mode](https://github.com/puma/puma#clustered-mode).
@@ -152,11 +161,14 @@ steps below:
1. Generate an SSL certificate key-pair for the address where Puma will
listen. For the example below, this is `127.0.0.1`.
- NOTE:
- If using a self-signed certificate from a custom Certificate Authority (CA),
+ {{< alert type="note" >}}
+
+If using a self-signed certificate from a custom Certificate Authority (CA),
follow [the documentation](https://docs.gitlab.com/omnibus/settings/ssl/#install-custom-public-certificates)
to make them trusted by other GitLab components.
+ {{< /alert >}}
+
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
@@ -175,7 +187,8 @@ steps below:
sudo gitlab-ctl reconfigure
```
-NOTE:
+{{< alert type="note" >}}
+
In addition to the Unix socket, Puma also listens over HTTP on port 8080 for
providing metrics to be scraped by Prometheus. It is not currently possible to
make Prometheus scrape them over HTTPS, and support for it is being discussed
@@ -183,9 +196,15 @@ make Prometheus scrape them over HTTPS, and support for it is being discussed
Hence, it is not technically possible to turn off this HTTP listener without
losing Prometheus metrics.
+{{< /alert >}}
+
### Using an encrypted SSL key
-> - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7799) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7799) in GitLab 16.1.
+
+{{< /history >}}
Puma supports the use of an encrypted private SSL key, which can be
decrypted at runtime. The following instructions illustrate how to
@@ -249,10 +268,13 @@ configure this:
## Switch from Unicorn to Puma
-NOTE:
+{{< alert type="note" >}}
+
For Helm-based deployments, see the
[`webservice` chart documentation](https://docs.gitlab.com/charts/charts/gitlab/webservice/).
+{{< /alert >}}
+
Puma is the default web server and Unicorn is no longer supported.
Puma has a multi-thread architecture that uses less memory than a multi-process
diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md
index 4d0aa0b45a99ea771b0652b7846ee21ac0c2f921..f80fa9f436c43ba3cded82dcbfc768f3f7d3758c 100644
--- a/doc/administration/operations/rails_console.md
+++ b/doc/administration/operations/rails_console.md
@@ -5,21 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rails console
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
At the heart of GitLab is a web application
[built using the Ruby on Rails framework](https://about.gitlab.com/blog/2018/10/29/why-we-use-rails-to-build-gitlab/).
The [Rails console](https://guides.rubyonrails.org/command_line.html#rails-console)
provides a way to interact with your GitLab instance from the command line, and also grants access to the amazing tools built right into Rails.
-WARNING:
+{{< alert type="warning" >}}
+
The Rails console interacts directly with GitLab. In many cases,
there are no handrails to prevent you from permanently modifying, corrupting
or destroying production data. If you would like to explore the Rails console
with no consequences, you are strongly advised to do so in a test environment.
+{{< /alert >}}
+
The Rails console is for GitLab system administrators who are troubleshooting
a problem or need to retrieve some data that can only be done through direct
access of the GitLab application. Basic knowledge of Ruby is needed (try
@@ -30,27 +36,33 @@ Rails experience is useful but not required.
The process for starting a Rails console session depends on the type of GitLab installation.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rails console
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
docker exec -it <container-id> gitlab-rails console
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
sudo -u git -H bundle exec rails console -e production
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
```shell
# find the pod
@@ -60,7 +72,9 @@ kubectl get pods --namespace <namespace> -lapp=toolbox
kubectl exec -it -c toolbox <toolbox-pod-name> -- gitlab-rails console
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To exit the console, type: `quit`.
@@ -720,9 +734,12 @@ ApplicationSetting.current
### Open object in `irb`
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
Sometimes it is easier to go through a method if you are in the context of the object. You can shim into the namespace of `Object` to let you open `irb` in the context of any object:
```ruby
diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md
index 938d3a2a76867ebb3c21fe4c75cbc3d472f5e097..f9baeaf4919f4dd5fc8cffdcce2528a353f6a696 100644
--- a/doc/administration/operations/ssh_certificates.md
+++ b/doc/administration/operations/ssh_certificates.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User lookup via OpenSSH's AuthorizedPrincipalsCommand
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The default SSH authentication for GitLab requires users to upload their SSH
public keys before they can use the SSH transport.
@@ -19,10 +22,13 @@ user, including ones that expire 24 hours after issuing.
In such setups some external automated process is needed to constantly
upload the new keys to GitLab.
-WARNING:
+{{< alert type="warning" >}}
+
OpenSSH version 6.9+ is required because `AuthorizedKeysCommand` must be
able to accept a fingerprint. Check the version of OpenSSH on your server.
+{{< /alert >}}
+
## Why use OpenSSH certificates?
By using OpenSSH certificates all the information about what user on
diff --git a/doc/administration/package_information/_index.md b/doc/administration/package_information/_index.md
index 5d2b4092ae7be65463147a7b8adf91e1c38436c6..11484c634f8db27875aad63498e02d8e81bf7f0b 100644
--- a/doc/administration/package_information/_index.md
+++ b/doc/administration/package_information/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Package information
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The Linux package is bundled with all dependencies required for GitLab
to function correctly. More details can be found
@@ -71,11 +74,14 @@ To view a diff between your configuration file and the latest version, run:
sudo gitlab-ctl diff-config
```
-WARNING:
+{{< alert type="warning" >}}
+
If you are pasting the output of this command into your
`/etc/gitlab/gitlab.rb` configuration file, omit any leading `+` and `-`
characters on each line.
+{{< /alert >}}
+
## Init system detection
The Linux package attempts to query the underlying system to
diff --git a/doc/administration/package_information/defaults.md b/doc/administration/package_information/defaults.md
index 259b9768b4148267639e579acbd3c0552e9d653e..7f687bd33282210462f6725137f26c49c6e5dc37 100644
--- a/doc/administration/package_information/defaults.md
+++ b/doc/administration/package_information/defaults.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Package defaults
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Unless configuration is specified in the `/etc/gitlab/gitlab.rb` file,
the package assumes the defaults as noted below.
@@ -73,9 +76,12 @@ If you are using NFS (Network File System), files are carried
over a network which requires, based on implementation, ports `111` and
`2049` to be open.
-NOTE:
+{{< alert type="note" >}}
+
In some cases, the GitLab Registry is automatically enabled by default. See [our documentation](../packages/container_registry.md) for more details.
+{{< /alert >}}
+
[^Consul-notes]: If using additional Consul functionality, more ports may need to be opened. See the [official documentation](https://developer.hashicorp.com/consul/docs/install/ports#ports-table) for the list.
[^Sidekiq-health]: If Sidekiq health check settings are not set, they default to the Sidekiq metrics exporter settings. This default is deprecated and is set to be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/347509).
diff --git a/doc/administration/package_information/deprecation_policy.md b/doc/administration/package_information/deprecation_policy.md
index 1655576d9f96670809a8545f5605149afb2b0c7e..25058ccd5d5d08a5bf6727c6767b91eff7c61c55 100644
--- a/doc/administration/package_information/deprecation_policy.md
+++ b/doc/administration/package_information/deprecation_policy.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Linux package deprecation policy
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The Linux packages come with number of different libraries and services which offers users plethora of configuration options.
diff --git a/doc/administration/package_information/licensing.md b/doc/administration/package_information/licensing.md
index 713e5b828f46a8f77142fe9245601cbcc00804c6..3cdf8b36aed2ed992261128a6f46be7ea339172f 100644
--- a/doc/administration/package_information/licensing.md
+++ b/doc/administration/package_information/licensing.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Package Licensing
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
## License
diff --git a/doc/administration/package_information/omnibus_packages.md b/doc/administration/package_information/omnibus_packages.md
index 68ccee5b70aa51e0649aee2de9c524eb176de8d0..f2c51f85bfd2cb494906443d88cfdaa18cce993b 100644
--- a/doc/administration/package_information/omnibus_packages.md
+++ b/doc/administration/package_information/omnibus_packages.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Packages and images from the Linux package
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Below you can find some basic information on why GitLab provides packages and
a Docker image that come with bundled dependencies.
diff --git a/doc/administration/package_information/postgresql_versions.md b/doc/administration/package_information/postgresql_versions.md
index 08cc9ae5a9ca4242b0fcaf938aa62a86a035b064..f6f489ff621651483d6a2a9797c8324fe6ebba19 100644
--- a/doc/administration/package_information/postgresql_versions.md
+++ b/doc/administration/package_information/postgresql_versions.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: PostgreSQL versions shipped with the Linux package
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This table lists only GitLab versions where a significant change happened in the
package regarding PostgreSQL versions, not all.
+{{< /alert >}}
+
Usually, PostgreSQL versions change with major or minor GitLab releases. However, patch versions
of the Linux package sometimes update the patch level of PostgreSQL. We've established a
[yearly cadence for PostgreSQL upgrades](https://handbook.gitlab.com/handbook/engineering/infrastructure-platforms/data-access/database-framework/postgresql-upgrade-cadence/)
diff --git a/doc/administration/package_information/signed_packages.md b/doc/administration/package_information/signed_packages.md
index 73fcdc74f106309f73a446e964875459300a29ec..e1938d1fc96a33c684df781e58b453fe8ea479a6 100644
--- a/doc/administration/package_information/signed_packages.md
+++ b/doc/administration/package_information/signed_packages.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Package Signatures
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Linux packages produced by GitLab are created using [Omnibus](https://github.com/chef/omnibus), for which GitLab
has added DEB signing using `debsigs` in [our own fork](https://gitlab.com/gitlab-org/omnibus).
diff --git a/doc/administration/package_information/supported_os.md b/doc/administration/package_information/supported_os.md
index 5d1c08a21d4174326f108dd6ada11e11f22b31fb..bdcba44fc2260c78c1eab871ba4a296fd68e7745 100644
--- a/doc/administration/package_information/supported_os.md
+++ b/doc/administration/package_information/supported_os.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Supported operating systems
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab officially supports long term support (LTS) versions of operating systems. Some operating systems, such as Ubuntu,
have a clear distinction between LTS and non-LTS versions. However, there are other operating systems, openSUSE for
@@ -16,10 +19,13 @@ example, that don't follow the LTS concept.
To avoid confusion, all the operating systems supported by GitLab are listed on the
[installation page](https://about.gitlab.com/install/).
-NOTE:
+{{< alert type="note" >}}
+
`amd64` and `x86_64` refer to the same 64-bit architecture. The names `arm64` and `aarch64` are also interchangeable
and refer to the same architecture.
+{{< /alert >}}
+
## AlmaLinux
These versions of AlmaLinux are supported.
@@ -122,9 +128,12 @@ GitLab provides arm64/aarch64 packages for some supported operating systems.
You can see if your operating system architecture is supported in the table
above.
-WARNING:
+{{< alert type="warning" >}}
+
[Known issues](https://gitlab.com/groups/gitlab-org/-/epics/4397) exist for running GitLab on ARM.
+{{< /alert >}}
+
## OS versions that are no longer supported
GitLab provides Linux packages for operating systems only until their
@@ -162,8 +171,11 @@ release for them can be found below:
| Ubuntu 16.04 | [April 2021](https://ubuntu.com/info/release-end-of-life) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_13.12&dist=ubuntu%2Fxenial) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_13.12&dist=ubuntu%2Fxenial) 13.12 |
| Ubuntu 18.04 | [June 2023](https://ubuntu.com/info/release-end-of-life) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_16.11&dist=ubuntu%2Fbionic) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=ggitlab-ee_16.11&dist=ubuntu%2Fbionic) 16.11 |
-NOTE:
+{{< alert type="note" >}}
+
An exception to this deprecation policy is when we are unable to provide
packages for the next version of the operating system. The most common reason
for this our package repository provider, PackageCloud, not supporting newer
versions and hence we can't upload packages to it.
+
+{{< /alert >}}
diff --git a/doc/administration/packages/_index.md b/doc/administration/packages/_index.md
index af35ddab0e0fe8ba0b33989dd4c38e7e332512f3..3fb49b19b561154f1901b805ee360e913385ecbb 100644
--- a/doc/administration/packages/_index.md
+++ b/doc/administration/packages/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab package registry administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To use GitLab as a private repository for a variety of common package managers, use the package registry.
You can build and publish
@@ -64,9 +67,9 @@ can define specific rate limits for the Packages API. For more details, see [pac
The package registry is enabled by default. To disable it:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -81,7 +84,9 @@ The package registry is enabled by default. To disable it:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -104,7 +109,9 @@ The package registry is enabled by default. To disable it:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -123,7 +130,9 @@ The package registry is enabled by default. To disable it:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -143,7 +152,9 @@ The package registry is enabled by default. To disable it:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Change the storage path
@@ -160,9 +171,9 @@ installation:
To change the local storage path:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -176,7 +187,9 @@ To change the local storage path:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -197,7 +210,9 @@ To change the local storage path:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
If you already had packages stored in the old storage path, move everything
from the old to the new location to ensure existing packages stay accessible:
@@ -229,46 +244,56 @@ The processing is done in a background worker and requires **no downtime**.
1. Migrate the packages.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake "gitlab:packages:migrate"
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:packages:migrate
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Track the progress and verify that all packages migrated successfully using
the PostgreSQL console.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus) 14.1 and earlier
+ {{< tab title="Linux package (Omnibus) 14.1 and earlier" >}}
```shell
sudo gitlab-rails dbconsole
```
- :::TabTitle Linux package (Omnibus) 14.2 and later
+ {{< /tab >}}
+
+ {{< tab title="Linux package (Omnibus) 14.2 and later" >}}
```shell
sudo gitlab-rails dbconsole --database main
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
RAILS_ENV=production sudo -u git -H psql -d gitlabhq_production
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Verify that all packages migrated to object storage with the following SQL
query. The number of `objectstg` should be the same as `total`:
@@ -283,18 +308,22 @@ The processing is done in a background worker and requires **no downtime**.
1. Finally, verify that there are no files on disk in the `packages` directory:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
sudo find /var/opt/gitlab/gitlab-rails/shared/packages -type f | grep -v tmp | wc -l
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo -u git find /home/git/gitlab/shared/packages -type f | grep -v tmp | wc -l
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md
index f981a53652758bfede9b42c67ce3dc08d6f1c378..538a72ac45d65efd455677678c19b38bac65113c 100644
--- a/doc/administration/packages/container_registry.md
+++ b/doc/administration/packages/container_registry.md
@@ -5,16 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab container registry administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
The [next-generation container registry](container_registry_metadata_database.md)
is now available for upgrade on GitLab Self-Managed instances.
This upgraded registry supports online garbage collection, and has significant performance
and reliability improvements.
+{{< /alert >}}
+
With the GitLab container registry, every project can have its
own space to store Docker images.
@@ -107,9 +113,12 @@ auth:
rootcertbundle: /root/certs/certbundle
```
-WARNING:
+{{< alert type="warning" >}}
+
If `auth` is not set up, users can pull Docker images without authentication.
+{{< /alert >}}
+
## Container registry domain configuration
You can configure the Registry's external domain in either of these ways:
@@ -139,14 +148,17 @@ to configure the container registry:
Ensure you choose a port different than the one that Registry listens to (`5000` by default),
otherwise conflicts occur.
-NOTE:
+{{< alert type="note" >}}
+
Host and container firewall rules must be configured to allow traffic in through the port listed
under the `registry_external_url` line, rather than the port listed under
`gitlab_rails['registry_port']` (default `5000`).
-::Tabs
+{{< /alert >}}
+
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Your `/etc/gitlab/gitlab.rb` should contain the Registry URL as well as the
path to the existing TLS certificate and key used by GitLab:
@@ -191,7 +203,9 @@ registry_nginx['redirect_http_to_https'] = true
registry_nginx['listen_port'] = 5678
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
configure it with the following settings:
@@ -206,7 +220,9 @@ registry_nginx['listen_port'] = 5678
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
Users should now be able to sign in to the container registry with their GitLab
credentials using:
@@ -229,9 +245,9 @@ generated by Let's Encrypt are also [supported in Linux package installations](h
Let's assume that you want the container registry to be accessible at
`https://registry.gitlab.example.com`.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Place your TLS certificate and key in
`/etc/gitlab/ssl/registry.gitlab.example.com.crt` and
@@ -261,7 +277,9 @@ registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
configure it with the following settings:
@@ -275,7 +293,9 @@ registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
Users should now be able to sign in to the container registry using their GitLab
credentials:
@@ -290,9 +310,9 @@ When you disable the Registry by following these steps, you do not
remove any existing Docker images. Docker image removal is handled by the
Registry application itself.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Open `/etc/gitlab/gitlab.rb` and set `registry['enable']` to `false`:
@@ -302,7 +322,9 @@ Registry application itself.
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
set `enabled` to `false`:
@@ -314,7 +336,9 @@ Registry application itself.
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Disable container registry for new projects site-wide
@@ -322,9 +346,9 @@ If the container registry is enabled, then it should be available on all new
projects. To disable this function and let the owners of a project to enable
the container registry by themselves, follow the steps below.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -334,7 +358,9 @@ the container registry by themselves, follow the steps below.
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Open `/home/git/gitlab/config/gitlab.yml`, find the `default_projects_features`
entry and configure it so that `container_registry` is set to `false`:
@@ -352,7 +378,9 @@ the container registry by themselves, follow the steps below.
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Increase token duration
@@ -367,7 +395,8 @@ To increase the token duration:
## Configure storage for the container registry
-NOTE:
+{{< alert type="note" >}}
+
For storage backends that support it, you can use object versioning to preserve, retrieve, and
restore the non-current versions of every object stored in your buckets. However, this may result in
higher storage usage and costs. Due to how the registry operates, image uploads are first stored in
@@ -377,9 +406,14 @@ these deleted temporary upload artifacts are kept as non-current versions, there
storage bucket size. To ensure that non-current versions are deleted after a given amount of time,
you should configure an object lifecycle policy with your storage provider.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
Do not directly modify the files or objects stored by the container registry. Anything other than the registry writing or deleting these entries can lead to instance-wide data consistency and instability issues from which recovery may not be possible.
+{{< /alert >}}
+
You can configure the container registry to use various storage backends by
configuring a storage driver. By default the GitLab container registry
is configured to use the [file system driver](#use-file-system)
@@ -411,9 +445,9 @@ This path is accessible to:
All GitLab, Registry, and web server users must
have access to this directory.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
The default location where images are stored in Linux package installations is
`/var/opt/gitlab/gitlab-rails/shared/registry`. To change it:
@@ -426,7 +460,9 @@ The default location where images are stored in Linux package installations is
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
The default location where images are stored in self-compiled installations is
`/home/git/gitlab/shared/registry`. To change it:
@@ -441,7 +477,9 @@ The default location where images are stored in self-compiled installations is
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Use object storage
@@ -450,11 +488,14 @@ driver for the container registry.
[Read more about using object storage with GitLab](../object_storage.md).
-WARNING:
+{{< alert type="warning" >}}
+
GitLab does not back up Docker images that are not stored on the
file system. Enable backups with your object storage provider if
desired.
+{{< /alert >}}
+
#### Configure `s3` and `gcs` storage drivers for Linux package installations
The following configuration steps are for the `s3` and `gcs` storage drivers. Other [storage drivers](#configure-storage-for-the-container-registry) are supported.
@@ -573,12 +614,15 @@ storage:
#### Migrate to object storage without downtime
-WARNING:
+{{< alert type="warning" >}}
+
Using [AWS DataSync](https://aws.amazon.com/datasync/)
to copy the registry data to or between S3 buckets creates invalid metadata objects in the bucket.
For additional details, see [Tags with an empty name](container_registry_troubleshooting.md#tags-with-an-empty-name).
To move data to and between S3 buckets, the AWS CLI `sync` operation is recommended.
+{{< /alert >}}
+
To migrate storage without stopping the container registry, set the container registry
to read-only mode. On large instances, this may require the container registry
to be in read-only mode for a while. During this time,
@@ -606,10 +650,13 @@ you can pull from the container registry, but you cannot push.
sudo aws --endpoint-url https://your-object-storage-backend.com s3 sync registry s3://mybucket
```
- NOTE:
- If you have a lot of data, you may be able to improve performance by
+ {{< alert type="note" >}}
+
+If you have a lot of data, you may be able to improve performance by
[running parallel sync operations](https://repost.aws/knowledge-center/s3-improve-transfer-sync-command).
+ {{< /alert >}}
+
1. To perform the final data sync,
[put the container registry in `read-only` mode](#performing-garbage-collection-without-downtime) and
[reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
@@ -623,11 +670,14 @@ you can pull from the container registry, but you cannot push.
[`--dryrun`](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html)
flag and run the command.
- WARNING:
+ {{< alert type="warning" >}}
+
The [`--delete`](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html)
flag deletes files that exist in the destination but not in the source.
If you swap the source and destination, all data in the Registry is deleted.
+ {{< /alert >}}
+
1. Verify all container registry files have been uploaded to object storage
by looking at the file count returned by these two commands:
@@ -646,9 +696,9 @@ you can pull from the container registry, but you cannot push.
#### Moving to Azure Object Storage
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```ruby
registry['storage'] = {
@@ -661,7 +711,9 @@ registry['storage'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```yaml
storage:
@@ -672,7 +724,9 @@ storage:
trimlegacyrootprefix: true
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
By default, Azure Storage Driver uses the `core.windows.net` realm. You can set another value for `realm` in the `azure` section (for example, `core.usgovcloudapi.net` for Azure Government Cloud).
@@ -682,9 +736,9 @@ By default, users accessing a registry configured with a remote backend are redi
However, this behavior is undesirable for registries used by internal hosts that usually can't access public servers. To disable redirects and [proxy download](../object_storage.md#proxy-download), set the `disable` flag to true as follows. This makes all traffic always go through the Registry service. This results in improved security (less surface attack as the storage backend is not publicly accessible), but worse performance (all traffic is redirected via the service).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -705,7 +759,9 @@ However, this behavior is undesirable for registries used by internal hosts that
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Add the `redirect` flag to your registry configuration YAML file:
@@ -727,7 +783,9 @@ However, this behavior is undesirable for registries used by internal hosts that
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Encrypted S3 buckets
@@ -739,9 +797,9 @@ encryption keys in every request.
For SSE-S3, you must enable the `encrypt` option in the registry settings. How you do this depends
on how you installed GitLab. Follow the instructions here that match your installation method.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -761,7 +819,9 @@ on how you installed GitLab. Follow the instructions here that match your instal
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit your registry configuration YAML file:
@@ -779,7 +839,9 @@ on how you installed GitLab. Follow the instructions here that match your instal
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations)
for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Storage limitations
@@ -793,9 +855,9 @@ The Registry server listens on localhost at port `5000` by default,
which is the address for which the Registry server should accept connections.
In the examples below we set the Registry's port to `5010`.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Open `/etc/gitlab/gitlab.rb` and set `registry['registry_http_addr']`:
@@ -805,7 +867,9 @@ In the examples below we set the Registry's port to `5010`.
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Open the configuration file of your Registry server and edit the
[`http:addr`](https://distribution.github.io/distribution/about/configuration/#http) value:
@@ -817,7 +881,9 @@ In the examples below we set the Registry's port to `5010`.
1. Save the file and restart the Registry server.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Disable container registry per project
@@ -826,12 +892,15 @@ project, you can [disable it from your project's settings](../../user/project/se
## Use an external container registry with GitLab as an auth endpoint
-WARNING:
+{{< alert type="warning" >}}
+
Using third-party container registries in GitLab was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/376217)
in GitLab 15.8 and support ended in GitLab 16.0.
If you need to use third-party container registries instead of the GitLab container registry,
tell us about your use cases in [feedback issue 958](https://gitlab.com/gitlab-org/container-registry/-/issues/958).
+{{< /alert >}}
+
If you use an external container registry, some features associated with the
container registry may be unavailable or have [inherent risks](../../user/packages/container_registry/reduce_container_registry_storage.md#use-with-external-container-registries).
@@ -940,15 +1009,18 @@ response to events happening in the registry.
Read more about the container registry notifications configuration options in the
[Docker Registry notifications documentation](https://distribution.github.io/distribution/about/notifications/).
-WARNING:
+{{< alert type="warning" >}}
+
Support for the `threshold` parameter was [deprecated](https://gitlab.com/gitlab-org/container-registry/-/issues/1243)
in GitLab 17.0, and is planned for removal in 18.0. Use `maxretries` instead.
+{{< /alert >}}
+
You can configure multiple endpoints for the container registry.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
To configure a notification endpoint for a Linux package installation:
@@ -972,13 +1044,18 @@ To configure a notification endpoint for a Linux package installation:
gitlab_rails['registry_notification_secret'] = 'AUTHORIZATION_EXAMPLE_TOKEN' # Must match the auth token in registry['notifications']
```
- NOTE:
- Replace `AUTHORIZATION_EXAMPLE_TOKEN` with a case sensitive alphanumeric string
- that starts with a letter. You can generate one with `< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c 32 | sed "s/^[0-9]*//"; echo`
+ {{< alert type="note" >}}
+
+ Replace `AUTHORIZATION_EXAMPLE_TOKEN` with a case sensitive alphanumeric string
+ that starts with a letter. You can generate one with `< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c 32 | sed "s/^[0-9]*//"; echo`
+
+ {{< /alert >}}
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Configuring the notification endpoint is done in your registry configuration YAML file created
when you deployed your Docker registry.
@@ -998,7 +1075,9 @@ notifications:
backoff: 1000
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Run the cleanup policy
@@ -1058,9 +1137,12 @@ projects_and_size.each do |ps|
end
```
-NOTE:
+{{< alert type="note" >}}
+
The script calculates size based on container image layers. Since layers can be shared across multiple projects, the results are approximate but give a good indication of relative disk usage between projects.
+{{< /alert >}}
+
To remove image tags by running the cleanup policy, run the following commands in the
[GitLab Rails console](../operations/rails_console.md):
@@ -1105,9 +1187,12 @@ end
## Container registry metadata database
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/423459) in GitLab 17.3.
@@ -1117,10 +1202,13 @@ See the [Container registry metadata database](container_registry_metadata_datab
## Container registry garbage collection
-NOTE:
+{{< alert type="note" >}}
+
Retention policies in your object storage provider, such as Amazon S3 Lifecycle, may prevent
objects from being properly deleted.
+{{< /alert >}}
+
The container registry can use considerable amounts of storage space, and you might want to
[reduce storage usage](../../user/packages/container_registry/reduce_container_registry_storage.md).
Among the listed options, deleting tags is the most effective option. However, tag deletion
@@ -1131,11 +1219,14 @@ delete unreferenced layers and (optionally) untagged manifests.
To start the garbage collector, use the `registry-garbage-collect` command provided by `gitlab-ctl`.
-WARNING:
+{{< alert type="warning" >}}
+
This command shuts down the container registry prior to the garbage collection and
only starts it again after garbage collection completes. If you prefer to avoid downtime,
you can manually set the container registry to [read-only mode and bypass `gitlab-ctl`](#performing-garbage-collection-without-downtime).
+{{< /alert >}}
+
The time required to perform garbage collection is proportional to the container registry data size.
Prerequisites:
@@ -1387,9 +1478,12 @@ for Registry to run separately from GitLab:
<!--- start_remove The following content will be removed on remove_date: '2025/08/15' -->
-WARNING:
+{{< alert type="warning" >}}
+
Support for authenticating requests using Amazon S3 Signature Version 2 in the container registry is deprecated in GitLab 17.8 and is planned for removal in 18.0. Use Signature Version 4 instead. This is a breaking change. For more information, see [issue 1449](https://gitlab.com/gitlab-org/container-registry/-/issues/1449).
+{{< /alert >}}
+
<!--- end_remove -->
### Configure GitLab
@@ -1483,8 +1577,12 @@ The GitLab container registry should accept the same configuration that you are
## Max retries for deleting container images
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/480652) in GitLab 17.5 [with a flag](../feature_flags.md) named `set_delete_failed_container_repository`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/490354) in GitLab 17.6. Feature flag `set_delete_failed_container_repository` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/480652) in GitLab 17.5 [with a flag](../feature_flags.md) named `set_delete_failed_container_repository`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/490354) in GitLab 17.6. Feature flag `set_delete_failed_container_repository` removed.
+
+{{< /history >}}
Errors could happen when deleting container images, so deletions are retried to ensure
the error is not a transient issue. Deletion is retried up to 10 times, with a back off delay
diff --git a/doc/administration/packages/container_registry_metadata_database.md b/doc/administration/packages/container_registry_metadata_database.md
index dbba08e966a5878ff768005ff2ad982e67912c6b..eb837b5e9dad0588d70e921788bdbf6f67fd3452 100644
--- a/doc/administration/packages/container_registry_metadata_database.md
+++ b/doc/administration/packages/container_registry_metadata_database.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Container registry metadata database
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423459) in GitLab 16.4 as a [beta feature](../../policy/development_stages_support.md) for GitLab Self-Managed.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/423459) in GitLab 17.3.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423459) in GitLab 16.4 as a [beta feature](../../policy/development_stages_support.md) for GitLab Self-Managed.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/423459) in GitLab 17.3.
+
+{{< /history >}}
The metadata database enables many new registry features, including
online garbage collection, and increases the efficiency of many registry operations.
@@ -126,7 +133,8 @@ A few factors affect the duration of the migration:
- The number of registry instances running.
- Network latency between the registry, PostgresSQL and your configured Object Storage.
-NOTE:
+{{< alert type="note" >}}
+
The migration only targets tagged images. Untagged and unreferenced manifests, and the layers
exclusively referenced by them, are left behind and become inaccessible. Untagged images
were never visible through the GitLab UI or API, but they can become "dangling" and
@@ -134,15 +142,20 @@ left behind in the backend. After migration to the new registry, all images are
to continuous online garbage collection, by default deleting any untagged and unreferenced manifests
and layers that remain for longer than 24 hours.
+{{< /alert >}}
+
Choose the one or three step method according to your registry installation.
#### One-step migration
-WARNING:
+{{< alert type="warning" >}}
+
The registry must be shut down or remain in `read-only` mode during the migration.
Only choose this method if you do not need to write to the registry during the migration
and your registry contains a relatively small amount of data.
+{{< /alert >}}
+
1. Add the `database` section to your `/etc/gitlab/gitlab.rb` file, but start with the metadata database **disabled**:
```ruby
@@ -231,21 +244,27 @@ Follow this guide to migrate your existing container registry data.
This procedure is recommended for larger sets of data or if you are
trying to minimize downtime while completing the migration.
-NOTE:
+{{< alert type="note" >}}
+
Users have reported step one import completed at [rates of 2 to 4 TB per hour](https://gitlab.com/gitlab-org/gitlab/-/issues/423459).
At the slower speed, registries with over 100TB of data could take longer than 48 hours.
+{{< /alert >}}
+
##### Pre-import repositories (step one)
For larger instances, this command can take hours to days to complete, depending
on the size of your registry. You may continue to use the registry as normal while
step one is being completed.
-WARNING:
+{{< alert type="warning" >}}
+
It is [not yet possible](https://gitlab.com/gitlab-org/container-registry/-/issues/1162)
to restart the migration, so it's important to let the migration run to completion.
If you must halt the operation, you have to restart this step.
+{{< /alert >}}
+
1. Add the `database` section to your `/etc/gitlab/gitlab.rb` file, but start with the metadata database **disabled**:
```ruby
@@ -271,12 +290,15 @@ If you must halt the operation, you have to restart this step.
sudo gitlab-ctl registry-database import --step-one
```
-NOTE:
+{{< alert type="note" >}}
+
You should try to schedule the following step as soon as possible
to reduce the amount of downtime required. Ideally, less than one week
after step one completes. Any new data written to the registry between steps one and two,
causes step two to take more time.
+{{< /alert >}}
+
##### Import all repository data (step two)
This step requires the registry to be shut down or set in `read-only` mode.
@@ -382,10 +404,13 @@ The registry must be enabled and the configuration section must have the databas
1. The registry must stop if it's running. Type `y` to confirm and wait for the process to finish.
-NOTE:
+{{< alert type="note" >}}
+
The `migrate up` command offers some extra flags that can be used to control how the migrations are applied.
Run `sudo gitlab-ctl registry-database migrate up --help` for details.
+{{< /alert >}}
+
### Undo schema migrations
You can undo schema migrations in case anything goes wrong, but this is a non-recoverable action.
@@ -398,9 +423,12 @@ after this.
sudo gitlab-ctl registry-database migrate down
```
-NOTE:
+{{< alert type="note" >}}
+
The `migrate down` command offers some extra flags. Run `sudo gitlab-ctl registry-database migrate down --help` for details.
+{{< /alert >}}
+
## Online garbage collection monitoring
The initial runs of online garbage collection following the import process varies
diff --git a/doc/administration/packages/container_registry_troubleshooting.md b/doc/administration/packages/container_registry_troubleshooting.md
index 2ef4fbec6e4b212f8fe72172b0338d24b9dc7daa..727821bd377c1f9e11c9401d7965ed3d1ebf99fd 100644
--- a/doc/administration/packages/container_registry_troubleshooting.md
+++ b/doc/administration/packages/container_registry_troubleshooting.md
@@ -125,9 +125,9 @@ level=error msg="response completed with error" err.code=unknown err.detail="une
To resolve the error specify a `chunksize` value in the Registry configuration.
Start with a value between `25000000` (25 MB) and `50000000` (50 MB).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -144,7 +144,9 @@ Start with a value between `25000000` (25 MB) and `50000000` (50 MB).
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `config/gitlab.yml`:
@@ -159,7 +161,9 @@ Start with a value between `25000000` (25 MB) and `50000000` (50 MB).
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Supporting older Docker clients
@@ -170,9 +174,9 @@ experience an error pushing images. See
You can add a configuration option for backwards compatibility.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -182,7 +186,9 @@ You can add a configuration option for backwards compatibility.
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit the YAML configuration file you created when you deployed the registry. Add the following snippet:
@@ -194,7 +200,9 @@ You can add a configuration option for backwards compatibility.
1. Restart the registry for the changes to take affect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Docker connection error
@@ -221,9 +229,9 @@ For more information, see [Docker push through NGINX proxy fails trying to send
To resolve this issue, update your NGINX configuration to enable relative URLs in the registry:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -235,7 +243,9 @@ To resolve this issue, update your NGINX configuration to enable relative URLs i
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit the YAML configuration file you created when you deployed the registry. Add the following snippet:
@@ -246,7 +256,9 @@ To resolve this issue, update your NGINX configuration to enable relative URLs i
1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-:::TabTitle Docker Compose
+{{< /tab >}}
+
+{{< tab title="Docker Compose" >}}
1. Edit your `docker-compose.yaml` file:
@@ -271,16 +283,21 @@ To resolve this issue, update your NGINX configuration to enable relative URLs i
sudo docker restart gitlab
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Enable the Registry debug server
You can use the container registry debug server to diagnose problems. The debug endpoint can monitor metrics and health, as well as do profiling.
-WARNING:
+{{< alert type="warning" >}}
+
Sensitive information may be available from the debug endpoint.
Access to the debug endpoint must be locked down in a production environment.
+{{< /alert >}}
+
The optional debug server can be enabled by setting the registry debug address
in your `gitlab.rb` configuration.
diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md
index dc0d89fa94b4c05c2dae3124ef3ab119e549b8da..7aa9b1ab7598f0147bdff4423d984d35c3016dc4 100644
--- a/doc/administration/packages/dependency_proxy.md
+++ b/doc/administration/packages/dependency_proxy.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Dependency Proxy administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6.
+
+{{< /history >}}
GitLab can be used as a dependency proxy for your frequently-accessed upstream images.
@@ -28,9 +35,9 @@ The Dependency Proxy is enabled by default. If you are an administrator, you
can turn off the Dependency Proxy. To turn off the Dependency Proxy, follow the instructions that
correspond to your GitLab installation.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -41,7 +48,9 @@ correspond to your GitLab installation.
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation)
for the changes to take effect.
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
After the installation is complete, update the global `appConfig` to turn off the Dependency Proxy:
@@ -58,7 +67,9 @@ global:
For more information, see [Configure Charts using Globals](https://docs.gitlab.com/charts/charts/globals.html#configure-appconfig-settings).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. After the installation is complete, configure the `dependency_proxy` section in
`config/gitlab.yml`. Set `enabled` to `false` to turn off the Dependency Proxy:
@@ -70,7 +81,9 @@ For more information, see [Configure Charts using Globals](https://docs.gitlab.c
1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Multi-node GitLab installations
@@ -93,9 +106,9 @@ The Dependency Proxy files for Linux package installations are stored under
`/var/opt/gitlab/gitlab-rails/shared/dependency_proxy/` and for source
installations under `shared/dependency_proxy/` (relative to the Git home directory).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -105,7 +118,9 @@ installations under `shared/dependency_proxy/` (relative to the Git home directo
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit the `dependency_proxy` section in `config/gitlab.yml`:
@@ -117,7 +132,9 @@ installations under `shared/dependency_proxy/` (relative to the Git home directo
1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Using object storage
@@ -127,9 +144,9 @@ This section describes the earlier configuration format. [Migration steps still
[Read more about using object storage with GitLab](../object_storage.md).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines (uncomment where
necessary):
@@ -160,7 +177,9 @@ This section describes the earlier configuration format. [Migration steps still
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit the `dependency_proxy` section in `config/gitlab.yml` (uncomment where necessary):
@@ -194,7 +213,9 @@ This section describes the earlier configuration format. [Migration steps still
1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Migrate local Dependency Proxy blobs and manifests to object storage
diff --git a/doc/administration/pages/_index.md b/doc/administration/pages/_index.md
index 44666fdae752d5c271449fcc04a6b5713b35a3e6..0fd68728791b845353ce62afd4790f5bec8eb9f7 100644
--- a/doc/administration/pages/_index.md
+++ b/doc/administration/pages/_index.md
@@ -5,17 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Pages administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab Pages allows for hosting of static sites. It must be configured by an
administrator. Separate [user documentation](../../user/project/pages/_index.md) is available.
-NOTE:
+{{< alert type="note" >}}
+
This guide is for Linux package installations. If you have a self-compiled GitLab installation, see
[GitLab Pages administration for self-compiled installations](source.md).
+{{< /alert >}}
+
## The GitLab Pages daemon
GitLab Pages makes use of the [GitLab Pages daemon](https://gitlab.com/gitlab-org/gitlab-pages), a basic HTTP server
@@ -56,9 +62,9 @@ Before configuring Pages for wildcard domains, you must:
| GitLab domain | Pages domain | Does it work? |
| -------------------- | ------------------- | ------------- |
- | `example.com` | `example.io` | **{check-circle}** Yes |
- | `example.com` | `pages.example.com` | **{dotted-circle}** No |
- | `gitlab.example.com` | `pages.example.com` | **{check-circle}** Yes |
+ | `example.com` | `example.io` | {{< icon name="check-circle" >}} Yes |
+ | `example.com` | `pages.example.com` | {{< icon name="dotted-circle" >}} No |
+ | `gitlab.example.com` | `pages.example.com` | {{< icon name="check-circle" >}} Yes |
1. Configure a **wildcard DNS record**.
1. Optional. Have a **wildcard certificate** for that domain if you decide to
@@ -75,9 +81,9 @@ Before configuring Pages for single-domain sites, you must:
| GitLab domain | Pages domain | Supported |
| -------------------- | ------------------- | ------------- |
- | `example.com` | `example.io` | **{check-circle}** Yes |
- | `example.com` | `pages.example.com` | **{dotted-circle}** No |
- | `gitlab.example.com` | `pages.example.com` | **{check-circle}** Yes |
+ | `example.com` | `example.io` | {{< icon name="check-circle" >}} Yes |
+ | `example.com` | `pages.example.com` | {{< icon name="dotted-circle" >}} No |
+ | `gitlab.example.com` | `pages.example.com` | {{< icon name="check-circle" >}} Yes |
1. Configure a **DNS record**.
1. Optional. If you decide to serve Pages under HTTPS, have a **TLS certificate** for that domain.
@@ -85,9 +91,12 @@ Before configuring Pages for single-domain sites, you must:
so that your users don't have to bring their own.
1. For custom domains, have a **secondary IP**.
-NOTE:
+{{< alert type="note" >}}
+
If your GitLab instance and the Pages daemon are deployed in a private network or behind a firewall, your GitLab Pages websites are only accessible to devices/users that have access to the private network.
+{{< /alert >}}
+
### Add the domain to the Public Suffix List
The [Public Suffix List](https://publicsuffix.org) is used by browsers to
@@ -120,10 +129,14 @@ IPv6 address. If you don't have IPv6, you can omit the `AAAA` record.
#### DNS configuration for single-domain sites
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) as an [experiment](../../policy/development_stages_support.md) in GitLab 16.7.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148621) to [beta](../../policy/development_stages_support.md) in GitLab 16.11.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1111) implementation from NGINX to the GitLab Pages codebase in GitLab 17.2.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/483365) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) as an [experiment](../../policy/development_stages_support.md) in GitLab 16.7.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148621) to [beta](../../policy/development_stages_support.md) in GitLab 16.11.
+- [Changed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1111) implementation from NGINX to the GitLab Pages codebase in GitLab 17.2.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/483365) in GitLab 17.4.
+
+{{< /history >}}
To configure GitLab Pages DNS for single-domain sites without wildcard DNS:
@@ -169,9 +182,12 @@ This example contains the following:
- `192.0.2.1`: The primary IP of your GitLab instance.
- `192.0.2.2`: The secondary IP, which is dedicated to GitLab Pages. It must be different than the primary IP.
-NOTE:
+{{< alert type="note" >}}
+
You should not use the GitLab domain to serve user pages. For more information see the [security section](#security).
+{{< /alert >}}
+
## Configuration
Depending on your needs, you can set up GitLab Pages in 4 different ways.
@@ -211,10 +227,14 @@ For an overview, see [How to Enable GitLab Pages for GitLab CE and EE](https://y
### Single-domain sites
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) as an [experiment](../../policy/development_stages_support.md) in GitLab 16.7.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148621) to [beta](../../policy/development_stages_support.md) in GitLab 16.11.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1111) implementation from NGINX to the GitLab Pages codebase in GitLab 17.2.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/483365) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) as an [experiment](../../policy/development_stages_support.md) in GitLab 16.7.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148621) to [beta](../../policy/development_stages_support.md) in GitLab 16.11.
+- [Changed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1111) implementation from NGINX to the GitLab Pages codebase in GitLab 17.2.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/483365) in GitLab 17.4.
+
+{{< /history >}}
The following configuration is the minimum setup to use GitLab Pages.
It is the foundation for all other setups described here.
@@ -244,12 +264,15 @@ To configure GitLab Pages to use single-domain sites:
The resulting URL scheme is `http://example.io/<namespace>/<project_slug>`.
-WARNING:
+{{< alert type="warning" >}}
+
GitLab Pages supports only one URL scheme at a time:
wildcard domains or single-domain sites.
If you enable `namespace_in_path`, existing GitLab Pages websites
are accessible only on single-domain.
+{{< /alert >}}
+
### Wildcard domains with TLS support
Prerequisites:
@@ -285,21 +308,30 @@ public internet.
The resulting URL scheme is `https://<namespace>.example.io/<project_slug>`.
-WARNING:
+{{< alert type="warning" >}}
+
Multiple wildcards for one instance is not supported. Only one wildcard per instance can be assigned.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
GitLab Pages does not update the OAuth application if changes are made to the redirect URI.
Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitlab-secrets.json`,
then run `gitlab-ctl reconfigure`. For more information, read
[GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947).
+{{< /alert >}}
### Single-domain sites with TLS support
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) as an [experiment](../../policy/development_stages_support.md) in GitLab 16.7.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148621) to [beta](../../policy/development_stages_support.md) in GitLab 16.11.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1111) implementation from NGINX to the GitLab Pages codebase in GitLab 17.2.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/483365) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) as an [experiment](../../policy/development_stages_support.md) in GitLab 16.7.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148621) to [beta](../../policy/development_stages_support.md) in GitLab 16.11.
+- [Changed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1111) implementation from NGINX to the GitLab Pages codebase in GitLab 17.2.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/483365) in GitLab 17.4.
+
+{{< /history >}}
Prerequisites:
@@ -336,23 +368,29 @@ daemon doesn't listen to the public internet:
[System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application)
to use the HTTPS protocol.
- WARNING:
+ {{< alert type="warning" >}}
+
GitLab Pages does not update the OAuth application, and
the default `auth_redirect_uri` is updated to `https://example.io/projects/auth`.
Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitlab-secrets.json`,
then run `gitlab-ctl reconfigure`. For more information, see
[GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947).
+ {{< /alert >}}
+
1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
The resulting URL scheme is `https://example.io/<namespace>/<project_slug>`.
-WARNING:
+{{< alert type="warning" >}}
+
GitLab Pages supports only one URL scheme at a time:
wildcard domains or single-domain sites.
If you enable `namespace_in_path`, existing GitLab Pages websites
are accessible only as single-domain sites.
+{{< /alert >}}
+
### Wildcard domains with TLS-terminating Load Balancer
Prerequisites:
@@ -554,12 +592,15 @@ GitLab supports [custom domain verification](../../user/project/pages/custom_dom
When adding a custom domain, users are required to prove they own it by
adding a GitLab-controlled verification code to the DNS records for that domain.
-WARNING:
+{{< alert type="warning" >}}
+
Disabling domain verification is unsafe and can lead to various vulnerabilities.
If you *do* disable it, either ensure that the Pages root domain itself does not point to the
secondary IP or add the root domain as custom domain to a project; otherwise, any user can add this
domain as a custom domain to their project.
+{{< /alert >}}
+
If your user base is private or otherwise trusted, you can disable the
verification requirement:
@@ -611,10 +652,13 @@ Pages access control is disabled by default. To enable it:
1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
1. Users can now configure it in their [projects' settings](../../user/project/pages/pages_access_control.md).
-NOTE:
+{{< alert type="note" >}}
+
For this setting to be effective with multi-node setups, it has to be applied to
all the App nodes and Sidekiq nodes.
+{{< /alert >}}
+
#### Using Pages with reduced authentication scope
By default, the Pages daemon uses the `api` scope to authenticate. You can configure this. For
@@ -652,9 +696,12 @@ To do that:
1. Select the **Disable public access to Pages sites** checkbox.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
You must enable [Access Control](#access-control) first for the setting to show in the **Admin** area.
+{{< /alert >}}
+
### Running behind a proxy
Like the rest of GitLab, Pages can be used in those environments where external
@@ -684,7 +731,11 @@ Authority (CA) in the system certificate store.
### Support mutual TLS when calling the GitLab API
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) in GitLab 17.1.
+
+{{< /history >}}
Prerequisites:
@@ -733,10 +784,13 @@ To configure the certificates in your GitLab Pages server:
### ZIP serving and cache configuration
-WARNING:
+{{< alert type="warning" >}}
+
These instructions deal with some advanced settings of your GitLab instance. The recommended default values are set inside GitLab Pages. You should
change these settings only if absolutely necessary. Use extreme caution.
+{{< /alert >}}
+
GitLab Pages can serve content from ZIP archives through object storage (an
[issue](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/485) exists for supporting disk storage
as well). It uses an in-memory cache to increase the performance when serving content from a ZIP
@@ -776,7 +830,11 @@ gitlab_pages['headers'] = ['Strict-Transport-Security: max-age=63072000']
### Pages project redirects limits
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/778) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/778) in GitLab 15.2.
+
+{{< /history >}}
GitLab Pages comes with a set of default limits for the [`_redirects` file](../../user/project/pages/redirects.md)
to minimize the impact on performance. You can configure these limits if you'd like to increase or decrease the limits.
@@ -878,9 +936,12 @@ Follow the steps below to configure the proxy listener of GitLab Pages.
## Set global maximum size of each GitLab Pages site
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Prerequisites:
@@ -896,9 +957,12 @@ To set the global maximum pages size for a project:
## Set maximum size of each GitLab Pages site in a group
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Prerequisites:
@@ -914,9 +978,12 @@ To set the maximum size of each GitLab Pages site in a group, overriding the inh
## Set maximum size of GitLab Pages site in a project
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Prerequisites:
@@ -945,7 +1012,11 @@ To set the maximum number of GitLab Pages custom domains for a project:
## Configure the default expiry for parallel deployments
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/456477) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/456477) in GitLab 17.4.
+
+{{< /history >}}
Prerequisites:
@@ -978,22 +1049,28 @@ your main application server. This configuration does not support mutual TLS (mT
To configure GitLab Pages on a separate server:
-WARNING:
+{{< alert type="warning" >}}
+
The following procedure includes steps to back up and edit the
`gitlab-secrets.json` file. This file contains secrets that control
database encryption. Proceed with caution.
+{{< /alert >}}
+
1. Optionally, to enable [access control](#access-control), add the following to `/etc/gitlab/gitlab.rb` and [reconfigure the **GitLab server**](../restart_gitlab.md#reconfigure-a-linux-package-installation):
```ruby
gitlab_pages['access_control'] = true
```
- WARNING:
+ {{< alert type="warning" >}}
+
If you plan to use GitLab Pages with access control, you must enable it on the first GitLab server before copying `gitlab-secrets.json`.
Enabling access control generates a new OAuth application, and information about it propagates to `gitlab-secrets.json`. If it's not done
in the correct order, you may face issues with access control.
+ {{< /alert >}}
+
1. Create a backup of the secrets file on the **GitLab server**:
```shell
@@ -1089,12 +1166,15 @@ The cache behavior can be modified by changing the cache settings, however, the
Incorrect configuration of these values may result in intermittent
or persistent errors, or the Pages Daemon serving old content.
-NOTE:
+{{< alert type="note" >}}
+
Expiry, interval and timeout flags use [Go duration formatting](https://pkg.go.dev/time#ParseDuration).
A duration string is a possibly signed sequence of decimal numbers,
each with optional fraction and a unit suffix, such as `300ms`, `1.5h` or `2h45m`.
Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
+{{< /alert >}}
+
Examples:
- Increasing `gitlab_cache_expiry` allows items to exist in the cache longer.
@@ -1126,10 +1206,13 @@ The following [object storage](../object_storage.md) settings are:
| `remote_directory` | The name of the bucket where Pages site content is stored. | |
| `connection` | Various connection options described below. | |
-NOTE:
+{{< alert type="note" >}}
+
If you want to stop using and disconnect the NFS server, you need to
[explicitly disable local storage](#disable-pages-local-storage).
+{{< /alert >}}
+
### S3-compatible connection settings
You should use the [consolidated object storage settings](../object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form).
@@ -1228,7 +1311,11 @@ than GitLab to prevent XSS attacks.
### Rate limits
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/14653) in GitLab 17.3: You can exclude subnets from Pages rate limits.
+{{< history >}}
+
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/14653) in GitLab 17.3: You can exclude subnets from Pages rate limits.
+
+{{< /history >}}
You can enforce rate limits to help minimize the risk of a Denial of Service (DoS) attack. GitLab Pages
uses a [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) to enforce rate limiting. By default,
diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md
index a567cd03ad56ce6f431e06e5efcb175be0a9269b..47a1fded883c0cfc9c97b7fb3715583e03e4a357 100644
--- a/doc/administration/pages/source.md
+++ b/doc/administration/pages/source.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Pages administration for self-compiled installations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
Before attempting to enable GitLab Pages, first make sure you have
[installed GitLab](../../install/installation.md) successfully.
+{{< /alert >}}
+
This document explains how to configure GitLab Pages for self-compiled GitLab installations.
For more information about configuring GitLab Pages for Linux Package installations (recommended), see the [Linux package documentation](_index.md).
@@ -75,10 +81,13 @@ host that GitLab runs. For example, an entry would look like this:
Where `example.io` is the domain to serve GitLab Pages from,
and `192.0.2.1` is the IP address of your GitLab instance.
-NOTE:
+{{< alert type="note" >}}
+
You should not use the GitLab domain to serve user pages. For more information
see the [security section](#security).
+{{< /alert >}}
+
## Configuration
Depending on your needs, you can set up GitLab Pages in 4 different ways.
@@ -386,9 +395,12 @@ world. Custom domains and TLS are supported.
## NGINX caveats
-NOTE:
+{{< alert type="note" >}}
+
The following information applies only to self-compiled installations.
+{{< /alert >}}
+
Be extra careful when setting up the domain name in the NGINX configuration. You must
not remove the backslashes.
diff --git a/doc/administration/pages/troubleshooting.md b/doc/administration/pages/troubleshooting.md
index 4676fffb70e2f837f97ebd7fe0fc8b43b492bfce..85de7605816ba302e44edddfedf93d8208102bc2 100644
--- a/doc/administration/pages/troubleshooting.md
+++ b/doc/administration/pages/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting GitLab Pages administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page contains a list of issues you might encounter when administering GitLab Pages.
diff --git a/doc/administration/polling.md b/doc/administration/polling.md
index 4f46595d410d393aa09f03ba157fcc086c89f41c..8b4f26721ca5a0a034743fb75a06ac2ea66c2cad 100644
--- a/doc/administration/polling.md
+++ b/doc/administration/polling.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Polling interval multiplier
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The GitLab UI polls for updates for different resources (such as issue notes, issue titles, and pipeline
statuses) on a schedule appropriate to the resource.
diff --git a/doc/administration/postgresql/_index.md b/doc/administration/postgresql/_index.md
index b5e8ec2b668964edbc6b311a66fb7b49e276edff..81149547d4eabcd986a5348ea5c361ce3d4e4b29 100644
--- a/doc/administration/postgresql/_index.md
+++ b/doc/administration/postgresql/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configuring PostgreSQL for scaling
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
In this section, you are guided through configuring a PostgreSQL database to
be used with GitLab in one of our [reference architectures](../reference_architectures/_index.md).
@@ -39,9 +42,12 @@ Read more about [monitoring and logging setup for external Databases](external_m
### PostgreSQL replication and failover for Linux package installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This setup is for when you have installed GitLab using the
[Linux **Enterprise Edition** (EE) package](https://about.gitlab.com/install/?version=ee).
diff --git a/doc/administration/postgresql/database_load_balancing.md b/doc/administration/postgresql/database_load_balancing.md
index c594e3ce1d882778b5addb80693530f4b893b4ea..e2e833fca84bb7c3732d1f8683db480aa5703800 100644
--- a/doc/administration/postgresql/database_load_balancing.md
+++ b/doc/administration/postgresql/database_load_balancing.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Database Load Balancing
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
With Database Load Balancing, read-only queries can be distributed across
multiple PostgreSQL nodes to increase performance.
@@ -95,13 +98,16 @@ nodes for each environment you want to balance:
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
-NOTE:
+{{< alert type="note" >}}
+
Adding the primary to the hosts list is optional, but recommended.
This makes the primary eligible for load-balanced read queries, improving system performance
when the primary has capacity for these queries.
Very high-traffic instances may not have capacity on the primary for it to serve as a read replica.
The primary will be used for write queries whether or not it is present in this list.
+{{< /alert >}}
+
### Service Discovery
Service discovery allows GitLab to automatically retrieve a list of PostgreSQL
@@ -159,7 +165,11 @@ upper limit on the time it takes to terminate all old database connections.
### Handling stale reads
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/327902) from GitLab Premium to GitLab Free in 14.0.
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/327902) from GitLab Premium to GitLab Free in 14.0.
+
+{{< /history >}}
To prevent reading from an outdated secondary the load balancer checks if it
is in sync with the primary. If the data is recent enough, the
diff --git a/doc/administration/postgresql/external.md b/doc/administration/postgresql/external.md
index a573cd8162397758f9bd6f7eedf5c62e188dec92..ee77c19d2ada6e2c9bd20cf3a0022adb9c32a361 100644
--- a/doc/administration/postgresql/external.md
+++ b/doc/administration/postgresql/external.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure GitLab using an external PostgreSQL service
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you're hosting GitLab on a cloud provider, you can optionally use a
managed service for PostgreSQL. For example, AWS offers a managed Relational
diff --git a/doc/administration/postgresql/moving.md b/doc/administration/postgresql/moving.md
index a436d4df31b34410aa84a35793e531eb90ee98b1..a1ace8143450ab336f59fe7770f373a4ba038666 100644
--- a/doc/administration/postgresql/moving.md
+++ b/doc/administration/postgresql/moving.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Moving GitLab databases to a different PostgreSQL instance
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Sometimes it is necessary to move your databases from one PostgreSQL instance to
another. For example, if you are using AWS Aurora and are preparing to
@@ -39,13 +42,16 @@ To move databases from one instance to another:
/opt/gitlab/embedded/bin/pg_dump -h $SRC_PGHOST -U $SRC_PGUSER -c -C -f praefect_production.sql praefect_production
```
- NOTE:
- In rare occasions, you might notice database performance issues after you perform
+ {{< alert type="note" >}}
+
+In rare occasions, you might notice database performance issues after you perform
a `pg_dump` and restore. This can happen because `pg_dump` does not contain the statistics
[used by the optimizer to make query planning decisions](https://www.postgresql.org/docs/14/app-pgdump.html).
If performance degrades after a restore, fix the problem by finding the problematic query,
then running ANALYZE on the tables used by the query.
+ {{< /alert >}}
+
1. Restore the databases to the destination (this overwrites any existing databases with the same names):
```shell
diff --git a/doc/administration/postgresql/multiple_databases.md b/doc/administration/postgresql/multiple_databases.md
index 8afbbd51cd793062fcad687bc32f5e417a4c8fd2..a218d82912096ea3da1c7ca0f9680ce6f341eaf9 100644
--- a/doc/administration/postgresql/multiple_databases.md
+++ b/doc/administration/postgresql/multiple_databases.md
@@ -1,20 +1,29 @@
---
-
stage: Tenant Scale
group: Organizations
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
title: Multiple Databases
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6168) in GitLab 15.7.
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6168) in GitLab 15.7.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature is not ready for production use
+{{< /alert >}}
+
By default, GitLab uses a single application database, referred to as the `main` database.
To scale GitLab, you can configure GitLab to use multiple application databases.
@@ -44,7 +53,11 @@ databases. Some examples:
## Migrate existing installations using a script
-> - A script for migrating existing Linux package installations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368729) in GitLab 16.8.
+{{< history >}}
+
+- A script for migrating existing Linux package installations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368729) in GitLab 16.8.
+
+{{< /history >}}
### Existing Linux package installations
@@ -133,9 +146,12 @@ sudo gitlab-rake gitlab:db:truncate_legacy_tables:ci
To migrate existing data from the `main` database to the `ci` database, you can
copy the database across.
-NOTE:
+{{< alert type="note" >}}
+
If something unexpected happens during the migration, it is safe to start over.
+{{< /alert >}}
+
### Existing self-compiled installation
1. [Disable background migrations](../../development/database/batched_background_migrations.md#enable-or-disable-background-migrations).
@@ -223,11 +239,14 @@ see [PostgreSQL replication and failover for Linux package installations](replic
To configure GitLab to use multiple application databases, follow the instructions below for your installation type.
-WARNING:
+{{< alert type="warning" >}}
+
You must stop GitLab before setting up multiple databases. This prevents
split-brain situations, where `main` data is written to the `ci` database, and
the other way around.
+{{< /alert >}}
+
### Self-compiled installations
1. For existing installations,
diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md
index 4945bd8de4a80f0779b5865ecd9e69d959f91f61..20c12f39e85d00fe36b66316eade175ecf399fd6 100644
--- a/doc/administration/postgresql/pgbouncer.md
+++ b/doc/administration/postgresql/pgbouncer.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Working with the bundled PgBouncer service
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
PgBouncer is bundled in the `gitlab-ee` package, but is free to use.
For support, you need a [Premium subscription](https://about.gitlab.com/pricing/).
+{{< /alert >}}
+
[PgBouncer](https://www.pgbouncer.org/) is used to seamlessly migrate database
connections between servers in a failover scenario. Additionally, it can be used
in a non-fault-tolerant setup to pool connections, speeding up response time
@@ -42,8 +48,11 @@ This content has been moved to a [new location](replication_and_failover.md#conf
1. Run `gitlab-ctl reconfigure`
- NOTE:
- If the database was already running, it needs to be restarted after reconfigure by running `gitlab-ctl restart postgresql`.
+ {{< alert type="note" >}}
+
+If the database was already running, it needs to be restarted after reconfigure by running `gitlab-ctl restart postgresql`.
+
+ {{< /alert >}}
1. On the node you are running PgBouncer on, make sure the following is set in `/etc/gitlab/gitlab.rb`
diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md
index fe9ce2a0cb764843a9e0b2555d0b09e7408bfde4..309fe8b266025973017445c217ba00905fe7c712 100644
--- a/doc/administration/postgresql/replication_and_failover.md
+++ b/doc/administration/postgresql/replication_and_failover.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: PostgreSQL replication and failover for Linux package installations
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you're a Free user of GitLab Self-Managed, consider using a cloud-hosted solution.
This document doesn't cover self-compiled installations.
@@ -81,10 +84,13 @@ You also need to take into consideration the underlying network topology, making
sure you have redundant connectivity between all Database and GitLab instances
to avoid the network becoming a single point of failure.
-NOTE:
+{{< alert type="note" >}}
+
PostgreSQL 12 is shipped with Linux package installations. Clustering for PostgreSQL 12 is supported only with
Patroni, and thus Patroni becomes mandatory for replication and failover. See the [Patroni](#patroni) section for further details.
+{{< /alert >}}
+
### Database node
Each database node runs four services:
@@ -836,9 +842,12 @@ before making changes as **_some of the options carry a risk of potential data
loss if not fully understood_**. The [replication mode](https://patroni.readthedocs.io/en/latest/replication_modes.html)
configured determines the amount of tolerable data loss.
-WARNING:
+{{< alert type="warning" >}}
+
Replication is not a backup strategy! There is no replacement for a well-considered and tested backup solution.
+{{< /alert >}}
+
Linux package installations default [`synchronous_commit`](https://www.postgresql.org/docs/11/runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT) to `on`.
```ruby
@@ -893,12 +902,15 @@ Stopping or restarting the Patroni service on the leader node triggers an automa
### Manual failover procedure for Patroni
-WARNING:
+{{< alert type="warning" >}}
+
In GitLab 16.5 and earlier, PgBouncer nodes do not automatically fail over alongside
Patroni nodes. PgBouncer services
[must be restarted manually](../postgresql/replication_and_failover_troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server)
for a successful switchover.
+{{< /alert >}}
+
While Patroni supports automatic failover, you also have the ability to perform
a manual one, where you have two slightly different options:
@@ -992,8 +1004,11 @@ Considering these, you should carefully plan your PostgreSQL upgrade:
gitlab-ctl patroni members
```
- NOTE:
- On a Geo secondary site, the Patroni leader node is called `standby leader`.
+ {{< alert type="note" >}}
+
+On a Geo secondary site, the Patroni leader node is called `standby leader`.
+
+ {{< /alert >}}
1. Stop Patroni **only on replicas**.
@@ -1014,11 +1029,14 @@ Considering these, you should carefully plan your PostgreSQL upgrade:
sudo gitlab-ctl pg-upgrade
```
- NOTE:
- `gitlab-ctl pg-upgrade` tries to detect the role of the node. If for any reason the auto-detection
+ {{< alert type="note" >}}
+
+`gitlab-ctl pg-upgrade` tries to detect the role of the node. If for any reason the auto-detection
does not work or you believe it did not detect the role correctly, you can use the `--leader` or
`--replica` arguments to manually override it. Use `gitlab-ctl pg-upgrade --help` for more details on available options.
+ {{< /alert >}}
+
1. Check the status of the leader and cluster. You can proceed only if you have a healthy leader:
```shell
@@ -1044,15 +1062,21 @@ Considering these, you should carefully plan your PostgreSQL upgrade:
If issues are encountered upgrading the replicas,
[there is a troubleshooting section](../postgresql/replication_and_failover_troubleshooting.md#postgresql-major-version-upgrade-fails-on-a-patroni-replica) that might be the solution.
-NOTE:
+{{< alert type="note" >}}
+
Reverting the PostgreSQL upgrade with `gitlab-ctl revert-pg-upgrade` has the same considerations as
`gitlab-ctl pg-upgrade`. You should follow the same procedure by first stopping the replicas,
then reverting the leader, and finally reverting the replicas.
+{{< /alert >}}
+
### Near-zero-downtime upgrade of PostgreSQL in a Patroni cluster
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
Patroni enables you to run a major PostgreSQL upgrade without shutting down the cluster. However, this
requires additional resources to host the new Patroni nodes with the upgraded PostgreSQL. In practice, with this
@@ -1167,9 +1191,12 @@ To dump the current database from the existing cluster, run these commands on th
The `pg_dump` and `pg_dumpall` commands are in `/opt/gitlab/embedded/bin`. In these commands,
`EXISTING_CLUSTER_LEADER` is the host address of the leader node of the existing cluster.
-NOTE:
+{{< alert type="note" >}}
+
The `gitlab-psql` user must be able to authenticate the existing leader from the new leader node.
+{{< /alert >}}
+
#### Replicate data from the existing cluster
After taking the initial data dump, you must keep the new leader in sync with the
diff --git a/doc/administration/postgresql/replication_and_failover_troubleshooting.md b/doc/administration/postgresql/replication_and_failover_troubleshooting.md
index 3c0df07ac4ed7a7acda1fde7e6f36c73a0f923c1..d9ba429e056131909fd5d887eac3eea046c25072 100644
--- a/doc/administration/postgresql/replication_and_failover_troubleshooting.md
+++ b/doc/administration/postgresql/replication_and_failover_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting PostgreSQL replication and failover for Linux package installations
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When working with PostgreSQL replication and failover, you might encounter the following issues.
@@ -106,9 +109,12 @@ If a replica cannot start or rejoin the cluster, or when it lags behind and cann
## Reset the Patroni state in Consul
-WARNING:
+{{< alert type="warning" >}}
+
Resetting the Patroni state in Consul is a potentially destructive process. Make sure that you have a healthy database backup first.
+{{< /alert >}}
+
As a last resort you can reset the Patroni state in Consul completely.
This may be required if your Patroni cluster is in an unknown or bad state and no node can start:
diff --git a/doc/administration/postgresql/standalone.md b/doc/administration/postgresql/standalone.md
index 94d5b2f1d9e2ba1633c6c9307b04b4ec77b253a2..de4e2c2b3d73462d279d111a8271afa700a52106 100644
--- a/doc/administration/postgresql/standalone.md
+++ b/doc/administration/postgresql/standalone.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Standalone PostgreSQL for Linux package installations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you wish to have your database service hosted separately from your GitLab
application servers, you can do this using the PostgreSQL binaries packaged
diff --git a/doc/administration/postgresql/upgrading_os.md b/doc/administration/postgresql/upgrading_os.md
index 546cc30883f80c595966e8c94a6a84ab4a9de386..1a78b6ef847ebc6fcc533a9794362e34163198a0 100644
--- a/doc/administration/postgresql/upgrading_os.md
+++ b/doc/administration/postgresql/upgrading_os.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Upgrading operating systems for PostgreSQL
---
-WARNING:
+{{< alert type="warning" >}}
+
[Geo](../geo/_index.md) cannot be used to migrate a PostgreSQL database from one operating system to another. If you attempt to do so, the secondary site may appear to be 100% replicated when in fact some data is not replicated, leading to data loss. This is because Geo depends on PostgreSQL streaming replication, which suffers from the limitations described in this document. Also see [Geo Troubleshooting - Check OS locale data compatibility](../geo/replication/troubleshooting/common.md#check-os-locale-data-compatibility).
+{{< /alert >}}
+
If you upgrade the operating system on which PostgreSQL runs, any
[changes to locale data might corrupt your database indexes](https://wiki.postgresql.org/wiki/Locale_data_changes).
In particular, the upgrade to `glibc` 2.28 is likely to cause this problem. To avoid this issue,
diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md
index 508e5731c5c61184547034eaed05acf3765c60ee..91e66239779624231728d9b4b7055e37c7503bdc 100644
--- a/doc/administration/raketasks/check.md
+++ b/doc/administration/raketasks/check.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Integrity check Rake task
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides Rake tasks to check the integrity of various components.
See also the [check GitLab configuration Rake task](maintenance.md#check-gitlab-configuration).
@@ -286,12 +289,19 @@ I, [2020-06-11T17:18:15.575711 #27148] INFO -- : Done!
## Reset encrypted tokens when they can't be recovered
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131893) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131893) in GitLab 16.6.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This operation is dangerous and can result in data-loss. Proceed with extreme caution.
You must have knowledge about GitLab internals before you perform this operation.
+{{< /alert >}}
+
In some cases, encrypted tokens can no longer be recovered and cause issues.
Most often, runner registration tokens for groups and projects might be broken on very large instances.
diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md
index 198642150fbd96019218a001b6dcdd23861474f4..bd9abeb7f43455323b69ac18c05388bbb06731a6 100644
--- a/doc/administration/raketasks/github_import.md
+++ b/doc/administration/raketasks/github_import.md
@@ -1,15 +1,18 @@
---
+redirect_to: ../../user/project/import/github.md
+remove_date: "2025-01-25"
stage: Systems
group: Distribution
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
-remove_date: '2025-01-25'
-redirect_to: '../../user/project/import/github.md'
title: GitHub import Rake task (removed)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134296) in GitLab 16.6
and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147182) in 17.0.
diff --git a/doc/administration/raketasks/incoming_email.md b/doc/administration/raketasks/incoming_email.md
index 87f218aa9d5968c649909a014f482e8b459f030c..086173f1ed1a0b5c72ac75d7e5aee22fa7e58914 100644
--- a/doc/administration/raketasks/incoming_email.md
+++ b/doc/administration/raketasks/incoming_email.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Incoming email Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9.
+
+{{< /history >}}
The following are Incoming email-related Rake tasks.
@@ -21,32 +28,40 @@ GitLab can use [Incoming email](../incoming_email.md) secrets read from an encry
Show the contents of the current Incoming email secrets.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake gitlab:incoming_email:secret:show
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the incoming email password. For more information,
read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-incoming-emails).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
sudo docker exec -t <container name> gitlab:incoming_email:secret:show
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
bundle exec rake gitlab:incoming_email:secret:show RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Example output
@@ -59,64 +74,80 @@ user: 'incoming-email@mail.example.com'
Opens the secret contents in your editor, and writes the resulting content to the encrypted secret file when you exit.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake gitlab:incoming_email:secret:edit EDITOR=vim
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the incoming email password. For more information,
read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-incoming-emails).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
sudo docker exec -t <container name> gitlab:incoming_email:secret:edit EDITOR=editor
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
bundle exec rake gitlab:incoming_email:secret:edit RAILS_ENV=production EDITOR=vim
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Write raw secret
Write new secret content by providing it on `STDIN`.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
echo -e "password: 'examplepassword'" | sudo gitlab-rake gitlab:incoming_email:secret:write
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the incoming email password. For more information,
read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-incoming-emails).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
sudo docker exec -t <container name> /bin/bash
echo -e "password: 'examplepassword'" | gitlab-rake gitlab:incoming_email:secret:write
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
echo -e "password: 'examplepassword'" | bundle exec rake gitlab:incoming_email:secret:write RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Secrets examples
diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md
index 13a384049bdf24c3b34f5e9e5d49dc613cd03c63..00f5faee9d94e1d1b71a011e8f516c86db74a075 100644
--- a/doc/administration/raketasks/ldap.md
+++ b/doc/administration/raketasks/ldap.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: LDAP Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following are LDAP-related Rake tasks.
@@ -39,19 +42,25 @@ rake gitlab:ldap:check[50]
## Run a group sync
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following task runs a [group sync](../auth/ldap/ldap_synchronization.md#group-sync) immediately.
This is valuable when you'd like to update all configured group memberships against LDAP without
waiting for the next scheduled group sync to be run.
-NOTE:
+{{< alert type="note" >}}
+
If you'd like to change the frequency at which a group sync is performed,
[adjust the cron schedule](../auth/ldap/ldap_synchronization.md#adjust-ldap-group-sync-schedule)
instead.
+{{< /alert >}}
+
- Linux package installations:
```shell
@@ -86,11 +95,14 @@ main:
`main` is the LDAP server ID. Together, the unique provider is `ldapmain`.
-WARNING:
+{{< alert type="warning" >}}
+
If you input an incorrect new provider, users cannot sign in. If this happens,
run the task again with the incorrect provider as the `old_provider` and the
correct provider as the `new_provider`.
+{{< /alert >}}
+
- Linux package installations:
```shell
diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md
index bee047129eee37f87d288c21b7b88a1bdbbadef7..1af5556079d323c8cf50a360bcab111aa8f9c80b 100644
--- a/doc/administration/raketasks/maintenance.md
+++ b/doc/administration/raketasks/maintenance.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Maintenance Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides Rake tasks for general maintenance.
@@ -78,9 +81,12 @@ Gitaly
## Show GitLab license information
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This command shows information about your [GitLab license](../license.md) and
how many seats are used. It is only available on GitLab Enterprise
@@ -300,9 +306,12 @@ clear it.
To clear all exclusive leases:
-WARNING:
+{{< alert type="warning" >}}
+
Don't run it while GitLab or Sidekiq is running
+{{< /alert >}}
+
```shell
sudo gitlab-rake gitlab:exclusive_lease:clear
```
@@ -378,13 +387,19 @@ Starting with GitLab 17.1, migrations are executed in an
## Rebuild database indexes
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature is experimental, and isn't enabled by default. Use caution when
running in a production environment, and run during off-peak times.
+{{< /alert >}}
+
Database indexes can be rebuilt regularly to reclaim space and maintain healthy
levels of index bloat over time. Reindexing can also be run as a
[regular cron job](https://docs.gitlab.com/omnibus/settings/database.html#automatic-database-reindexing).
@@ -448,7 +463,11 @@ To determine if there are any differences:
## Check the database for schema inconsistencies
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390719) in GitLab 15.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390719) in GitLab 15.11.
+
+{{< /history >}}
This Rake task checks the database schema for any inconsistencies and prints them in the terminal.
This task is a diagnostic tool to be used under the guidance of GitLab Support.
diff --git a/doc/administration/raketasks/praefect.md b/doc/administration/raketasks/praefect.md
index 10f99f0453fa1aa92fb0c4561ec77b8c1804d5ae..0a2921b7f1ccd2bc6e97cdf927f57716d88c1d44 100644
--- a/doc/administration/raketasks/praefect.md
+++ b/doc/administration/raketasks/praefect.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Praefect Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Rake tasks are available for projects that have been created on Praefect storage. See the
[Praefect documentation](../gitaly/praefect.md) for information on configuring Praefect.
diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md
index e7f9eeeba8ac2ae47ac5ef496c01e23b105cf74d..f0b6672d764de8d8406ac27639fcf2d481619256 100644
--- a/doc/administration/raketasks/project_import_export.md
+++ b/doc/administration/raketasks/project_import_export.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project import and export Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides Rake tasks for [project import and export](../../user/project/settings/import_export.md).
@@ -30,21 +33,25 @@ Parameters:
| `project_path` | string | yes | Project path |
| `archive_path` | string | yes | Path to the exported project tarball you want to import |
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
gitlab-rake "gitlab:import_export:import[root, group/subgroup, testingprojectimport, /path/to/file.tar.gz]"
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
bundle exec rake "gitlab:import_export:import[root, group/subgroup, testingprojectimport, /path/to/file.tar.gz]" RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Export large projects
diff --git a/doc/administration/raketasks/service_desk_email.md b/doc/administration/raketasks/service_desk_email.md
index 9efdbbff63a2ba69d3de5a7eba70e605d7cba465..586b2741dc6b604a965c0fd5c797948fa2fd19d2 100644
--- a/doc/administration/raketasks/service_desk_email.md
+++ b/doc/administration/raketasks/service_desk_email.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Service Desk email Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9.
+
+{{< /history >}}
The following are Service Desk email-related Rake tasks.
@@ -21,32 +28,40 @@ GitLab can use [Service Desk email](../../user/project/service_desk/configure.md
Show the contents of the current Service Desk email secrets.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake gitlab:service_desk_email:secret:show
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the Service Desk email password. For more information,
read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
sudo docker exec -t <container name> gitlab:service_desk_email:secret:show
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
bundle exec rake gitlab:service_desk_email:secret:show RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Example output
@@ -59,64 +74,80 @@ user: 'service-desk-email@mail.example.com'
Opens the secret contents in your editor, and writes the resulting content to the encrypted secret file when you exit.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the Service Desk email password. For more information,
read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
sudo docker exec -t <container name> gitlab:service_desk_email:secret:edit EDITOR=editor
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
bundle exec rake gitlab:service_desk_email:secret:edit RAILS_ENV=production EDITOR=vim
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Write raw secret
Write new secret content by providing it on `STDIN`.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
echo -e "password: 'examplepassword'" | sudo gitlab-rake gitlab:service_desk_email:secret:write
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the Service Desk email password. For more information,
read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
sudo docker exec -t <container name> /bin/bash
echo -e "password: 'examplepassword'" | gitlab-rake gitlab:service_desk_email:secret:write
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
echo -e "password: 'examplepassword'" | bundle exec rake gitlab:service_desk_email:secret:write RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Secrets examples
diff --git a/doc/administration/raketasks/smtp.md b/doc/administration/raketasks/smtp.md
index fc4c76311b0ab6cce337cad3e8ef60768d0a7d61..3a55e579f4a3b6a0cbc2e29cdf63bd10ec0cb4bc 100644
--- a/doc/administration/raketasks/smtp.md
+++ b/doc/administration/raketasks/smtp.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: SMTP Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The following are SMTP-related Rake tasks.
diff --git a/doc/administration/raketasks/tokens/_index.md b/doc/administration/raketasks/tokens/_index.md
index 6f52f146044941aff871f230cf4ff04eb5bc268e..4b76ac24f08ce693205cb85b5a49ee6a80517c97 100644
--- a/doc/administration/raketasks/tokens/_index.md
+++ b/doc/administration/raketasks/tokens/_index.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Access token Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467416) in GitLab 17.2.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467416) in GitLab 17.2.
+
+{{< /history >}}
## Analyze token expiration dates
@@ -20,15 +27,17 @@ year after those tokens were created.
To identify which tokens might have been affected by this migration, you can run a
Rake task that analyses all access tokens and displays the top ten most common expiration dates:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
gitlab-rake gitlab:tokens:analyze
```
- :::TabTitle Helm chart (Kubernetes)
+ {{< /tab >}}
+
+ {{< tab title="Helm chart (Kubernetes)" >}}
```shell
# Find the toolbox pod
@@ -36,20 +45,26 @@ Rake task that analyses all access tokens and displays the top ten most common e
kubectl exec -it <toolbox-pod-name> -- sh -c 'cd /srv/gitlab && bin/rake gitlab:tokens:analyze'
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
```shell
sudo docker exec -it <container_name> /bin/bash
gitlab-rake gitlab:tokens:analyze
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:tokens:analyze
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
This task analyzes all the access tokens and groups them by expiration date.
The left column shows the expiration date, and the right column shows how many tokens
@@ -94,15 +109,17 @@ Run the following Rake task to extend or remove expiration dates from tokens in
1. Run the tool:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
```shell
gitlab-rake gitlab:tokens:edit
```
- :::TabTitle Helm chart (Kubernetes)
+ {{< /tab >}}
+
+ {{< tab title="Helm chart (Kubernetes)" >}}
```shell
# Find the toolbox pod
@@ -110,20 +127,26 @@ Run the following Rake task to extend or remove expiration dates from tokens in
kubectl exec -it <toolbox-pod-name> -- sh -c 'cd /srv/gitlab && bin/rake gitlab:tokens:edit'
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
```shell
sudo docker exec -it <container_name> /bin/bash
gitlab-rake gitlab:tokens:edit
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
```shell
sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:tokens:edit
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
After the tool starts, it shows the output from the [analyze step](#analyze-token-expiration-dates)
plus an additional prompt about modifying the expiration dates:
diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md
index 596df83a4800f40f31351fd1fc21dd5bb4b272a9..7aac817d11e978a47a8130a5396650d73587f376 100644
--- a/doc/administration/raketasks/uploads/migrate.md
+++ b/doc/administration/raketasks/uploads/migrate.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Uploads migrate Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
There is a Rake task for migrating uploads between different storage types.
@@ -80,11 +83,14 @@ The Rake task uses three parameters to find uploads to migrate:
| `model_class` | string | Type of the model to migrate from. |
| `mount_point` | string/symbol | Name of the model's column the uploader is mounted on. |
-NOTE:
+{{< alert type="note" >}}
+
These parameters are mainly internal to the structure of GitLab, you may want to refer to the task list
instead below. After running these individual tasks, we recommend that you run the [all-in-one Rake task](#all-in-one-rake-task)
to migrate any uploads not included in the listed types.
+{{< /alert >}}
+
This task also accepts an environment variable which you can use to override
the default batch size:
@@ -94,9 +100,9 @@ the default batch size:
The following shows how to run `gitlab:uploads:migrate` for individual types of uploads.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
# gitlab-rake gitlab:uploads:migrate[uploader_class, model_class, mount_point]
@@ -124,7 +130,9 @@ gitlab-rake "gitlab:uploads:migrate[FileUploader, MergeRequest]"
gitlab-rake "gitlab:uploads:migrate[DesignManagement::DesignV432x230Uploader, DesignManagement::Action, :image_v432x230]"
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Use `RAILS_ENV=production` for every task.
@@ -154,19 +162,24 @@ sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, MergeReque
sudo -u git -H bundle exec rake "gitlab:uploads:migrate[DesignManagement::DesignV432x230Uploader, DesignManagement::Action]"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Migrate to local storage
If you need to disable [object storage](../../object_storage.md) for any reason, you must first
migrate your data out of object storage and back into your local storage.
-WARNING:
+{{< alert type="warning" >}}
+
**Extended downtime is required** so no new files are created in object storage during
the migration. A configuration setting to allow migrating
from object storage to local files with only a brief moment of downtime for configuration changes
is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30979).
+{{< /alert >}}
+
### All-in-one Rake task
GitLab provides a wrapper Rake task that migrates all uploaded files (for example, avatars, logos,
diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md
index df1103d263f79bd46befeef71fd5496ae47b192c..225480bbc42c5468830dfb4807b13c217413c7ea 100644
--- a/doc/administration/raketasks/uploads/sanitize.md
+++ b/doc/administration/raketasks/uploads/sanitize.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Uploads sanitize Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
EXIF data is automatically stripped from JPG or TIFF image uploads.
diff --git a/doc/administration/read_only_gitlab.md b/doc/administration/read_only_gitlab.md
index b7449dc4ba5884b57c91631807b482d19e5f7b74..9d8b7d89c20787ad230ce6755b2fe5060311055f 100644
--- a/doc/administration/read_only_gitlab.md
+++ b/doc/administration/read_only_gitlab.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Place GitLab into a read-only state
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
The recommended method to place GitLab in a read-only state is to enable
[maintenance mode](maintenance_mode/_index.md).
+{{< /alert >}}
+
In some cases, you might want to place GitLab under a read-only state.
The configuration for doing so depends on your desired outcome.
diff --git a/doc/administration/redis/_index.md b/doc/administration/redis/_index.md
index b3a99a00f38a071c6002905823e2c0b5d4b566b2..204085396f4ae0a6fc795bbd2e0133233bf154da 100644
--- a/doc/administration/redis/_index.md
+++ b/doc/administration/redis/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configuring Redis for scaling
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Based on your infrastructure setup and how you have installed GitLab, there are
multiple ways to configure Redis.
diff --git a/doc/administration/redis/replication_and_failover.md b/doc/administration/redis/replication_and_failover.md
index 9b920188592c6ccc5445eb6ddbc1f8e02ba57d9d..683a9a1b7bf1eaa72385a9a3b27c27d03aadcbeb 100644
--- a/doc/administration/redis/replication_and_failover.md
+++ b/doc/administration/redis/replication_and_failover.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Redis replication and failover with the Linux package
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This documentation is for the Linux package. To use your own
non-bundled Redis, see [Redis replication and failover providing your own instance](replication_and_failover_external.md).
@@ -162,9 +165,12 @@ is not achieved (see the odd number of nodes requirement above). In that case,
a new attempt is made after the amount of time defined in
`sentinel['failover_timeout']` (in milliseconds).
-NOTE:
+{{< alert type="note" >}}
+
We can see where `sentinel['failover_timeout']` is defined later.
+{{< /alert >}}
+
The `failover_timeout` variable has a lot of different use cases. According to
the official documentation:
@@ -194,11 +200,14 @@ It is assumed that you have installed GitLab and all its components from scratch
If you already have Redis installed and running, read how to
[switch from a single-machine installation](#switching-from-an-existing-single-machine-installation).
-NOTE:
+{{< alert type="note" >}}
+
Redis nodes (both primary and replica) need the same password defined in
`redis['password']`. At any time during a failover the Sentinels can
reconfigure a node and change its status from primary to replica and vice versa.
+{{< /alert >}}
+
### Requirements
The requirements for a Redis setup are the following:
@@ -277,11 +286,14 @@ If you fail to replicate first, you may loose data (unprocessed background jobs)
1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-NOTE:
+{{< alert type="note" >}}
+
You can specify multiple roles like sentinel and Redis as:
`roles ['redis_sentinel_role', 'redis_master_role']`.
Read more about [roles](https://docs.gitlab.com/omnibus/roles/).
+{{< /alert >}}
+
### Step 2. Configuring the replica Redis instances
1. SSH into the **replica** Redis server.
@@ -335,11 +347,14 @@ Read more about [roles](https://docs.gitlab.com/omnibus/roles/).
1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
1. Go through the steps again for all the other replica nodes.
-NOTE:
+{{< alert type="note" >}}
+
You can specify multiple roles like sentinel and Redis as:
`roles ['redis_sentinel_role', 'redis_master_role']`.
Read more about [roles](https://docs.gitlab.com/omnibus/roles/).
+{{< /alert >}}
+
These values don't have to be changed again in `/etc/gitlab/gitlab.rb` after
a failover, as the nodes are managed by the Sentinels, and even after a
`gitlab-ctl reconfigure`, they get their configuration restored by
@@ -347,9 +362,12 @@ the same Sentinels.
### Step 3. Configuring the Redis Sentinel instances
-NOTE:
+{{< alert type="note" >}}
+
[Support for Sentinel password authentication](https://gitlab.com/gitlab-org/gitlab/-/issues/235938) was introduced in GitLab 16.1.
+{{< /alert >}}
+
Now that the Redis servers are all set up, let's configure the Sentinel
servers.
@@ -470,10 +488,13 @@ the correct credentials for the Sentinel nodes.
While it doesn't require a list of all Sentinel nodes, in case of a failure,
it needs to access at least one of the listed.
-NOTE:
+{{< alert type="note" >}}
+
The following steps should be performed in the GitLab application server
which ideally should not have Redis or Sentinels on it for a HA setup.
+{{< /alert >}}
+
1. SSH into the server where the GitLab application is installed.
1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
@@ -728,11 +749,14 @@ To make this work with Sentinel:
sudo gitlab-ctl reconfigure
```
-NOTE:
+{{< alert type="note" >}}
+
For each persistence class, GitLab defaults to using the
configuration specified in `gitlab_rails['redis_sentinels']` unless
overridden by the previously described settings.
+{{< /alert >}}
+
### Control running services
In the previous example, we've used `redis_sentinel_role` and
@@ -782,7 +806,11 @@ You can find the relevant attributes defined in [`gitlab_rails.rb`](https://gitl
### Control startup behavior
-> - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/6646) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/6646) in GitLab 15.10.
+
+{{< /history >}}
To prevent the bundled Redis service from starting at boot or restarting after changing its configuration:
@@ -805,7 +833,11 @@ to ensure the node starts and restarts as expected during operation.
### Control replica configuration
-> - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/6646) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/6646) in GitLab 15.10.
+
+{{< /history >}}
To prevent the `replicaof` line from rendering in the Redis configuration file:
diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md
index ce50786f4e76eb2ff9e89cc540d76b4d639da64a..a4d13425a99e3e60046ca50ca25dcb3b92872297 100644
--- a/doc/administration/redis/replication_and_failover_external.md
+++ b/doc/administration/redis/replication_and_failover_external.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Redis replication and failover providing your own instance
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you're hosting GitLab on a cloud provider, you can optionally use a managed
service for Redis. For example, AWS offers ElastiCache that runs Redis.
diff --git a/doc/administration/redis/standalone.md b/doc/administration/redis/standalone.md
index 2bb496f95e7b160cd2476d9694d43d7881d07f15..8b5db5329795219e2b487df2bc277d9543230e6a 100644
--- a/doc/administration/redis/standalone.md
+++ b/doc/administration/redis/standalone.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Standalone Redis using the Linux package
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The Linux package can be used to configure a standalone Redis server.
In this configuration, Redis is not scaled, and represents a single
diff --git a/doc/administration/redis/troubleshooting.md b/doc/administration/redis/troubleshooting.md
index 3eafa9e142db0b281f743c65a5274e8c18816535..d67f761c2b5970a834562bf18d93735cec9f85b4 100644
--- a/doc/administration/redis/troubleshooting.md
+++ b/doc/administration/redis/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Redis
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
There are a lot of moving parts that must be taken care carefully
in order for the HA setup to work as expected.
@@ -136,10 +139,13 @@ To make sure your configuration is correct:
redis-cli -h localhost -p 6379 DEBUG sleep 20
```
- WARNING:
+ {{< alert type="warning" >}}
+
This action affects services, and takes the instance down for up to 20 seconds. If successful,
it should recover after that.
+ {{< /alert >}}
+
1. Then back in the Rails console from the first step, run:
```ruby
diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md
index 2609521a3ae454c894843767c6c2c6e2b36f7c19..46ab8744a3734b26723d991555d154113f47e969 100644
--- a/doc/administration/reference_architectures/10k_users.md
+++ b/doc/administration/reference_architectures/10k_users.md
@@ -5,19 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Reference architecture: Up to 200 RPS or 10,000 users'
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page describes the GitLab reference architecture designed to target a peak load of 200 requests per second (RPS), the typical peak load of up to 10,000 users, both manual and automated, based on real data.
For a full list of reference architectures, see
[Available reference architectures](_index.md#available-reference-architectures).
-NOTE:
+{{< alert type="note" >}}
+
Before deploying this architecture it's recommended to read through the [main documentation](_index.md) first,
specifically the [Before you start](_index.md#before-you-start) and [Deciding which architecture to use](_index.md#deciding-which-architecture-to-start-with) sections.
+{{< /alert >}}
+
> - **Target load:** API: 200 RPS, Web: 20 RPS, Git (Pull): 20 RPS, Git (Push): 4 RPS
> - **High Availability:** Yes ([Praefect](#configure-praefect-postgresql) needs a third-party PostgreSQL solution for HA)
> - **Cost calculator template:** [See cost calculator templates section](_index.md#cost-calculator-templates)
@@ -60,9 +66,12 @@ specifically the [Before you start](_index.md#before-you-start) and [Deciding wh
such as like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) can only be run on one node, which is handled better in Kubernetes.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 10k
skinparam linetype ortho
@@ -432,9 +441,12 @@ Refer to your preferred Load Balancer's documentation for further guidance.
Next, we set up the Consul servers.
-NOTE:
+{{< alert type="note" >}}
+
Consul must be deployed in an odd number of 3 nodes or more. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.11`: Consul 1
@@ -717,10 +729,13 @@ before proceeding.
Now that the PostgreSQL servers are all set up, let's configure PgBouncer
for tracking and handling reads/writes to the primary database.
-NOTE:
+{{< alert type="note" >}}
+
PgBouncer is single threaded and doesn't significantly benefit from an increase in CPU cores.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.31`: PgBouncer 1
@@ -816,12 +831,17 @@ Using [Redis](https://redis.io/) in scalable environment is possible using a **P
topology with a [Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/) service to watch and automatically
start the failover procedure.
-NOTE:
+{{< alert type="note" >}}
+
Redis clusters must each be deployed in an odd number of 3 nodes or more. This is to ensure Redis Sentinel can take votes as part of a quorum. This does not apply when configuring Redis externally, such as a cloud provider service.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Redis is primarily single threaded and doesn't significantly benefit from an increase in CPU cores. For this size of architecture it's strongly recommended having separate Cache and Persistent instances as specified to achieve optimum performance.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
Redis requires authentication if used with Sentinel. See
[Redis Security](https://redis.io/docs/latest/operate/rc/security/) documentation for more
@@ -1176,11 +1196,14 @@ are supported and can be added if needed.
repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being
designated the primary, and failover occurs automatically if the primary node goes down.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management.
Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/_index.md#before-deploying-gitaly-cluster).
@@ -1294,13 +1317,16 @@ There are many third-party solutions for PostgreSQL HA. The solution selected mu
- A static IP for all connections that doesn't change on failover.
- [`LISTEN`](https://www.postgresql.org/docs/12/sql-listen.html) SQL functionality must be supported.
-NOTE:
+{{< alert type="note" >}}
+
With a third-party setup, it's possible to colocate Praefect's database on the same server as
the main [GitLab](#provide-your-own-postgresql-instance) database as a convenience unless
you are using Geo, where separate database instances are required for handling replication correctly.
In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be
minimal.
+{{< /alert >}}
+
A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal)
and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default from
[14.4.0](https://docs.gitlab.com/17.3/ee/update/versions/gitlab_14_changes.html#1440).
@@ -1358,9 +1384,12 @@ This is how this would work with a Linux package PostgreSQL setup:
Praefect is the router and transaction manager for Gitaly Cluster and all connections to Gitaly go through
it. This section details how to configure it.
-NOTE:
+{{< alert type="note" >}}
+
Consul must be deployed in an odd number of 3 nodes or more. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
Praefect requires several secret tokens to secure communications across the Cluster:
- `<praefect_external_token>`: Used for repositories hosted on your Gitaly cluster and can only be accessed by Gitaly clients that carry this token.
@@ -1388,8 +1417,11 @@ To configure the Praefect nodes, on each one:
on the page.
1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect:
- NOTE:
- You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+ {{< alert type="note" >}}
+
+You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+
+ {{< /alert >}}
<!--
Updates to example must be made at:
@@ -1513,11 +1545,14 @@ To configure the Praefect nodes, on each one:
The [Gitaly](../gitaly/_index.md) server nodes that make up the cluster have
requirements that are dependent on data and load.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Due to Gitaly having notable input and output requirements, we strongly
recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs
should have a throughput of at least 8,000
@@ -1758,18 +1793,25 @@ Sidekiq requires connection to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
If you find that the environment's Sidekiq job processing is slow with long queues
you can scale it accordingly. Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
When configuring additional GitLab functionality such as Container Registry, SAML, or LDAP,
update the Sidekiq configuration in addition to the Rails configuration.
Refer to the [external Sidekiq documentation](../sidekiq/_index.md) for more information.
+{{< /alert >}}
- `10.6.0.101`: Sidekiq 1
- `10.6.0.102`: Sidekiq 2
@@ -1923,10 +1965,13 @@ Rails requires connections to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.111`: GitLab application 1
@@ -2256,16 +2301,22 @@ Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts
documentation for setup instructions including guidance on what GitLab secrets to sync
between Kubernetes and the backend components.
-NOTE:
+{{< alert type="note" >}}
+
This is an **advanced** setup. Running services in Kubernetes is well known
to be complex. **This setup is only recommended** if you have strong working
knowledge and experience in Kubernetes. The rest of this
section assumes this.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
**Gitaly Cluster is not supported to be run in Kubernetes**.
Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details.
+{{< /alert >}}
+
### Cluster topology
The following tables and diagram detail the hybrid environment using the same formats
@@ -2320,9 +2371,12 @@ services where applicable):
However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 10k
skinparam linetype ortho
@@ -2460,5 +2514,8 @@ After following this guide you should now have a fresh GitLab environment with c
You may want to configure additional optional features of GitLab depending on your requirements. See [Steps after installing GitLab](../../install/next_steps.md) for more information.
-NOTE:
+{{< alert type="note" >}}
+
Depending on your environment and requirements, additional hardware requirements or adjustments may be required to set up additional features as desired. Refer to the individual pages for more information.
+
+{{< /alert >}}
diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md
index 9153e73d2b6c7237bb5b271467c926852de7fb10..fdb787962f8636ee4c5be059b2478397695199da 100644
--- a/doc/administration/reference_architectures/1k_users.md
+++ b/doc/administration/reference_architectures/1k_users.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Reference architecture: Up to 20 RPS or 1,000 users'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This reference architecture targets a peak load of 20 requests per second (RPS). Based on real data, this load typically corresponds to up to 1,000 users, which includes both manual and automated interactions.
@@ -75,11 +78,14 @@ monitor .[#7FFFD4,norank]--> redis
Before starting, see the [requirements](_index.md#requirements) for reference architectures.
-WARNING:
+{{< alert type="warning" >}}
+
**The node's specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads), it might *significantly* impact the performance of the environment.**
If this applies to you, [further adjustments might be required](_index.md#scaling-an-environment). See the linked documentation and reach out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
## Testing methodology
The 1k architecture is designed to cover a large majority of workflows. It is regularly
@@ -107,9 +113,12 @@ or [external object storage service](../object_storage.md). It improves performa
## Configure advanced search
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can leverage Elasticsearch and [enable advanced search](../../integration/advanced_search/elasticsearch.md)
for faster, more advanced code search across your entire GitLab instance.
@@ -133,5 +142,8 @@ For environments that serve fewer users or a lower RPS, you can lower the node s
Now you have a fresh GitLab environment with core functionality configured accordingly. You might want to configure additional optional GitLab features depending on your requirements. See [Steps after installing GitLab](../../install/next_steps.md) for more information.
-NOTE:
+{{< alert type="note" >}}
+
Depending on your environment and requirements, additional hardware requirements or adjustments may be required to set up additional features. See the individual pages for more information.
+
+{{< /alert >}}
diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md
index f1e22e8a623b5860cb8b46abc7cdc95fb3cd559b..1b200fb345c6a902e9978ede2ab748388ccfc864 100644
--- a/doc/administration/reference_architectures/25k_users.md
+++ b/doc/administration/reference_architectures/25k_users.md
@@ -5,19 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Reference architecture: Up to 500 RPS or 25,000 users'
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page describes the GitLab reference architecture designed to target a peak load of 500 requests per second (RPS) - The typical peak load of up to 25,000 users, both manual and automated, based on real data.
For a full list of reference architectures, see
[Available reference architectures](_index.md#available-reference-architectures).
-NOTE:
+{{< alert type="note" >}}
+
Before deploying this architecture it's recommended to read through the [main documentation](_index.md) first,
specifically the [Before you start](_index.md#before-you-start) and [Deciding which architecture to use](_index.md#deciding-which-architecture-to-start-with) sections.
+{{< /alert >}}
+
> - **Target load:** API: 500 RPS, Web: 50 RPS, Git (Pull): 50 RPS, Git (Push): 10 RPS
> - **High Availability:** Yes ([Praefect](#configure-praefect-postgresql) needs a third-party PostgreSQL solution for HA)
> - **Cost calculator template:** [See cost calculator templates section](_index.md#cost-calculator-templates)
@@ -60,9 +66,12 @@ specifically the [Before you start](_index.md#before-you-start) and [Deciding wh
such as like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) can only be run on one node, which is handled better in Kubernetes.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 25k
skinparam linetype ortho
@@ -436,9 +445,12 @@ Refer to your preferred Load Balancer's documentation for further guidance.
Next, we set up the Consul servers.
-NOTE:
+{{< alert type="note" >}}
+
Consul must be deployed in an odd number of 3 nodes or more. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.11`: Consul 1
@@ -721,10 +733,13 @@ before proceeding.
Now that the PostgreSQL servers are all set up, let's configure PgBouncer
for tracking and handling reads/writes to the primary database.
-NOTE:
+{{< alert type="note" >}}
+
PgBouncer is single threaded and doesn't significantly benefit from an increase in CPU cores.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.31`: PgBouncer 1
@@ -820,12 +835,17 @@ Using [Redis](https://redis.io/) in scalable environment is possible using a **P
topology with a [Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/) service to watch and automatically
start the failover procedure.
-NOTE:
+{{< alert type="note" >}}
+
Redis clusters must each be deployed in an odd number of 3 nodes or more. This is to ensure Redis Sentinel can take votes as part of a quorum. This does not apply when configuring Redis externally, such as a cloud provider service.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Redis is primarily single threaded and doesn't significantly benefit from an increase in CPU cores. For this size of architecture it's strongly recommended having separate Cache and Persistent instances as specified to achieve optimum performance.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
Redis requires authentication if used with Sentinel. See
[Redis Security](https://redis.io/docs/latest/operate/rc/security/) documentation for more
@@ -1184,11 +1204,14 @@ are supported and can be added if needed.
repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being
designated the primary, and failover occurs automatically if the primary node goes down.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management.
Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/_index.md#before-deploying-gitaly-cluster).
@@ -1302,13 +1325,16 @@ There are many third-party solutions for PostgreSQL HA. The solution selected mu
- A static IP for all connections that doesn't change on failover.
- [`LISTEN`](https://www.postgresql.org/docs/12/sql-listen.html) SQL functionality must be supported.
-NOTE:
+{{< alert type="note" >}}
+
With a third-party setup, it's possible to colocate Praefect's database on the same server as
the main [GitLab](#provide-your-own-postgresql-instance) database as a convenience unless
you are using Geo, where separate database instances are required for handling replication correctly.
In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be
minimal.
+{{< /alert >}}
+
A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal)
and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default from
[14.4.0](https://docs.gitlab.com/17.3/ee/update/versions/gitlab_14_changes.html#1440).
@@ -1364,9 +1390,12 @@ This is how this would work with a Linux package PostgreSQL setup:
Praefect is the router and transaction manager for Gitaly Cluster and all connections to Gitaly go through
it. This section details how to configure it.
-NOTE:
+{{< alert type="note" >}}
+
Praefect must be deployed in an odd number of 3 nodes or more. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
Praefect requires several secret tokens to secure communications across the Cluster:
- `<praefect_external_token>`: Used for repositories hosted on your Gitaly cluster and can only be accessed by Gitaly clients that carry this token.
@@ -1394,8 +1423,11 @@ To configure the Praefect nodes, on each one:
on the page.
1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect:
- NOTE:
- You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+ {{< alert type="note" >}}
+
+You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+
+ {{< /alert >}}
<!--
Updates to example must be made at:
@@ -1519,11 +1551,14 @@ To configure the Praefect nodes, on each one:
The [Gitaly](../gitaly/_index.md) server nodes that make up the cluster have
requirements that are dependent on data and load.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Due to Gitaly having notable input and output requirements, we strongly
recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs
should have a throughput of at least 8,000
@@ -1764,18 +1799,25 @@ Sidekiq requires connection to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
If you find that the environment's Sidekiq job processing is slow with long queues
you can scale it accordingly. Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
When configuring additional GitLab functionality such as Container Registry, SAML, or LDAP,
update the Sidekiq configuration in addition to the Rails configuration.
Refer to the [external Sidekiq documentation](../sidekiq/_index.md) for more information.
+{{< /alert >}}
- `10.6.0.101`: Sidekiq 1
- `10.6.0.102`: Sidekiq 2
@@ -1929,10 +1971,13 @@ Rails requires connections to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.111`: GitLab application 1
@@ -2264,16 +2309,22 @@ Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts
documentation for setup instructions including guidance on what GitLab secrets to sync
between Kubernetes and the backend components.
-NOTE:
+{{< alert type="note" >}}
+
This is an **advanced** setup. Running services in Kubernetes is well known
to be complex. **This setup is only recommended** if you have strong working
knowledge and experience in Kubernetes. The rest of this
section assumes this.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
**Gitaly Cluster is not supported to be run in Kubernetes**.
Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details.
+{{< /alert >}}
+
### Cluster topology
The following tables and diagram detail the hybrid environment using the same formats
@@ -2327,9 +2378,12 @@ services where applicable):
However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 25k
skinparam linetype ortho
@@ -2467,5 +2521,8 @@ After following this guide you should now have a fresh GitLab environment with c
You may want to configure additional optional features of GitLab depending on your requirements. See [Steps after installing GitLab](../../install/next_steps.md) for more information.
-NOTE:
+{{< alert type="note" >}}
+
Depending on your environment and requirements, additional hardware requirements or adjustments may be required to set up additional features as desired. Refer to the individual pages for more information.
+
+{{< /alert >}}
diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md
index ab2e0ae6aa5124c92e11f0f756f25f9f7c5540c7..04633ca649f543150d81cf3a6108f3368211c0b0 100644
--- a/doc/administration/reference_architectures/2k_users.md
+++ b/doc/administration/reference_architectures/2k_users.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Reference architecture: Up to 40 RPS or 2,000 users'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page describes the GitLab reference architecture designed to target a peak load of 40 requests per second (RPS), the typical peak load of up to 2,000 users, both manual and automated, based on real data.
@@ -49,9 +52,12 @@ For a full list of reference architectures, see
such as like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) can only be run on one node, which is handled better in Kubernetes.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to deploy them over multiple availability zones for resilience if desired.
+{{< /alert >}}
+
```plantuml
@startuml 2k
skinparam linetype ortho
@@ -354,10 +360,13 @@ are supported and can be added if needed.
In this section, you'll be guided through configuring an external Redis instance
to be used with GitLab.
-NOTE:
+{{< alert type="note" >}}
+
Redis is primarily single threaded and doesn't significantly benefit from an increase in CPU cores.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
### Provide your own Redis instance
You can optionally use a [third party external service for the Redis instance](../redis/replication_and_failover_external.md#redis-as-a-managed-service-in-a-cloud-provider) with the following guidance:
@@ -423,11 +432,14 @@ are supported and can be added if needed.
[Gitaly](../gitaly/_index.md) server node requirements are dependent on data size,
specifically the number of projects and those projects' sizes.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Due to Gitaly having notable input and output requirements, we strongly
recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs
should have a throughput of at least 8,000
@@ -448,11 +460,14 @@ Be sure to note the following items:
to restrict access to the Gitaly server. Another option is to
[use TLS](#gitaly-tls-support).
-NOTE:
+{{< alert type="note" >}}
+
The token referred to throughout the Gitaly documentation is an arbitrary
password selected by the administrator. This token is unrelated to tokens
created for the GitLab API or other similar web API tokens.
+{{< /alert >}}
+
The following procedure describes how to configure a single Gitaly server named
`gitaly1.internal` with the secret token `gitalysecret`. We assume your GitLab
installation has two repository storages: `default` and `storage1`.
@@ -465,8 +480,11 @@ To configure the Gitaly server, on the server node you want to use for Gitaly:
1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure
storage paths, enable the network listener, and to configure the token:
- NOTE:
- You can't remove the `default` entry from `gitaly['configuration'][:storage]` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+ {{< alert type="note" >}}
+
+You can't remove the `default` entry from `gitaly['configuration'][:storage]` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+
+ {{< /alert >}}
<!--
Updates to example must be made at:
@@ -560,12 +578,15 @@ nodes (including the Gitaly node using the certificate) and on all client nodes
that communicate with it following the procedure described in
[GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl/#install-custom-public-certificates).
-NOTE:
+{{< alert type="note" >}}
+
The self-signed certificate must specify the address you use to access the
Gitaly server. If you are addressing the Gitaly server by a hostname, add it as a Subject Alternative
Name. If you are addressing the Gitaly server by its IP address, you must add it
as a Subject Alternative Name to the certificate.
+{{< /alert >}}
+
It's possible to configure Gitaly servers with both an unencrypted listening
address (`listen_addr`) and an encrypted listening address (`tls_listen_addr`)
at the same time. This allows you to do a gradual transition from unencrypted to
@@ -619,14 +640,19 @@ Sidekiq requires connection to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
If you find that the environment's Sidekiq job processing is slow with long queues
you can scale it accordingly. Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
When configuring additional GitLab functionality such as Container Registry, SAML, or LDAP,
update the Sidekiq configuration in addition to the Rails configuration.
Refer to the [external Sidekiq documentation](../sidekiq/_index.md) for more information.
+{{< /alert >}}
To configure the Sidekiq server, on the server node you want to use for Sidekiq:
@@ -1067,9 +1093,12 @@ While sharing the job logs through NFS is supported, it's recommended to avoid t
## Configure advanced search
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can leverage Elasticsearch and [enable advanced search](../../integration/advanced_search/elasticsearch.md)
for faster, more advanced code search across your entire GitLab instance.
@@ -1106,20 +1135,28 @@ Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts
documentation for setup instructions including guidance on what GitLab secrets to sync
between Kubernetes and the backend components.
-NOTE:
+{{< alert type="note" >}}
+
This is an **advanced** setup. Running services in Kubernetes is well known
to be complex. **This setup is only recommended** if you have strong working
knowledge and experience in Kubernetes. The rest of this
section assumes this.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The 2,000 reference architecture is not a highly-available setup. To achieve HA,
you can follow a modified [3K or 60 RPS reference architecture](3k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative).
+{{< /alert >}}
+
+{{< alert type="warning" >}}
-WARNING:
**Gitaly Cluster is not supported to be run in Kubernetes**.
Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details.
+{{< /alert >}}
+
### Cluster topology
The following tables and diagram detail the hybrid environment using the same formats
@@ -1161,9 +1198,12 @@ services where applicable):
3. Should be run on reputable Cloud Provider or Self Managed solutions. See [Configure the object storage](#configure-the-object-storage) for more information.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 2k
skinparam linetype ortho
@@ -1266,5 +1306,8 @@ After following this guide you should now have a fresh GitLab environment with c
You may want to configure additional optional features of GitLab depending on your requirements. See [Steps after installing GitLab](../../install/next_steps.md) for more information.
-NOTE:
+{{< alert type="note" >}}
+
Depending on your environment and requirements, additional hardware requirements or adjustments may be required to set up additional features as desired. Refer to the individual pages for more information.
+
+{{< /alert >}}
diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md
index 8c7ab80305265176d35c4a28cd4a1ec972b001d6..29ef2bac0806e7ab7dc42d01cfab748b308640a0 100644
--- a/doc/administration/reference_architectures/3k_users.md
+++ b/doc/administration/reference_architectures/3k_users.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Reference architecture: Up to 60 RPS or 3,000 users'
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page describes the GitLab reference architecture designed to target a peak load of 60 requests per second (RPS), the typical peak load of up to 3,000 users, both manual and automated, based on real data.
@@ -58,9 +61,12 @@ For a full list of reference architectures, see
such as like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) can only be run on one node, which is handled better in Kubernetes.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 3k
skinparam linetype ortho
@@ -422,9 +428,12 @@ Refer to your preferred Load Balancer's documentation for further guidance.
Next, we set up the Consul servers.
-NOTE:
+{{< alert type="note" >}}
+
Consul must be deployed in an odd number of 3 nodes or more. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.11`: Consul 1
@@ -707,10 +716,13 @@ before proceeding.
Now that the PostgreSQL servers are all set up, let's configure PgBouncer
for tracking and handling reads/writes to the primary database.
-NOTE:
+{{< alert type="note" >}}
+
PgBouncer is single threaded and doesn't significantly benefit from an increase in CPU cores.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
The following IPs are used as an example:
- `10.6.0.31`: PgBouncer 1
@@ -823,12 +835,17 @@ Using [Redis](https://redis.io/) in scalable environment is possible using a **P
topology with a [Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/) service to watch and automatically
start the failover procedure.
-NOTE:
+{{< alert type="note" >}}
+
Redis clusters must each be deployed in an odd number of 3 nodes or more. This is to ensure Redis Sentinel can take votes as part of a quorum. This does not apply when configuring Redis externally, such as a cloud provider service.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Redis is primarily single threaded and doesn't significantly benefit from an increase in CPU cores.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
Redis requires authentication if used with Sentinel. See
[Redis Security](https://redis.io/docs/latest/operate/rc/security/) documentation for more
@@ -1015,11 +1032,14 @@ are supported and can be added if needed.
repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being
designated the primary, and failover occurs automatically if the primary node goes down.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management.
Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/_index.md#before-deploying-gitaly-cluster).
@@ -1132,13 +1152,16 @@ There are many third-party solutions for PostgreSQL HA. The solution selected mu
- A static IP for all connections that doesn't change on failover.
- [`LISTEN`](https://www.postgresql.org/docs/12/sql-listen.html) SQL functionality must be supported.
-NOTE:
+{{< alert type="note" >}}
+
With a third-party setup, it's possible to colocate Praefect's database on the same server as
the main [GitLab](#provide-your-own-postgresql-instance) database as a convenience unless
you are using Geo, where separate database instances are required for handling replication correctly.
In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be
minimal.
+{{< /alert >}}
+
A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal)
and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default from
[14.4.0](https://docs.gitlab.com/17.3/ee/update/versions/gitlab_14_changes.html#1440).
@@ -1194,9 +1217,12 @@ This is how this would work with a Linux package PostgreSQL setup:
Praefect is the router and transaction manager for Gitaly Cluster and all connections to Gitaly go through
it. This section details how to configure it.
-NOTE:
+{{< alert type="note" >}}
+
Praefect must be deployed in an odd number of 3 nodes or more. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
Praefect requires several secret tokens to secure communications across the Cluster:
- `<praefect_external_token>`: Used for repositories hosted on your Gitaly cluster and can only be accessed by Gitaly clients that carry this token.
@@ -1224,8 +1250,11 @@ To configure the Praefect nodes, on each one:
on the page.
1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect:
- NOTE:
- You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+ {{< alert type="note" >}}
+
+You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+
+ {{< /alert >}}
<!--
Updates to example must be made at:
@@ -1349,11 +1378,14 @@ To configure the Praefect nodes, on each one:
The [Gitaly](../gitaly/_index.md) server nodes that make up the cluster have
requirements that are dependent on data and load.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Due to Gitaly having notable input and output requirements, we strongly
recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs
should have a throughput of at least 8,000
@@ -1598,18 +1630,25 @@ Sidekiq requires connection to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
If you find that the environment's Sidekiq job processing is slow with long queues
you can scale it accordingly. Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
When configuring additional GitLab functionality such as Container Registry, SAML, or LDAP,
update the Sidekiq configuration in addition to the Rails configuration.
Refer to the [external Sidekiq documentation](../sidekiq/_index.md) for more information.
+{{< /alert >}}
The following IPs will be used as an example:
@@ -1771,10 +1810,13 @@ Rails requires connections to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
+{{< /alert >}}
+
On each node perform the following:
1. [Download and install](https://about.gitlab.com/install/) the Linux
@@ -2119,9 +2161,12 @@ required. Each component has various considerations and rules to follow, and the
meets all of these. Smaller versions of this architecture will be fundamentally the same,
but with smaller performance requirements, the following modifications are supported as follows:
-NOTE:
+{{< alert type="note" >}}
+
If not stated below, no other modifications are supported for lower use counts.
+{{< /alert >}}
+
- Lowering node specs: Depending on your user count, you can lower all suggested node specs as desired. However, it's recommended that you don't go lower than the [general requirements](../../install/requirements.md).
- Combining select nodes: The following specific components are supported to be combined onto the same nodes to reduce complexity at the cost of some performance:
- GitLab Rails and Sidekiq: Sidekiq nodes can be removed, and the component instead enabled on the GitLab Rails nodes.
@@ -2156,16 +2201,22 @@ Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts
documentation for setup instructions including guidance on what GitLab secrets to sync
between Kubernetes and the backend components.
-NOTE:
+{{< alert type="note" >}}
+
This is an **advanced** setup. Running services in Kubernetes is well known
to be complex. **This setup is only recommended** if you have strong working
knowledge and experience in Kubernetes. The rest of this
section assumes this.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
**Gitaly Cluster is not supported to be run in Kubernetes**.
Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details.
+{{< /alert >}}
+
### Cluster topology
The following tables and diagram detail the hybrid environment using the same formats
@@ -2218,9 +2269,12 @@ services where applicable):
However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 3k
skinparam linetype ortho
@@ -2355,5 +2409,8 @@ After following this guide you should now have a fresh GitLab environment with c
You may want to configure additional optional features of GitLab depending on your requirements. See [Steps after installing GitLab](../../install/next_steps.md) for more information.
-NOTE:
+{{< alert type="note" >}}
+
Depending on your environment and requirements, additional hardware requirements or adjustments may be required to set up additional features as desired. Refer to the individual pages for more information.
+
+{{< /alert >}}
diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md
index bf71fae30fcb6ed80bbee75e3ab0366ddeba6a24..662f5d8314ca1d88338830a1ae6532f18a13be04 100644
--- a/doc/administration/reference_architectures/50k_users.md
+++ b/doc/administration/reference_architectures/50k_users.md
@@ -5,19 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Reference architecture: Up to 1000 RPS or 50,000 users'
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page describes the GitLab reference architecture designed to target a peak load of 1000 requests per second (RPS), the typical peak load of up to 50,000 users, both manual and automated, based on real data.
For a full list of reference architectures, see
[Available reference architectures](_index.md#available-reference-architectures).
-NOTE:
+{{< alert type="note" >}}
+
Before deploying this architecture it's recommended to read through the [main documentation](_index.md) first,
specifically the [Before you start](_index.md#before-you-start) and [Deciding which architecture to use](_index.md#deciding-which-architecture-to-start-with) sections.
+{{< /alert >}}
+
> - **Target load:** API: 1000 RPS, Web: 100 RPS, Git (Pull): 100 RPS, Git (Push): 20 RPS
> - **High Availability:** Yes ([Praefect](#configure-praefect-postgresql) needs a third-party PostgreSQL solution for HA)
> - **Cost calculator template:** [See cost calculator templates section](_index.md#cost-calculator-templates)
@@ -59,9 +65,12 @@ specifically the [Before you start](_index.md#before-you-start) and [Deciding wh
such as like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) can only be run on one node, which is handled better in Kubernetes.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 50k
skinparam linetype ortho
@@ -440,9 +449,12 @@ Refer to your preferred Load Balancer's documentation for further guidance.
Next, we set up the Consul servers.
-NOTE:
+{{< alert type="note" >}}
+
Consul must be deployed in an odd number of 3 nodes or more. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.11`: Consul 1
@@ -726,10 +738,13 @@ before proceeding.
Now that the PostgreSQL servers are all set up, let's configure PgBouncer
for tracking and handling reads/writes to the primary database.
-NOTE:
+{{< alert type="note" >}}
+
PgBouncer is single threaded and doesn't significantly benefit from an increase in CPU cores.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.31`: PgBouncer 1
@@ -825,13 +840,18 @@ Using [Redis](https://redis.io/) in scalable environment is possible using a **P
topology with a [Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/) service to watch and automatically
start the failover procedure.
-NOTE:
+{{< alert type="note" >}}
+
Redis clusters must each be deployed in an odd number of 3 nodes or more. This is to ensure Redis Sentinel can take votes as part of a quorum. This does not apply when configuring Redis externally, such as a cloud provider service.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Redis is primarily single threaded and doesn't significantly benefit from increasing CPU cores.
For this size of architecture it's strongly recommended having separate Cache and Persistent instances as specified to achieve optimum performance at this scale.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
Redis requires authentication if used with Sentinel. See
[Redis Security](https://redis.io/docs/latest/operate/rc/security/) documentation for more
@@ -1191,11 +1211,14 @@ Advanced [configuration options](https://docs.gitlab.com/omnibus/settings/redis.
repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being
designated the primary, and failover occurs automatically if the primary node goes down.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management.
Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/_index.md#before-deploying-gitaly-cluster).
@@ -1309,13 +1332,16 @@ There are many third-party solutions for PostgreSQL HA. The solution selected mu
- A static IP for all connections that doesn't change on failover.
- [`LISTEN`](https://www.postgresql.org/docs/12/sql-listen.html) SQL functionality must be supported.
-NOTE:
+{{< alert type="note" >}}
+
With a third-party setup, it's possible to colocate Praefect's database on the same server as
the main [GitLab](#provide-your-own-postgresql-instance) database as a convenience unless
you are using Geo, where separate database instances are required for handling replication correctly.
In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be
minimal.
+{{< /alert >}}
+
A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal)
and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default from
[14.4.0](https://docs.gitlab.com/17.3/ee/update/versions/gitlab_14_changes.html#1440).
@@ -1371,9 +1397,12 @@ This is how this would work with a Linux package PostgreSQL setup:
Praefect is the router and transaction manager for Gitaly Cluster and all connections to Gitaly go through
it. This section details how to configure it.
-NOTE:
+{{< alert type="note" >}}
+
Praefect must be deployed in an odd number of 3 nodes or later. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
Praefect requires several secret tokens to secure communications across the Cluster:
- `<praefect_external_token>`: Used for repositories hosted on your Gitaly cluster and can only be accessed by Gitaly clients that carry this token.
@@ -1401,8 +1430,11 @@ To configure the Praefect nodes, on each one:
on the page.
1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect:
- NOTE:
- You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+ {{< alert type="note" >}}
+
+You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+
+ {{< /alert >}}
<!--
Updates to example must be made at:
@@ -1526,11 +1558,14 @@ To configure the Praefect nodes, on each one:
The [Gitaly](../gitaly/_index.md) server nodes that make up the cluster have
requirements that are dependent on data and load.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Due to Gitaly having notable input and output requirements, we strongly
recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs
should have a throughput of at least 8,000
@@ -1771,19 +1806,26 @@ Sidekiq requires connection to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
If you find that the environment's Sidekiq job processing is slow with long queues
you can scale it accordingly.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
When configuring additional GitLab functionality such as Container Registry, SAML, or LDAP,
update the Sidekiq configuration in addition to the Rails configuration.
Refer to the [external Sidekiq documentation](../sidekiq/_index.md) for more information.
+{{< /alert >}}
- `10.6.0.101`: Sidekiq 1
- `10.6.0.102`: Sidekiq 2
@@ -1940,10 +1982,13 @@ Rails requires connections to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.111`: GitLab application 1
@@ -2279,16 +2324,22 @@ Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts
documentation for setup instructions including guidance on what GitLab secrets to sync
between Kubernetes and the backend components.
-NOTE:
+{{< alert type="note" >}}
+
This is an **advanced** setup. Running services in Kubernetes is well known
to be complex. **This setup is only recommended** if you have strong working
knowledge and experience in Kubernetes. The rest of this
section assumes this.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
**Gitaly Cluster is not supported to be run in Kubernetes**.
Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details.
+{{< /alert >}}
+
### Cluster topology
The following tables and diagram detail the hybrid environment using the same formats
@@ -2342,9 +2393,12 @@ services where applicable):
However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 50k
skinparam linetype ortho
@@ -2482,5 +2536,8 @@ After following this guide you should now have a fresh GitLab environment with c
You may want to configure additional optional features of GitLab depending on your requirements. See [Steps after installing GitLab](../../install/next_steps.md) for more information.
-NOTE:
+{{< alert type="note" >}}
+
Depending on your environment and requirements, additional hardware requirements or adjustments may be required to set up additional features as desired. Refer to the individual pages for more information.
+
+{{< /alert >}}
diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md
index 99d6f7cab4a9504e01faedc169e1eb8cb9691579..c2e24087ef39e2e4989bd3ddec78bdc3c47bde72 100644
--- a/doc/administration/reference_architectures/5k_users.md
+++ b/doc/administration/reference_architectures/5k_users.md
@@ -5,19 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Reference architecture: Up to 100 RPS or 5,000 users'
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page describes the GitLab reference architecture designed to target a peak load of 100 requests per second (RPS) - The typical peak load of up to 5,000 users, both manual and automated, based on real data.
For a full list of reference architectures, see
[Available reference architectures](_index.md#available-reference-architectures).
-NOTE:
+{{< alert type="note" >}}
+
Before deploying this architecture it's recommended to read through the [main documentation](_index.md) first,
specifically the [Before you start](_index.md#before-you-start) and [Deciding which architecture to use](_index.md#deciding-which-architecture-to-start-with) sections.
+{{< /alert >}}
+
> - **Target load:** API: 100 RPS, Web: 10 RPS, Git (Pull): 10 RPS, Git (Push): 2 RPS
> - **High Availability:** Yes ([Praefect](#configure-praefect-postgresql) needs a third-party PostgreSQL solution for HA)
> - **Cost calculator template:** [See cost calculator templates section](_index.md#cost-calculator-templates)
@@ -58,9 +64,12 @@ specifically the [Before you start](_index.md#before-you-start) and [Deciding wh
such as like [migrations](#gitlab-rails-post-configuration) and [Mailroom](../incoming_email.md) can only be run on one node, which is handled better in Kubernetes.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 5k
skinparam linetype ortho
@@ -422,9 +431,12 @@ Refer to your preferred Load Balancer's documentation for further guidance.
Next, we set up the Consul servers.
-NOTE:
+{{< alert type="note" >}}
+
Consul must be deployed in an odd number of 3 nodes or more. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
The following IPs will be used as an example:
- `10.6.0.11`: Consul 1
@@ -707,10 +719,13 @@ before proceeding.
Now that the PostgreSQL servers are all set up, let's configure PgBouncer
for tracking and handling reads/writes to the primary database.
-NOTE:
+{{< alert type="note" >}}
+
PgBouncer is single threaded and doesn't significantly benefit from an increase in CPU cores.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
+
The following IPs are used as an example:
- `10.6.0.31`: PgBouncer 1
@@ -823,12 +838,17 @@ Using [Redis](https://redis.io/) in scalable environment is possible using a **P
topology with a [Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/) service to watch and automatically
start the failover procedure.
-NOTE:
+{{< alert type="note" >}}
+
Redis clusters must each be deployed in an odd number of 3 nodes or more. This is to ensure Redis Sentinel can take votes as part of a quorum. This does not apply when configuring Redis externally, such as a cloud provider service.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Redis is primarily single threaded and doesn't significantly benefit from an increase in CPU cores.
Refer to the [scaling documentation](_index.md#scaling-an-environment) for more information.
+{{< /alert >}}
Redis requires authentication if used with Sentinel. See
[Redis Security](https://redis.io/docs/latest/operate/rc/security/) documentation for more
@@ -1015,11 +1035,14 @@ are supported and can be added if needed.
repositories. In this configuration, every Git repository is stored on every Gitaly node in the cluster, with one being
designated the primary, and failover occurs automatically if the primary node goes down.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management.
Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/_index.md#before-deploying-gitaly-cluster).
@@ -1133,13 +1156,16 @@ There are many third-party solutions for PostgreSQL HA. The solution selected mu
- A static IP for all connections that doesn't change on failover.
- [`LISTEN`](https://www.postgresql.org/docs/12/sql-listen.html) SQL functionality must be supported.
-NOTE:
+{{< alert type="note" >}}
+
With a third-party setup, it's possible to colocate Praefect's database on the same server as
the main [GitLab](#provide-your-own-postgresql-instance) database as a convenience unless
you are using Geo, where separate database instances are required for handling replication correctly.
In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be
minimal.
+{{< /alert >}}
+
A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal)
and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default from
[14.4.0](https://docs.gitlab.com/17.3/ee/update/versions/gitlab_14_changes.html#1440).
@@ -1195,9 +1221,12 @@ This is how this would work with a Linux package PostgreSQL setup:
Praefect is the router and transaction manager for Gitaly Cluster and all connections to Gitaly go through
it. This section details how to configure it.
-NOTE:
+{{< alert type="note" >}}
+
Praefect must be deployed in an odd number of 3 nodes or later. This is to ensure the nodes can take votes as part of a quorum.
+{{< /alert >}}
+
Praefect requires several secret tokens to secure communications across the Cluster:
- `<praefect_external_token>`: Used for repositories hosted on your Gitaly cluster and can only be accessed by Gitaly clients that carry this token.
@@ -1225,8 +1254,11 @@ To configure the Praefect nodes, on each one:
on the page.
1. Edit the `/etc/gitlab/gitlab.rb` file to configure Praefect:
- NOTE:
- You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+ {{< alert type="note" >}}
+
+You can't remove the `default` entry from `virtual_storages` because [GitLab requires it](../gitaly/configure_gitaly.md#gitlab-requires-a-default-repository-storage).
+
+ {{< /alert >}}
<!--
Updates to example must be made at:
@@ -1350,11 +1382,14 @@ To configure the Praefect nodes, on each one:
The [Gitaly](../gitaly/_index.md) server nodes that make up the cluster have
requirements that are dependent on data and load.
-WARNING:
+{{< alert type="warning" >}}
+
**Gitaly specifications are based on high percentiles of both usage patterns and repository sizes in good health.**
**However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact the performance of the environment and further adjustments may be required.**
If this applies to you, we strongly recommended referring to the linked documentation as well as reaching out to your [Customer Success Manager](https://handbook.gitlab.com/job-families/sales/customer-success-management/) or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Due to Gitaly having notable input and output requirements, we strongly
recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs
should have a throughput of at least 8,000
@@ -1595,19 +1630,26 @@ Sidekiq requires connections to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
If you find that the environment's Sidekiq job processing is slow with long queues,
more nodes can be added as required. You can also tune your Sidekiq nodes to
run [multiple Sidekiq processes](../sidekiq/extra_sidekiq_processes.md).
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
When configuring additional GitLab functionality such as Container Registry, SAML, or LDAP,
update the Sidekiq configuration in addition to the Rails configuration.
Refer to the [external Sidekiq documentation](../sidekiq/_index.md) for more information.
+{{< /alert >}}
- `10.6.0.71`: Sidekiq 1
- `10.6.0.72`: Sidekiq 2
@@ -1768,10 +1810,13 @@ Rails requires connections to the [Redis](#configure-redis),
[PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances.
It also requires a connection to [Object Storage](#configure-the-object-storage) as recommended.
-NOTE:
+{{< alert type="note" >}}
+
[Because it's recommended to use Object storage](../object_storage.md) instead of NFS for data objects, the following
examples include the Object storage configuration.
+{{< /alert >}}
+
On each node perform the following:
1. [Download and install](https://about.gitlab.com/install/) the Linux
@@ -2129,16 +2174,22 @@ Refer to the Helm charts [Advanced configuration](https://docs.gitlab.com/charts
documentation for setup instructions including guidance on what GitLab secrets to sync
between Kubernetes and the backend components.
-NOTE:
+{{< alert type="note" >}}
+
This is an **advanced** setup. Running services in Kubernetes is well known
to be complex. **This setup is only recommended** if you have strong working
knowledge and experience in Kubernetes. The rest of this
section assumes this.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
**Gitaly Cluster is not supported to be run in Kubernetes**.
Refer to [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127) for more details.
+{{< /alert >}}
+
### Cluster topology
The following tables and diagram detail the hybrid environment using the same formats
@@ -2191,9 +2242,12 @@ services where applicable):
However, if you have [large monorepos](_index.md#large-monorepos) (larger than several gigabytes) or [additional workloads](_index.md#additional-workloads) these can *significantly* impact Git and Gitaly performance and further adjustments will likely be required.
<!-- markdownlint-enable MD029 -->
-NOTE:
+{{< alert type="note" >}}
+
For all PaaS solutions that involve configuring instances, it's recommended to implement a minimum of three nodes in three different availability zones to align with resilient cloud architecture practices.
+{{< /alert >}}
+
```plantuml
@startuml 5k
skinparam linetype ortho
@@ -2328,5 +2382,8 @@ After following this guide you should now have a fresh GitLab environment with c
You may want to configure additional optional features of GitLab depending on your requirements. See [Steps after installing GitLab](../../install/next_steps.md) for more information.
-NOTE:
+{{< alert type="note" >}}
+
Depending on your environment and requirements, additional hardware requirements or adjustments may be required to set up additional features as desired. Refer to the individual pages for more information.
+
+{{< /alert >}}
diff --git a/doc/administration/reference_architectures/_index.md b/doc/administration/reference_architectures/_index.md
index 5e642d2a80f5c8a601f810f72511697807d4c6f2..d24bea0c84e0671624269e60a8985b76efb06f94 100644
--- a/doc/administration/reference_architectures/_index.md
+++ b/doc/administration/reference_architectures/_index.md
@@ -1,14 +1,17 @@
---
stage: Systems
group: Distribution
-description: Recommended deployments at scale.
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
+description: Recommended deployments at scale.
title: Reference architectures
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The GitLab reference architectures provide recommended scalable and elastic environment sizes.
@@ -18,9 +21,12 @@ The following reference architectures are available as recommended starting poin
The architectures are named in terms of peak load, based on user count or requests per second (RPS). RPS is calculated based on average real data.
-NOTE:
+{{< alert type="note" >}}
+
Each architecture is designed to be [scalable and elastic](#scaling-an-environment). They can be adjusted accordingly based on your workload, upwards or downwards. For example, some known heavy scenarios such as using [large monorepos](#large-monorepos) or notable [additional workloads](#additional-workloads).
+{{< /alert >}}
+
For details about what each reference architecture is tested against, see the **Testing Methodology** section of each page.
### GitLab package (Omnibus)
@@ -166,9 +172,12 @@ To determine which architecture to pick for the expected load, see the following
</tr>
</table>
-NOTE:
+{{< alert type="note" >}}
+
Before you select an initial architecture, review this section thoroughly. Consider other factors such as High Availability (HA) or use of large monorepos, as they may impact the choice beyond just RPS or user count.
+{{< /alert >}}
+
#### If in doubt, start large, monitor, and then scale down
If you're uncertain about the required environment size, consider starting with a larger size, [monitoring](#monitoring) it, and then [scaling down](#scaling-an-environment) accordingly if the metrics support your situation.
@@ -313,9 +322,12 @@ If you want, you can select a newer machine type series and have improved perfor
Additionally, ARM CPUs are supported for Linux package environments and for any [cloud provider services](#cloud-provider-services).
-NOTE:
+{{< alert type="note" >}}
+
Any "burstable" instance types are not recommended due to inconsistent performance.
+{{< /alert >}}
+
### Supported disk types
Most standard disk types are expected to work for GitLab. However, be aware of the following specific call-outs:
@@ -346,9 +358,12 @@ Their presence and how they are used can put a significant strain on the entire
The performance implications are largely software in nature. Additional hardware resources lead to diminishing returns.
-WARNING:
+{{< alert type="warning" >}}
+
If this applies to you, we strongly recommend you follow the linked documentation and reach out to your GitLab representative or our [Support team](https://about.gitlab.com/support/) for further guidance.
+{{< /alert >}}
+
Large monorepos come with notable cost. If you have such a repository,
follow these guidance to ensure good performance and to keep costs in check:
@@ -421,13 +436,16 @@ can be set up using the Linux package as the specifications reflect. For more de
## Recommended cloud providers and services
-NOTE:
+{{< alert type="note" >}}
+
The following lists are non-exhaustive. Other cloud providers not listed
here may work with the same specifications, but they have not been validated.
For the cloud provider services not listed here,
use caution, as each implementation can be notably different.
Test thoroughly before using them in production.
+{{< /alert >}}
+
The following architectures are recommended for the following cloud providers based on testing and real life usage:
<table>
@@ -638,9 +656,12 @@ The above RPS targets were selected based on real customer data of total environ
### How to interpret the results
-NOTE:
+{{< alert type="note" >}}
+
Read our blog post on [how our QA team leverages GitLab performance testing tool](https://about.gitlab.com/blog/2020/02/18/how-were-building-up-performance-testing-of-gitlab/).
+{{< /alert >}}
+
Testing is done publicly, and all results are shared.
The following table details the testing done against the architectures along with the frequency and results. Additional testing is continuously evaluated, and the table is updated accordingly.
@@ -799,9 +820,12 @@ In this section you can find links to documentation for relevant areas and speci
The reference architectures are designed as a starting point, and are elastic and scalable throughout. You might want to adjust the environment for your specific needs after deployment for reasons such as additional performance capacity or reduced costs. This behavior is expected. Scaling can be done iteratively or wholesale to the next architecture size, if metrics suggest that a component is exhausted.
-NOTE:
+{{< alert type="note" >}}
+
If a component is continuously exhausting its given resources, reach out to our [Support team](https://about.gitlab.com/support/) before performing any significant scaling.
+{{< /alert >}}
+
For most components, vertical and horizontal scaling can be applied as usual. However, before doing so, be aware of the following caveats:
- When scaling Puma or Sidekiq vertically, the amount of workers must be adjusted to use the additional specifications. Puma is scaled automatically on the next reconfigure. However, you might have to [change Sidekiq configuration beforehand](../sidekiq/extra_sidekiq_processes.md#start-multiple-processes).
@@ -816,9 +840,12 @@ You should take an iterative approach when scaling downwards, to ensure there ar
In some cases, scaling a component significantly may result in knock on effects for downstream components, impacting performance. The architectures are designed with balance in mind to ensure components that depend on each other are congruent in terms of specifications. Notably scaling a component may result in additional throughput being passed to the other components it depends on. As a result, they may need to be scaled as well.
-NOTE:
+{{< alert type="note" >}}
+
The architectures have been designed to have elasticity to accommodate an upstream component being scaled. However, reach out to our [Support team](https://about.gitlab.com/support/) before you make any significant changes to your environment to be safe.
+{{< /alert >}}
+
The following components can impact others when they have been significantly scaled:
- Puma and Sidekiq - Notable scale ups of either Puma or Sidekiq workers will result in higher concurrent connections to the internal load balancer, PostgreSQL (via PgBouncer if present), Gitaly (via Praefect if present) and Redis respectively.
@@ -843,16 +870,22 @@ Upgrading a reference architecture environment is same as any other GitLab envir
The main [Upgrade GitLab](../../update/_index.md) section has detailed steps on how to approach this.
[Zero-downtime upgrades](#zero-downtime-upgrades) are also available.
-NOTE:
+{{< alert type="note" >}}
+
You should upgrade a reference architecture in the same order as you created it.
+{{< /alert >}}
+
### Monitoring
You can monitor your infrastructure and [GitLab](../monitoring/_index.md) using various options. See the selected monitoring solution's documentation for more information.
-NOTE:
+{{< alert type="note" >}}
+
GitLab application is bundled with [Prometheus and various Prometheus compatible exporters](../monitoring/prometheus/_index.md) that could be hooked into your solution.
+{{< /alert >}}
+
## Update history
The following is a history of notable updates for reference architectures (2021-01-01 onward, ascending order). We aim to update it at least once per quarter.
diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md
index 8bda12c9af40461166c69de7ba42b0eeb35a7b66..ffb767fe7f8162928f478001a1c24b196262744a 100644
--- a/doc/administration/reply_by_email.md
+++ b/doc/administration/reply_by_email.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Reply by email
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab can be set up to allow users to comment on issues and merge requests by
replying to notification emails.
diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md
index 1bcaa6b6f81f97d89b607637f0556c96f8d6f4e3..0a1095da19b2ba81f9c2fdc318592bc4253dcabe 100644
--- a/doc/administration/reply_by_email_postfix_setup.md
+++ b/doc/administration/reply_by_email_postfix_setup.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Set up Postfix for incoming email
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This document takes you through the steps of setting up a basic Postfix mail
server with IMAP authentication on Ubuntu, to be used with [incoming email](incoming_email.md).
@@ -94,8 +97,11 @@ The instructions make the assumption that you are using the email address `incom
quit
```
- NOTE:
- The `.` is a literal period on its own line.
+ {{< alert type="note" >}}
+
+The `.` is a literal period on its own line.
+
+ {{< /alert >}}
If you receive an error after entering `rcpt to: incoming@localhost`
then your Postfix `my_network` configuration is not correct. The error will
@@ -275,9 +281,12 @@ Courier, which we install later to add IMAP authentication, requires mailboxes t
quit
```
- NOTE:
+ {{< alert type="note" >}}
+
The `.` is a literal period on its own line.
+ {{< /alert >}}
+
1. Check if the `incoming` user received the email:
```shell
diff --git a/doc/administration/reporting/git_abuse_rate_limit.md b/doc/administration/reporting/git_abuse_rate_limit.md
index 88539870041083cca08b8693004b482782206a47..d93f6f4c248fac1d1c8da5813a79cd67672b87b4 100644
--- a/doc/administration/reporting/git_abuse_rate_limit.md
+++ b/doc/administration/reporting/git_abuse_rate_limit.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Git abuse rate limit (administration)
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../feature_flags.md) named `git_abuse_rate_limit_feature_flag`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/394996) in GitLab 15.11. Feature flag `git_abuse_rate_limit_feature_flag` removed.
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../feature_flags.md) named `git_abuse_rate_limit_feature_flag`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/394996) in GitLab 15.11. Feature flag `git_abuse_rate_limit_feature_flag` removed.
+
+{{< /history >}}
This is the administration documentation. For information about Git abuse rate limiting for a group, see the [group documentation](../../user/group/reporting/git_abuse_rate_limit.md).
diff --git a/doc/administration/reporting/ip_addr_restrictions.md b/doc/administration/reporting/ip_addr_restrictions.md
index 51b9715fbeb3f85a456103ae04fc8601701f074c..3e103f2459a66cba38b0a48348f810bc8ac30989 100644
--- a/doc/administration/reporting/ip_addr_restrictions.md
+++ b/doc/administration/reporting/ip_addr_restrictions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: IP address restrictions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
IP address restrictions help prevent malicious users hiding their activities behind multiple IP addresses.
@@ -16,10 +19,13 @@ specified limit is reached, any requests made by the user from a new IP address
IP addresses are cleared from the list when no further requests have been made by the user from the IP address in the specified time period.
-NOTE:
+{{< alert type="note" >}}
+
When a runner runs a CI/CD job as a particular user, the runner IP address is also stored against the user's list of
unique IP addresses. Therefore, the IP addresses per user limit should take into account the number of configured active runners.
+{{< /alert >}}
+
## Configure IP address restrictions
1. On the left sidebar, at the bottom, select **Admin**.
diff --git a/doc/administration/reporting/spamcheck.md b/doc/administration/reporting/spamcheck.md
index 0533334cd6b798186d6db65ea2a8264d15095eef..4511f3a95b4f2a821202037f6db8bf4cd717f3c7 100644
--- a/doc/administration/reporting/spamcheck.md
+++ b/doc/administration/reporting/spamcheck.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Spamcheck anti-spam service
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
Spamcheck is available to all tiers, but only on instances using GitLab Enterprise Edition (EE). For [licensing reasons](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6259#note_726605397), it is not included in the GitLab Community Edition (CE) package. You can [migrate from CE to EE](../../update/package/convert_to_ee.md).
+{{< /alert >}}
+
[Spamcheck](https://gitlab.com/gitlab-org/gl-security/security-engineering/security-automation/spam/spamcheck) is an anti-spam engine
developed by GitLab originally to combat rising amount of spam in GitLab.com,
and later made public to be used in GitLab Self-Managed instances.
@@ -50,7 +56,8 @@ Spamcheck is only available for package-based installations:
1. Leave **Spam Check API key** blank.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
In single-node instances, Spamcheck runs over `localhost`, and hence is running
in an unauthenticated mode. If on multi-node instances where GitLab runs on one
server and Spamcheck runs on another server listening over a public endpoint, it
@@ -60,6 +67,8 @@ example would be to use `JWT` authentication for this and specifying a bearer
token as the API key.
[Native authentication for Spamcheck is in the works](https://gitlab.com/gitlab-com/gl-security/engineering-and-research/automation-team/spam/spamcheck/-/issues/171).
+{{< /alert >}}
+
## Running Spamcheck over TLS
Spamcheck service on its own cannot communicate directly over TLS with GitLab.
diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md
index 21c8250581fbe07e0dec26d97db03565312a1078..1a75d9b0f572bd9fa7f14b3c1c2b80071806d661 100644
--- a/doc/administration/repository_checks.md
+++ b/doc/administration/repository_checks.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Repository checks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can use [`git fsck`](https://git-scm.com/docs/git-fsck) to verify the integrity of all data
committed to a repository. GitLab administrators can:
diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md
index 436bfe42df87f09713bf3690eba0348b5ca3f71b..5e5515421ad264342a41b20c99299f79dcb33548 100644
--- a/doc/administration/repository_storage_paths.md
+++ b/doc/administration/repository_storage_paths.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Repository storage
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab stores [repositories](../user/project/repository/_index.md) on repository storage. Repository
storage is either:
@@ -15,11 +18,14 @@ storage is either:
- Physical storage configured with a `gitaly_address` that points to a [Gitaly node](gitaly/_index.md).
- [Virtual storage](gitaly/_index.md#virtual-storage) that stores repositories on a Gitaly Cluster.
-WARNING:
+{{< alert type="warning" >}}
+
Repository storage could be configured as a `path` that points directly to the directory where the repositories are
stored. GitLab directly accessing a directory containing repositories is deprecated. You should configure GitLab to
access repositories through a physical or virtual storage.
+{{< /alert >}}
+
For more information on:
- Configuring Gitaly, see [Configure Gitaly](gitaly/configure_gitaly.md).
@@ -27,8 +33,12 @@ For more information on:
## Hashed storage
-> - Support for legacy storage, where repository paths were generated based on the project path, has been completely removed in GitLab 14.0.
-> - **Storage name** field [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128416) from **Gitaly storage name** and **Relative path** field [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128416) from **Gitaly relative path** in GitLab 16.3.
+{{< history >}}
+
+- Support for legacy storage, where repository paths were generated based on the project path, has been completely removed in GitLab 14.0.
+- **Storage name** field [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128416) from **Gitaly storage name** and **Relative path** field [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128416) from **Gitaly relative path** in GitLab 16.3.
+
+{{< /history >}}
Hashed storage stores projects on disk in a location based on a hash of the project's ID. This makes the folder
structure immutable and eliminates the need to synchronize state from URLs to disk structure. This means that renaming a
@@ -137,10 +147,13 @@ project. Object pool repositories are stored similarly to regular repositories i
"@pools/#{hash[0..1]}/#{hash[2..3]}/#{hash}.git"
```
-WARNING:
+{{< alert type="warning" >}}
+
Do not run `git prune` or `git gc` in object pool repositories, which are stored in the `@pools` directory.
This can cause data loss in the regular repositories that depend on the object pool.
+{{< /alert >}}
+
### Translate hashed object pool storage paths
To look up a project's object pool using a Rails console:
@@ -244,11 +257,14 @@ By default, if repository weights have not been configured earlier:
- `default` is weighted `100`.
- All other storages are weighted `0`.
-NOTE:
+{{< alert type="note" >}}
+
If all storage weights are `0` (for example, when `default` does not exist), GitLab attempts to
create new repositories on `default`, regardless of the configuration or if `default` exists.
See [the tracking issue](https://gitlab.com/gitlab-org/gitlab/-/issues/36175) for more information.
+{{< /alert >}}
+
## Move repositories
To move a repository to a different repository storage (for example, from `default` to `storage2`), use the
diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md
index c442a583d51a343756b37f1456dbf95552e8838d..9babe9c982279f589188624730385e6c90f58457 100644
--- a/doc/administration/restart_gitlab.md
+++ b/doc/administration/restart_gitlab.md
@@ -5,16 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: How to restart GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Depending on how you installed GitLab, there are different methods to restart
its services.
-NOTE:
+{{< alert type="note" >}}
+
A short downtime is expected for all methods.
+{{< /alert >}}
+
## Linux package installations
If you have used the [Linux package](https://about.gitlab.com/install/) to install GitLab,
diff --git a/doc/administration/review_abuse_reports.md b/doc/administration/review_abuse_reports.md
index f460a9c9fc0fd48438a534814eb2509c0372132e..0742d7270a5e1b81933b1fa402b631801066521b 100644
--- a/doc/administration/review_abuse_reports.md
+++ b/doc/administration/review_abuse_reports.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Review abuse reports
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
View and resolve abuse reports from GitLab users.
@@ -33,7 +36,11 @@ To find out more about reporting abuse, see
## Resolving abuse reports
-> - **Trust user** [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131102) in GitLab 16.4.
+{{< history >}}
+
+- **Trust user** [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131102) in GitLab 16.4.
+
+{{< /history >}}
To access abuse reports:
diff --git a/doc/administration/review_spam_logs.md b/doc/administration/review_spam_logs.md
index dcbdb3120ff8220b874a024cf2063d2d4c436798..c19bbd2c4198e866a46402cde89772d73f2d18bb 100644
--- a/doc/administration/review_spam_logs.md
+++ b/doc/administration/review_spam_logs.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Review spam logs
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab tracks user activity and flags certain behavior for potential spam.
@@ -15,7 +18,11 @@ In the **Admin** area, a GitLab administrator can view and resolve spam logs.
## Manage spam logs
-> - **Trust user** [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131812) in GitLab 16.5.
+{{< history >}}
+
+- **Trust user** [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131812) in GitLab 16.5.
+
+{{< /history >}}
View and resolve spam logs to moderate user activity in your instance.
@@ -23,7 +30,7 @@ To view spam logs:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Spam logs**.
-1. Optional. To resolve a spam log, select **More actions** (**{ellipsis_v}**), then **Remove user**, **Block user**, **Remove log**, or **Trust user**.
+1. Optional. To resolve a spam log, select **More actions** ({{< icon name="ellipsis_v" >}}), then **Remove user**, **Block user**, **Remove log**, or **Trust user**.
### Resolving spam logs
diff --git a/doc/administration/self_hosted_models/_index.md b/doc/administration/self_hosted_models/_index.md
index 3ab24a0908e8d2ad293ea3dd04e3131819ecb5ed..c9471c17f4b70ba3a86cfbd44fc9d2bb39d06dfd 100644
--- a/doc/administration/self_hosted_models/_index.md
+++ b/doc/administration/self_hosted_models/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo_self_hosted/_index.md'
-remove_date: '2025-05-05'
+redirect_to: ../gitlab_duo_self_hosted/_index.md
+remove_date: "2025-05-05"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/self_hosted_models/configuration_types.md b/doc/administration/self_hosted_models/configuration_types.md
index 3f0eb9793ce6fb0ef0094eeb3e8bf7cd92d2dd37..830d85bbb0db15ac1b8a30d04f678ecbaaf4b1a2 100644
--- a/doc/administration/self_hosted_models/configuration_types.md
+++ b/doc/administration/self_hosted_models/configuration_types.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo_self_hosted/configuration_types.md'
-remove_date: '2025-05-05'
+redirect_to: ../gitlab_duo_self_hosted/configuration_types.md
+remove_date: "2025-05-05"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/self_hosted_models/configure_duo_features.md b/doc/administration/self_hosted_models/configure_duo_features.md
index 826524c52776b9aeebee6a590560a67104f4e79f..8ed87ddbf13214c9076159185a351f624cf805f3 100644
--- a/doc/administration/self_hosted_models/configure_duo_features.md
+++ b/doc/administration/self_hosted_models/configure_duo_features.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo_self_hosted/configure_duo_features.md'
-remove_date: '2025-05-05'
+redirect_to: ../gitlab_duo_self_hosted/configure_duo_features.md
+remove_date: "2025-05-05"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/self_hosted_models/install_infrastructure.md b/doc/administration/self_hosted_models/install_infrastructure.md
index 3d699b15882a7c719bd9ac9899ec1a8f539b24cd..56e74147972cc92632e5a21a4510a7677a846ead 100644
--- a/doc/administration/self_hosted_models/install_infrastructure.md
+++ b/doc/administration/self_hosted_models/install_infrastructure.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo_self_hosted/_index.md'
-remove_date: '2025-01-22'
+redirect_to: ../gitlab_duo_self_hosted/_index.md
+remove_date: "2025-01-22"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/self_hosted_models/licensing_and_offerings.md b/doc/administration/self_hosted_models/licensing_and_offerings.md
index 3f0eb9793ce6fb0ef0094eeb3e8bf7cd92d2dd37..830d85bbb0db15ac1b8a30d04f678ecbaaf4b1a2 100644
--- a/doc/administration/self_hosted_models/licensing_and_offerings.md
+++ b/doc/administration/self_hosted_models/licensing_and_offerings.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo_self_hosted/configuration_types.md'
-remove_date: '2025-05-05'
+redirect_to: ../gitlab_duo_self_hosted/configuration_types.md
+remove_date: "2025-05-05"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/self_hosted_models/litellm_proxy_setup.md b/doc/administration/self_hosted_models/litellm_proxy_setup.md
index 8e14df9ae361cc0be974f4f8722fd53e94b245b3..506fdeddd2ffe88d932f32ad95ba01ecec8654fd 100644
--- a/doc/administration/self_hosted_models/litellm_proxy_setup.md
+++ b/doc/administration/self_hosted_models/litellm_proxy_setup.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'supported_llm_serving_platforms.md'
-remove_date: '2025-01-22'
+redirect_to: supported_llm_serving_platforms.md
+remove_date: "2025-01-22"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/self_hosted_models/logging.md b/doc/administration/self_hosted_models/logging.md
index 86597c78fe3970a52978c033206d976947056f87..9d340f8db0ed0847e64500d748d8e76877fc7e77 100644
--- a/doc/administration/self_hosted_models/logging.md
+++ b/doc/administration/self_hosted_models/logging.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo_self_hosted/logging.md'
-remove_date: '2025-05-05'
+redirect_to: ../gitlab_duo_self_hosted/logging.md
+remove_date: "2025-05-05"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/self_hosted_models/related_topics.md b/doc/administration/self_hosted_models/related_topics.md
index 6669994756ea6f9644a36371c9887c8434d49999..873e738f313d7ae130e3c2e78f8c7aba35d869eb 100644
--- a/doc/administration/self_hosted_models/related_topics.md
+++ b/doc/administration/self_hosted_models/related_topics.md
@@ -1,20 +1,27 @@
---
stage: AI-Powered
group: Custom Models
-description: Self-Hosted model setup Related topics
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
+description: Self-Hosted model setup Related topics
title: Self-Hosted model setup related topics
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Feature flag `ai_custom_model` removed in GitLab 17.8
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12972) in GitLab 17.1 [with a flag](../feature_flags.md) named `ai_custom_model`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/15176) in GitLab 17.6.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Feature flag `ai_custom_model` removed in GitLab 17.8
+{{< /history >}}
## AWS Bedrock
diff --git a/doc/administration/self_hosted_models/supported_llm_serving_platforms.md b/doc/administration/self_hosted_models/supported_llm_serving_platforms.md
index a43cf38ee130eaed3b6e28035ad4e7c983500a62..ae4216def14463595f3e4f62e035ef6ccd47ef1d 100644
--- a/doc/administration/self_hosted_models/supported_llm_serving_platforms.md
+++ b/doc/administration/self_hosted_models/supported_llm_serving_platforms.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo_self_hosted/supported_llm_serving_platforms.md'
-remove_date: '2025-05-05'
+redirect_to: ../gitlab_duo_self_hosted/supported_llm_serving_platforms.md
+remove_date: "2025-05-05"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/self_hosted_models/supported_models_and_hardware_requirements.md b/doc/administration/self_hosted_models/supported_models_and_hardware_requirements.md
index 2295bc150ef83ffd3de79c25f79908292c7a33ef..3cc99fdd7ec4b5733bec85ac672280ea66a1b170 100644
--- a/doc/administration/self_hosted_models/supported_models_and_hardware_requirements.md
+++ b/doc/administration/self_hosted_models/supported_models_and_hardware_requirements.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo_self_hosted/supported_models_and_hardware_requirements.md'
-remove_date: '2025-05-05'
+redirect_to: ../gitlab_duo_self_hosted/supported_models_and_hardware_requirements.md
+remove_date: "2025-05-05"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/self_hosted_models/troubleshooting.md b/doc/administration/self_hosted_models/troubleshooting.md
index 5129284a24bc3c532f0a229800fa9d3e3cddb8de..1b0b46ecb8e20766d865f1c2136f207f5f0e4562 100644
--- a/doc/administration/self_hosted_models/troubleshooting.md
+++ b/doc/administration/self_hosted_models/troubleshooting.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo_self_hosted/troubleshooting.md'
-remove_date: '2025-05-05'
+redirect_to: ../gitlab_duo_self_hosted/troubleshooting.md
+remove_date: "2025-05-05"
---
<!-- markdownlint-disable -->
diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md
index b355bf597e3c2b75f933c5681b5355e270b8a11d..362c999e5d985b55efd619b12da7f55931762544 100644
--- a/doc/administration/server_hooks.md
+++ b/doc/administration/server_hooks.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Git server hooks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/372991) from server hooks to Git server hooks in GitLab 15.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/372991) from server hooks to Git server hooks in GitLab 15.6.
+
+{{< /history >}}
Git server hooks (not to be confused with [system hooks](system_hooks.md) or [file hooks](file_hooks.md)) run custom logic
on the GitLab server. You can use them to run Git-related tasks such as:
@@ -36,11 +43,15 @@ If you don't have access to the `gitaly` command, alternatives to server hooks i
## Set server hooks for a repository
-::Tabs
+{{< tabs >}}
+
+{{< tab title="GitLab 15.11 and later" >}}
+
+{{< history >}}
-:::TabTitle GitLab 15.11 and later
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4629) in GitLab 15.11, `hooks set` command replaces direct file system access. Existing Git hooks don't need migrating for the `hooks set` command.
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4629) in GitLab 15.11, `hooks set` command replaces direct file system access. Existing Git hooks don't need migrating for the `hooks set` command.
+{{< /history >}}
Prerequisites:
@@ -75,7 +86,9 @@ To set server hooks for a repository:
If you implemented the server hook code correctly, it should execute when the Git hook is next triggered.
-:::TabTitle GitLab 15.10 and earlier
+{{< /tab >}}
+
+{{< tab title="GitLab 15.10 and earlier" >}}
To create server hooks for a repository:
@@ -106,7 +119,9 @@ To create server hooks for a repository:
If the server hook code is properly implemented, it should execute when the Git hook is next triggered.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Server hooks on a Gitaly Cluster
@@ -166,11 +181,15 @@ subdirectories.
## Remove server hooks for a repository
-::Tabs
+{{< tabs >}}
+
+{{< tab title="GitLab 15.11 and later" >}}
-:::TabTitle GitLab 15.11 and later
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4629) in GitLab 15.11, `hooks set` command replaces direct file system access.
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/4629) in GitLab 15.11, `hooks set` command replaces direct file system access.
+
+{{< /history >}}
Prerequisites:
@@ -182,14 +201,18 @@ To remove server hooks, pass an empty tarball to `hook set` to indicate that the
cat empty_hooks.tar | sudo -u git -- /opt/gitlab/embedded/bin/gitaly hooks set --storage <storage> --repository <relative path> --config <config path>
```
-:::TabTitle GitLab 15.10 and earlier
+{{< /tab >}}
+
+{{< tab title="GitLab 15.10 and earlier" >}}
To remove server hooks:
1. Go to the location of the repository on disk.
1. Delete the server hooks in the `custom_hooks` directory.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Chained server hooks
diff --git a/doc/administration/settings/_index.md b/doc/administration/settings/_index.md
index 6ae77fdae7591956fe2f296d133ba51bfe057b8d..bbe8a7f53b762c490a757b63b8f6e34098aafafb 100644
--- a/doc/administration/settings/_index.md
+++ b/doc/administration/settings/_index.md
@@ -1,14 +1,17 @@
---
stage: none
group: unassigned
-description: Product settings.
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
+description: Product settings.
title: Update your Admin area settings
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
As an instance administrator, you can manage the behavior of your
deployment.
diff --git a/doc/administration/settings/account_and_limit_settings.md b/doc/administration/settings/account_and_limit_settings.md
index daba651f13601fa6ecd27c17b3ccb747df93475e..6081c6bf3dea2b9ffb35ad9128a31a0927e16cfd 100644
--- a/doc/administration/settings/account_and_limit_settings.md
+++ b/doc/administration/settings/account_and_limit_settings.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Configure the maximum number of projects users can create on GitLab Self-Managed. Configure size limits for attachments, pushes, and repository size."
+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
+description: Configure the maximum number of projects users can create on GitLab Self-Managed. Configure size limits for attachments, pushes, and repository size.
title: Account and limit settings
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
## Default projects limit
@@ -40,7 +43,11 @@ can create in their personal namespace:
## Max attachment size
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/20061) from 10 MB to 100 MB in GitLab 15.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/20061) from 10 MB to 100 MB in GitLab 15.7.
+
+{{< /history >}}
The maximum file size for attachments in GitLab comments and replies is 100 MB.
To change the maximum attachment size:
@@ -66,7 +73,8 @@ You can change the maximum push size for your instance:
For GitLab.com push size limits, see [accounts and limit settings](../../user/gitlab_com/_index.md#account-and-limit-settings).
-NOTE:
+{{< alert type="note" >}}
+
When you [add files to a repository](../../user/project/repository/web_editor.md#create-a-file)
through the web UI, the maximum **attachment** size is the limiting factor. This happens
because the [web server](../../development/architecture.md#components)
@@ -74,6 +82,8 @@ must receive the file before GitLab can generate the commit.
Use [Git LFS](../../topics/git/lfs/_index.md) to add large files to a repository.
This setting does not apply when pushing Git LFS objects.
+{{< /alert >}}
+
## Personal access token prefix
You can specify a prefix for personal access tokens. You might use a prefix
@@ -99,9 +109,12 @@ You can also configure the prefix by using the
## Repository size limit
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Repositories in your GitLab instance can grow quickly, especially if you are
using LFS. Their size can grow exponentially, rapidly consuming available storage.
@@ -169,17 +182,24 @@ You can change how long users can remain signed in without activity.
1. Select **Save changes**.
1. Restart GitLab to apply the changes.
- WARNING:
+ {{< alert type="warning" >}}
+
Setting **Session duration (minutes)** to `0` breaks your GitLab instance.
For more information, see [issue 19469](https://gitlab.com/gitlab-org/gitlab/-/issues/19469).
+ {{< /alert >}}
+
If [Remember me](#turn-remember-me-on-or-off) is enabled, users' sessions can remain active for an indefinite period of time.
For details, see [cookies used for sign-in](../../user/profile/_index.md#cookies-used-for-sign-in).
### Turn **Remember me** on or off
-> - Enabling and disabling the **Remember me** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369133) in GitLab 16.0.
+{{< history >}}
+
+- Enabling and disabling the **Remember me** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369133) in GitLab 16.0.
+
+{{< /history >}}
Users can select the **Remember me** checkbox on sign-in. Their session remains active for an indefinite
period of time when accessed from that specific browser. Turn off this setting to expire sessions for
@@ -193,16 +213,26 @@ number of minutes of inactivity set when you [customize your session duration](#
### Customize session duration for Git Operations when 2FA is enabled
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296669) in GitLab 13.9 with a [flag](../feature_flags.md) named `two_factor_for_cli`. Disabled by default. This feature flag also affects [2FA for Git over SSH operations](../../security/two_factor_authentication.md#2fa-for-git-over-ssh-operations).
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296669) in GitLab 13.9 with a [flag](../feature_flags.md) named `two_factor_for_cli`. Disabled by default. This feature flag also affects [2FA for Git over SSH operations](../../security/two_factor_authentication.md#2fa-for-git-over-ssh-operations).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history. This feature is not ready for production use.
+{{< /alert >}}
+
GitLab administrators can choose to customize the session duration (in minutes) for Git operations
when 2FA is enabled. The default is 15 and this can be set to a value between 1 and 10080.
@@ -216,11 +246,18 @@ To set a limit on how long these sessions are valid:
## Require expiration dates for new access tokens
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/470192) in GitLab 17.3.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/470192) in GitLab 17.3.
+
+{{< /history >}}
Prerequisites:
@@ -251,12 +288,19 @@ When you require expiration dates for new access tokens:
## Allow top-level group Owners to create service accounts
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163726) in GitLab 17.5 [with a feature flag](../feature_flags.md) named `allow_top_level_group_owners_to_create_service_accounts` for GitLab Self-Managed. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172502) in GitLab 17.6. Feature flag `allow_top_level_group_owners_to_create_service_accounts` removed.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163726) in GitLab 17.5 [with a feature flag](../feature_flags.md) named `allow_top_level_group_owners_to_create_service_accounts` for GitLab Self-Managed. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172502) in GitLab 17.6. Feature flag `allow_top_level_group_owners_to_create_service_accounts` removed.
+
+{{< /history >}}
By default, in GitLab Self-Managed, top-level group Owners can not create service accounts. GitLab
administrators can allow top-level group Owners to create service accounts.
@@ -269,16 +313,26 @@ administrators can allow top-level group Owners to create service accounts.
## Limit the lifetime of SSH keys
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) the maximum allowable lifetime limit to an increased value of 400 days in GitLab 17.6 [with a flag](../feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+{{< /details >}}
+
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) the maximum allowable lifetime limit to an increased value of 400 days in GitLab 17.6 [with a flag](../feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the extended maximum allowable lifetime limit is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Users can optionally specify a lifetime for
[SSH keys](../../user/ssh.md).
This lifetime is not a requirement, and can be set to any arbitrary number of days.
@@ -308,21 +362,34 @@ After a lifetime for SSH keys is set, GitLab:
- Applies the lifetime restriction to existing SSH keys. Keys with no expiry or a lifetime
greater than the maximum immediately become invalid.
-NOTE:
+{{< alert type="note" >}}
+
When a user's SSH key becomes invalid they can delete and re-add the same key again.
+{{< /alert >}}
+
## Limit the lifetime of access tokens
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) the maximum allowable lifetime limit to an increased value of 400 days in GitLab 17.6 [with a flag](../feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) the maximum allowable lifetime limit to an increased value of 400 days in GitLab 17.6 [with a flag](../feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the extended maximum allowable lifetime limit is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Users can optionally specify a maximum lifetime in days for
access tokens, this includes [personal](../../user/profile/personal_access_tokens.md),
[group](../../user/group/settings/group_access_tokens.md), and [project](../../user/project/settings/project_access_tokens.md) access tokens.
@@ -363,9 +430,12 @@ After a lifetime for access tokens is set, GitLab:
## User OAuth applications setting
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Prerequisites:
@@ -385,11 +455,18 @@ To turn the **User OAuth applications** setting on or off:
## OAuth authorizations
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323615) in GitLab 17.8.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323615) in GitLab 17.8.
+
+{{< /history >}}
Prerequisites:
@@ -408,9 +485,12 @@ To turn this setting on or off:
## Disable user profile name changes
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To maintain integrity of user details in [audit events](../audit_event_reports.md),
GitLab administrators can prevent users from changing their profile name.
@@ -428,16 +508,26 @@ When selected, GitLab administrators can still update usernames in the
## Prevent users from creating organizations
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423302) in GitLab 16.7 [with a flag](../feature_flags.md) named `ui_for_organizations`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423302) in GitLab 16.7 [with a flag](../feature_flags.md) named `ui_for_organizations`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator
can [enable the feature flag](../feature_flags.md) named `ui_for_organizations`. On GitLab.com and GitLab Dedicated,
this feature is not available. This feature is not ready for production use.
+{{< /alert >}}
+
By default, users can create organizations. GitLab administrators can prevent users from creating organizations.
1. On the left sidebar, at the bottom, select **Admin**.
@@ -447,7 +537,11 @@ By default, users can create organizations. GitLab administrators can prevent us
## Prevent new users from creating top-level groups
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5.
+
+{{< /history >}}
By default, new users can create top-level groups. GitLab administrators can prevent new users from creating top-level groups:
@@ -463,7 +557,11 @@ By default, new users can create top-level groups. GitLab administrators can pre
## Prevent non-members from creating projects and groups
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/426279) in GitLab 16.8
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/426279) in GitLab 16.8
+
+{{< /history >}}
By default, users with the Guest role can create projects and groups.
GitLab administrators can prevent this behavior:
@@ -476,19 +574,29 @@ GitLab administrators can prevent this behavior:
## Prevent users from making their profiles private
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421310) in GitLab 17.1 [with a flag](../feature_flags.md) named `disallow_private_profiles`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427400) in GitLab 17.9. Feature flag `disallow_private_profiles` removed.
+
+{{< /history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421310) in GitLab 17.1 [with a flag](../feature_flags.md) named `disallow_private_profiles`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427400) in GitLab 17.9. Feature flag `disallow_private_profiles` removed.
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
By default, users can make their profiles private.
GitLab administrators can disable this setting to require all user profiles to be public.
This setting does not affect [internal users](../internal_users.md) (sometimes referred to as "bots").
@@ -512,7 +620,11 @@ When you re-enable this setting, the user's
## Set profiles of new users to private by default
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231301) in GitLab 15.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231301) in GitLab 15.8.
+
+{{< /history >}}
By default, newly created users have a public profile. GitLab administrators can set new users to have a private profile by default:
@@ -522,16 +634,26 @@ By default, newly created users have a public profile. GitLab administrators can
1. Select the **Make new users' profiles private by default** checkbox.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
If [**Allow users to make their profiles private**](#prevent-users-from-making-their-profiles-private) is disabled, this setting is also disabled.
+{{< /alert >}}
+
## Prevent users from deleting their accounts
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26053) in GitLab 16.1 [with a flag](../feature_flags.md) named `deleting_account_disabled_for_users`. Enabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26053) in GitLab 16.1 [with a flag](../feature_flags.md) named `deleting_account_disabled_for_users`. Enabled by default.
+{{< /history >}}
By default, users can delete their own accounts. GitLab administrators can prevent
users from deleting their own accounts:
diff --git a/doc/administration/settings/continuous_integration.md b/doc/administration/settings/continuous_integration.md
index bb9975aff17f97b1e562df5828ab26334955a4cc..4e3e245a63c35976c8d3ff3152c513ec17287065 100644
--- a/doc/administration/settings/continuous_integration.md
+++ b/doc/administration/settings/continuous_integration.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI/CD Admin area settings
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The [**Admin** area](_index.md) has the instance settings for CI/CD-related features,
including runners, job artifacts, and the package registry.
@@ -68,14 +71,18 @@ To enable a project runner for more than one project:
1. On the left sidebar, at the bottom, select **Admin**.
1. From the left sidebar, select **CI/CD > Runners**.
1. Select the runner you want to edit.
-1. In the upper-right corner, select **Edit** (**{pencil}**).
+1. In the upper-right corner, select **Edit** ({{< icon name="pencil" >}}).
1. Under **Restrict projects for this runner**, search for a project.
1. To the left of the project, select **Enable**.
1. Repeat this process for each additional project.
### Disable runner version management
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114041) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114041) in GitLab 15.10.
+
+{{< /history >}}
By default, GitLab instances periodically fetch official runner version data from GitLab.com to [determine whether the runners need upgrades](../../ci/runners/runners_scope.md#determine-which-runners-need-to-be-upgraded).
@@ -89,7 +96,11 @@ To disable your instance fetching this data:
### Restrict runner registration by all users in an instance
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/368008) in GitLab 15.5.
+{{< history >}}
+
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/368008) in GitLab 15.5.
+
+{{< /history >}}
GitLab administrators can adjust who is allowed to register runners, by showing and hiding areas of the UI.
This setting does not affect the ability to create a runner from the UI or through an authenticated API call.
@@ -107,11 +118,14 @@ To restrict all users in an instance from registering runners:
**Members of the group can register runners** checkboxes to remove runner registration from the UI.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
After you disable runner registration by members of a project, the registration
token automatically rotates. The token is no longer valid and you must
use the new registration token for the project.
+{{< /alert >}}
+
### Restrict runner registration by all members in a group
Prerequisites:
@@ -130,13 +144,20 @@ To restrict runner registration by members in a specific group:
### Allow runner registrations tokens
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147559) in GitLab 16.11
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147559) in GitLab 16.11
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
The ability to pass a runner registration token, and support for certain configuration arguments
was deprecated in GitLab 15.6 and will be removed in GitLab 18.0. Runner authentication tokens should be used instead.
For more information, see [Migrating to the new runner registration workflow](../../ci/runners/new_creation_workflow.md).
+{{< /alert >}}
+
In GitLab 17.0, the use of runner registration tokens to create runners will be disabled in all GitLab instances.
Users must use runner authentication tokens instead.
If you have not yet [migrated to the use of runner authentication tokens](../../ci/runners/new_creation_workflow.md),
@@ -197,12 +218,15 @@ This setting is set per job and can be overridden in
[`.gitlab-ci.yml`](../../ci/yaml/_index.md#artifactsexpire_in).
To disable the expiration, set it to `0`. The default unit is in seconds.
-NOTE:
+{{< alert type="note" >}}
+
Any changes to this setting applies to new artifacts only. The expiration time is not
be updated for artifacts created before this setting was changed.
The administrator may need to manually search for and expire previously-created
artifacts, as described in the [troubleshooting documentation](../cicd/job_artifacts_troubleshooting.md#delete-old-builds-and-artifacts).
+{{< /alert >}}
+
### Keep the latest artifacts for all jobs in the latest successful pipelines
When enabled (default), the artifacts of the most recent pipeline for each Git ref
@@ -226,9 +250,12 @@ To disable the setting:
When you disable the feature, the latest artifacts do not immediately expire.
A new pipeline must run before the latest artifacts can expire and be deleted.
-NOTE:
+{{< alert type="note" >}}
+
All application settings have a [customizable cache expiry interval](../application_settings_cache.md) which can delay the settings affect.
+{{< /alert >}}
+
### Disable the external redirect page for job artifacts
By default, GitLab Pages shows an external redirect page when a user tries to view
@@ -247,7 +274,7 @@ so you can view job artifact pages directly:
## Archive jobs
You can archive old jobs to prevent them from being re-run individually. Archived jobs
-display a lock icon (**{lock}**) and **This job is archived** at the top of the job log.
+display a lock icon ({{< icon name="lock" >}}) and **This job is archived** at the top of the job log.
To set the duration for which the jobs are considered as old and expired:
@@ -274,7 +301,11 @@ To set all new [CI/CD variables](../../ci/variables/_index.md) as
## Maximum includes
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207270) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207270) in GitLab 16.0.
+
+{{< /history >}}
The maximum number of [includes](../../ci/yaml/includes.md) per pipeline can be set for the entire instance.
The default is `150`.
@@ -286,7 +317,11 @@ The default is `150`.
## Maximum downstream pipeline trigger rate
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144077) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144077) in GitLab 16.10.
+
+{{< /history >}}
The maximum number of [downstream pipelines](../../ci/pipelines/downstream_pipelines.md) that can be triggered per minute
(for a given project, user, and commit) can be set for the entire instance.
@@ -311,11 +346,15 @@ It is also possible to specify a [custom CI/CD configuration file for a specific
## Set CI/CD limits
-> - **Maximum number of active pipelines per project** setting [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/368195) in GitLab 16.0.
-> - **Maximum number of instance-level CI/CD variables** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/456845) in GitLab 17.1.
-> - **Maximum size of a dotenv artifact in bytes** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155791) in GitLab 17.1.
-> - **Maximum number of variables in a dotenv artifact** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155791) in GitLab 17.1.
-> - **Maximum number of jobs in a single pipeline** setting [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/287669) from GitLab Enterprise Edition to GitLab Community Edition in 17.6.
+{{< history >}}
+
+- **Maximum number of active pipelines per project** setting [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/368195) in GitLab 16.0.
+- **Maximum number of instance-level CI/CD variables** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/456845) in GitLab 17.1.
+- **Maximum size of a dotenv artifact in bytes** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155791) in GitLab 17.1.
+- **Maximum number of variables in a dotenv artifact** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155791) in GitLab 17.1.
+- **Maximum number of jobs in a single pipeline** setting [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/287669) from GitLab Enterprise Edition to GitLab Community Edition in 17.6.
+
+{{< /history >}}
You can configure some [CI/CD limits](../instance_limits.md#cicd-limits)
from the **Admin** area:
@@ -340,7 +379,11 @@ from the **Admin** area:
## Job token permissions
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/496647) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/496647) in GitLab 17.6.
+
+{{< /history >}}
You can configure the [CI/CD job token access setting](../../ci/jobs/ci_job_token.md#control-job-token-access-to-your-project)
for all projects from the **Admin** area.
@@ -367,7 +410,11 @@ To disable the banner:
## Disable the migrate from Jenkins banner
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/470025) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/470025) in GitLab 17.7.
+
+{{< /history >}}
By default, a banner shows in merge requests in projects with the [Jenkins integration enabled](../../integration/jenkins.md) to prompt migration to GitLab CI/CD.
@@ -382,20 +429,30 @@ To disable the banner:
## Required pipeline configuration
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/352316) from GitLab Premium to GitLab Ultimate in 15.0.
+- [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389467) in GitLab 15.9.
+- [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389467) in GitLab 17.0.
+- [Re-added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165111) behind the `required_pipelines` feature flag in GitLab 17.4. Disabled by default.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/352316) from GitLab Premium to GitLab Ultimate in 15.0.
-> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389467) in GitLab 15.9.
-> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389467) in GitLab 17.0.
-> - [Re-added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165111) behind the `required_pipelines` feature flag in GitLab 17.4. Disabled by default.
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389467) in GitLab 15.9
and was removed in 17.0. From 17.4, it is available only behind the feature flag `required_pipelines`, disabled by default.
Use [compliance pipelines](../../user/group/compliance_pipelines.md) instead. This change is a breaking change.
+{{< /alert >}}
+
You can set a [CI/CD template](../../ci/examples/_index.md#cicd-templates)
as a required pipeline configuration for all projects on a GitLab instance. You can
use a template from:
@@ -403,12 +460,15 @@ use a template from:
- The default CI/CD templates.
- A custom template stored in an [instance template repository](instance_template_repository.md).
- NOTE:
- When you use a configuration defined in an instance template repository,
+ {{< alert type="note" >}}
+
+When you use a configuration defined in an instance template repository,
nested [`include:`](../../ci/yaml/_index.md#include) keywords
(including `include:file`, `include:local`, `include:remote`, and `include:template`)
[do not work](https://gitlab.com/gitlab-org/gitlab/-/issues/35345).
+ {{< /alert >}}
+
The project CI/CD configuration merges into the required pipeline configuration when
a pipeline runs. The merged configuration is the same as if the required pipeline configuration
added the project configuration with the [`include` keyword](../../ci/yaml/_index.md#include).
@@ -427,9 +487,12 @@ To select a CI/CD template for the required pipeline configuration:
### Maven Forwarding
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab administrators can disable the forwarding of Maven requests to [Maven Central](https://search.maven.org/).
@@ -443,9 +506,12 @@ To disable forwarding Maven requests:
### npm Forwarding
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab administrators can disable the forwarding of npm requests to [npmjs.com](https://www.npmjs.com/).
@@ -459,9 +525,12 @@ To disable it:
### PyPI Forwarding
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab administrators can disable the forwarding of PyPI requests to [pypi.org](https://pypi.org/).
diff --git a/doc/administration/settings/deprecated_api_rate_limits.md b/doc/administration/settings/deprecated_api_rate_limits.md
index 56bd6ab155be7bc5b1d415a5b25e87ec584b9c7b..6ec888bc203d4f3fe16dd792fc2332cafd5da372 100644
--- a/doc/administration/settings/deprecated_api_rate_limits.md
+++ b/doc/administration/settings/deprecated_api_rate_limits.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Define limits for deprecated APIs on GitLab Self-Managed."
+description: Define limits for deprecated APIs on GitLab Self-Managed.
title: Deprecated API rate limits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Deprecated API endpoints are those which have been replaced with alternative
functionality, but cannot be removed without breaking backward compatibility.
diff --git a/doc/administration/settings/email.md b/doc/administration/settings/email.md
index 861a03272b91cca2b3a1d823d9f2e4498fa3b5ac..439d167f2dd9d7af2e0008496d21cbe700a93258 100644
--- a/doc/administration/settings/email.md
+++ b/doc/administration/settings/email.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Email
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can customize some of the content in emails sent from your GitLab instance.
@@ -17,9 +20,12 @@ The logo in the header of some emails can be customized, see the [logo customiza
## Include author name in email notification email body
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
By default, GitLab overrides the email address in notification emails with the email address
of the issue, merge request, or comment author. Enable this setting to include the author's email
@@ -35,9 +41,12 @@ To include the author's email address in the email body:
## Enable multipart email
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab can send email in multipart format (HTML and plain text) or plain text only.
@@ -51,9 +60,12 @@ To enable multipart email:
## Custom hostname for private commit emails
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This configuration option sets the email hostname for [private commit emails](../../user/profile/_index.md#use-an-automatically-generated-private-commit-email).
By default it is set to `users.noreply.YOUR_CONFIGURED_HOSTNAME`.
@@ -66,16 +78,22 @@ To change the hostname used in private commit emails:
1. Enter the desired hostname in the **Custom hostname (for private commit emails)** field.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
After the hostname is configured, every private commit email using the previous hostname is not
recognized by GitLab. This can directly conflict with certain [Push rules](../../user/project/repository/push_rules.md) such as
`Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`.
+{{< /alert >}}
+
## Custom additional text
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can add additional text at the bottom of any email that GitLab sends. This additional text
can be used for legal, auditing, or compliance reasons, for example.
@@ -102,13 +120,20 @@ To disable these notifications:
### Custom additional text in deactivation emails
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355964) in GitLab 15.9 [with a flag](../feature_flags.md) named `deactivation_email_additional_text`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111882) in GitLab 15.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392761) in GitLab 16.5. Feature flag `deactivation_email_additional_text` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355964) in GitLab 15.9 [with a flag](../feature_flags.md) named `deactivation_email_additional_text`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111882) in GitLab 15.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392761) in GitLab 16.5. Feature flag `deactivation_email_additional_text` removed.
+
+{{< /history >}}
You can add additional text at the bottom of the email that GitLab sends to users when their account
is deactivated. This email text is separate from the [custom additional text](#custom-additional-text)
@@ -124,15 +149,25 @@ To add additional text to deactivation emails:
## Group and project access token expiry emails to inherited members
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
-> - Notifications to inherited group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) in GitLab 17.7 [with a flag](../feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+{{< /details >}}
+
+{{< history >}}
+
+- Notifications to inherited group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) in GitLab 17.7 [with a flag](../feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of emails to inherited project and group members is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
In GitLab 17.7 and later, the following inherited group and project members can receive emails about group and project access tokens that are expiring soon, in addition to direct group and project members:
- For groups, members who inherit the Owner role for those groups.
diff --git a/doc/administration/settings/external_authorization.md b/doc/administration/settings/external_authorization.md
index 252be07a76b7bd39526a4b22366db504613f9d3d..628c56915eb5ce9b27247da5b9d1e33e43ef19ed 100644
--- a/doc/administration/settings/external_authorization.md
+++ b/doc/administration/settings/external_authorization.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: External authorization control
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) from GitLab Premium to GitLab Free in 11.10.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) from GitLab Premium to GitLab Free in 11.10.
+
+{{< /history >}}
In highly controlled environments, it may be necessary for access policy to be
controlled by an external service that permits access based on project
@@ -56,8 +63,12 @@ The external authorization service can be enabled by an administrator:
### Allow external authorization with deploy tokens and deploy keys
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386656) in GitLab 15.9.
-> - Deploy tokens no longer being able to access container or package registries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387721) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386656) in GitLab 15.9.
+- Deploy tokens no longer being able to access container or package registries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387721) in GitLab 16.0.
+
+{{< /history >}}
You can set your instance to allow external authorization for Git operations with
[deploy tokens](../../user/project/deploy_tokens/_index.md) or [deploy keys](../../user/project/deploy_keys/_index.md).
@@ -75,9 +86,12 @@ To allow authorization with deploy tokens and keys:
- Select **Allow deploy tokens and deploy keys to be used with external authorization**.
1. Select **Save changes**.
-WARNING:
+{{< alert type="warning" >}}
+
If you enable external authorization, deploy tokens cannot access container or package registries. If you use deploy tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use tokens with container or package registries.
+{{< /alert >}}
+
## How it works
When GitLab requests access, it sends a JSON POST request to the external
diff --git a/doc/administration/settings/files_api_rate_limits.md b/doc/administration/settings/files_api_rate_limits.md
index 49636d6259312e97b5a6134ca3f0d0f77337f81f..f861e735f10d507286ede73816460415c65d2a14 100644
--- a/doc/administration/settings/files_api_rate_limits.md
+++ b/doc/administration/settings/files_api_rate_limits.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Configure rate limits for the repository files API on GitLab Self-Managed."
+description: Configure rate limits for the repository files API on GitLab Self-Managed.
title: Rate limits on Repository files API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The [Repository files API](../../api/repository_files.md) enables you to
fetch, create, update, and delete files in your repository. To improve the security
diff --git a/doc/administration/settings/floc.md b/doc/administration/settings/floc.md
index ba08053a1c6d805679b3b2f12a258376af16eca0..e44913503eaeb99e9bcfe0d6dd52bcedf915c156 100644
--- a/doc/administration/settings/floc.md
+++ b/doc/administration/settings/floc.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Federated Learning of Cohorts (FLoC)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Federated Learning of Cohorts (FLoC) was a proposed feature
for Google Chrome that categorized users into different cohorts for interest-based
diff --git a/doc/administration/settings/git_http_rate_limits.md b/doc/administration/settings/git_http_rate_limits.md
index 4b32d596214a43e72413546f4ccb345da3699128..2220880c16f817ed0e1a5d50c7764a04ce39dd77 100644
--- a/doc/administration/settings/git_http_rate_limits.md
+++ b/doc/administration/settings/git_http_rate_limits.md
@@ -2,15 +2,22 @@
stage: Create
group: Source Code
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
-description: "Configure rate limits on Git HTTP requests to GitLab Self-Managed."
+description: Configure rate limits on Git HTTP requests to GitLab Self-Managed.
title: Rate limits on Git HTTP
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147112) in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147112) in GitLab 17.0.
+
+{{< /history >}}
If you use Git HTTP in your repository,
common Git operations can generate many Git HTTP requests.
diff --git a/doc/administration/settings/git_lfs_rate_limits.md b/doc/administration/settings/git_lfs_rate_limits.md
index b3b1dc69415096bc203496e8f2abb21508b3a900..d3ba023a1006d7e750ccda66dcd415990b2341ad 100644
--- a/doc/administration/settings/git_lfs_rate_limits.md
+++ b/doc/administration/settings/git_lfs_rate_limits.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Configure rate limits for Git LFS on GitLab Self-Managed."
+description: Configure rate limits for Git LFS on GitLab Self-Managed.
title: Rate limits on Git LFS
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
[Git LFS (Large File Storage)](../../topics/git/lfs/_index.md) is a Git extension
for handling large files. If you use Git LFS in your repository, common Git operations
diff --git a/doc/administration/settings/gitaly_timeouts.md b/doc/administration/settings/gitaly_timeouts.md
index f58fe86acbee6abfdf9d98ee6e0fb41f040ba4fc..f43ff0e089413a42a17bd24f79889e273024eaa8 100644
--- a/doc/administration/settings/gitaly_timeouts.md
+++ b/doc/administration/settings/gitaly_timeouts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Gitaly timeouts
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
[Gitaly](../gitaly/_index.md) provides two types of configurable timeouts:
@@ -36,7 +39,11 @@ Different call timeouts are available for different Gitaly operations.
## Configure the negotiation timeouts
-> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5574) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5574) in GitLab 16.5.
+
+{{< /history >}}
You might need to increase the negotiation timeout:
@@ -50,9 +57,9 @@ You can configure negotiation timeouts for:
To configure these timeouts:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Edit `/etc/gitlab/gitlab.rb`:
@@ -65,7 +72,9 @@ gitaly['configuration'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Edit `/home/git/gitaly/config.toml`:
@@ -75,7 +84,9 @@ upload_pack_negotiation = "10m"
upload_archive_negotiation = "20m"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
For the values, use the format of [`ParseDuration`](https://pkg.go.dev/time#ParseDuration) in Go.
diff --git a/doc/administration/settings/help_page.md b/doc/administration/settings/help_page.md
index 4f565e650e80e746946aa628f72a48c83900fc95..27caa863879a1cbd90188479dc2d781da668e5bb 100644
--- a/doc/administration/settings/help_page.md
+++ b/doc/administration/settings/help_page.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Customize the Help page message
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
In large organizations, it is useful to have information about who to contact or where
to go for help. You can customize and display this information on the GitLab `/help` page.
@@ -25,14 +28,21 @@ You can add a help message, which is shown at the top of the GitLab `/help` page
You can now see the message on `/help`.
-NOTE:
+{{< alert type="note" >}}
+
By default, `/help` is visible to unauthenticated users. However, if the
[**Public** visibility level](visibility_and_access_controls.md#restrict-visibility-levels)
is restricted, `/help` is visible only to authenticated users.
+{{< /alert >}}
+
## Add a help message to the sign-in page
-> - Additional text to show on the sign-in page [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/410885) in GitLab 17.0.
+{{< history >}}
+
+- Additional text to show on the sign-in page [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/410885) in GitLab 17.0.
+
+{{< /history >}}
To add a help message to the sign-in page, [customize your sign-in and register pages](../appearance.md#customize-your-sign-in-and-register-pages).
diff --git a/doc/administration/settings/import_and_export_settings.md b/doc/administration/settings/import_and_export_settings.md
index 0e93f48e9c17789371f877e662d8c44ad90f55de..ceea800f7bc7ff6ea01bd034966c06bc9d5fb338 100644
--- a/doc/administration/settings/import_and_export_settings.md
+++ b/doc/administration/settings/import_and_export_settings.md
@@ -1,13 +1,16 @@
---
stage: Foundations
group: Import and Integrate
-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"
+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
title: Import and export settings
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Settings for import- and export-related features.
@@ -38,17 +41,29 @@ To enable the export of
## Enable migration of groups and projects by direct transfer
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8.
+
+{{< /history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8.
+{{< alert type="warning" >}}
-WARNING:
In GitLab 16.1 and earlier, you should **not** use direct transfer with [scheduled scan execution policies](../../user/application_security/policies/scan_execution_policies.md). If using direct transfer, first upgrade to GitLab 16.2 and ensure security policy bots are enabled in the projects you are enforcing.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
This feature is in [beta](../../policy/development_stages_support.md#beta) and subject to change without notice.
This feature is not ready for production use.
+{{< /alert >}}
Migration of groups and projects by direct transfer is disabled by default.
To enable migration of groups and projects by direct transfer:
@@ -67,9 +82,13 @@ The same setting
## Enable silent admin exports
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151278) in GitLab 17.0 [with a flag](../feature_flags.md) named `export_audit_events`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153351) in GitLab 17.1. Feature flag `export_audit_events` removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152143) for file export downloads in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151278) in GitLab 17.0 [with a flag](../feature_flags.md) named `export_audit_events`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153351) in GitLab 17.1. Feature flag `export_audit_events` removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152143) for file export downloads in GitLab 17.1.
+
+{{< /history >}}
Enable silent admin exports to prevent [audit events](../audit_event_reports.md) when
instance administrators trigger a [project or group file export](../../user/project/settings/import_export.md) or download the export file.
@@ -84,8 +103,12 @@ To enable silent admin project and group file exports:
## Allow contribution mapping to administrators
-> - Introduced in GitLab 17.5 [with a flag](../feature_flags.md) named `importer_user_mapping`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175371) in GitLab 17.7.
+{{< history >}}
+
+- Introduced in GitLab 17.5 [with a flag](../feature_flags.md) named `importer_user_mapping`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175371) in GitLab 17.7.
+
+{{< /history >}}
Allow mapping of imported user contributions to administrators.
@@ -98,7 +121,11 @@ To allow mapping of imported user contributions to administrators:
## Max export size
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86124) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86124) in GitLab 15.0.
+
+{{< /history >}}
To modify the maximum file size for exports in GitLab:
@@ -126,7 +153,11 @@ For GitLab.com repository size limits, read [accounts and limit settings](../../
## Maximum remote file size for imports
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384976) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384976) in GitLab 16.3.
+
+{{< /history >}}
By default, the maximum remote file size for imports from external object storages (for example, AWS) is 10 GiB.
@@ -139,7 +170,11 @@ To modify this setting:
## Maximum download file size for imports by direct transfer
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384976) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384976) in GitLab 16.3.
+
+{{< /history >}}
By default, the maximum download file size for imports by direct transfer is 5 GiB.
@@ -152,8 +187,12 @@ To modify this setting:
## Maximum decompressed file size for imported archives
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128218) in GitLab 16.3.
-> - **Maximum decompressed file size for archives from imports** field [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130081) from **Maximum decompressed size** in GitLab 16.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128218) in GitLab 16.3.
+- **Maximum decompressed file size for archives from imports** field [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130081) from **Maximum decompressed size** in GitLab 16.4.
+
+{{< /history >}}
When you import a project using [file exports](../../user/project/settings/import_export.md) or
[direct transfer](../../user/group/import/_index.md), you can specify the
@@ -175,7 +214,11 @@ To modify this setting:
## Timeout for decompressing archived files
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128218) in GitLab 16.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128218) in GitLab 16.4.
+
+{{< /history >}}
When you [import a project](../../user/project/settings/import_export.md), you can specify the maximum time out for decompressing imported archives. The default value is 210 seconds.
@@ -188,7 +231,11 @@ To modify the maximum decompressed file size for imports in GitLab:
## Maximum number of simultaneous import jobs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143875) in GitLab 16.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143875) in GitLab 16.11.
+
+{{< /history >}}
You can specify the maximum number of import jobs that are executed simultaneously for:
@@ -215,7 +262,11 @@ To modify this setting:
## Maximum number of simultaneous batch export jobs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169122) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169122) in GitLab 17.6.
+
+{{< /history >}}
Direct transfer exports can consume a significant amount of resources.
To prevent using up the database or Sidekiq processes,
diff --git a/doc/administration/settings/import_export_rate_limits.md b/doc/administration/settings/import_export_rate_limits.md
index 245d6cf540980884638dab840ee17e7e48963ca2..3a6f216ae9d71c051ff4b95e7ca80c80baa75a3a 100644
--- a/doc/administration/settings/import_export_rate_limits.md
+++ b/doc/administration/settings/import_export_rate_limits.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limits for imports and exports of project and groups
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can configure the rate limits for imports and exports of projects and groups:
diff --git a/doc/administration/settings/incident_management_rate_limits.md b/doc/administration/settings/incident_management_rate_limits.md
index 298dffabd6c10f1d83007a3f8a5bd5d9fa5d41a9..7fe12a61f185ad40c23dc19136842e2d8670709c 100644
--- a/doc/administration/settings/incident_management_rate_limits.md
+++ b/doc/administration/settings/incident_management_rate_limits.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Incident management rate limits
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can limit the number of inbound alerts for [incidents](../../operations/incident_management/incidents.md)
that can be created in a period of time. The inbound [incident management](../../operations/incident_management/_index.md)
diff --git a/doc/administration/settings/instance_template_repository.md b/doc/administration/settings/instance_template_repository.md
index bca5ea599e3b2e11c60cfc338194c7d1da521a9c..5c56cc1b5f1ced0d2554f93fcbb70cf2e27c05c6 100644
--- a/doc/administration/settings/instance_template_repository.md
+++ b/doc/administration/settings/instance_template_repository.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Configure a collection of file templates available for all projects on GitLab Self-Managed."
+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
+description: Configure a collection of file templates available for all projects on GitLab Self-Managed.
title: Instance template repository
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
In hosted systems, enterprises often have a need to share their own templates
across teams. This feature allows an administrator to pick a project to be the
diff --git a/doc/administration/settings/jira_cloud_app.md b/doc/administration/settings/jira_cloud_app.md
index d05f36f57d72b312eaa914646c0dcfc5ee575acb..3c4ff8c460a78d5a12cb0152c3990e193135383b 100644
--- a/doc/administration/settings/jira_cloud_app.md
+++ b/doc/administration/settings/jira_cloud_app.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab for Jira Cloud app administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This page contains administrator documentation for the GitLab for Jira Cloud app. For user documentation, see [GitLab for Jira Cloud app](../../integration/jira/connect-app.md).
+{{< /alert >}}
+
With the [GitLab for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?tab=overview&hosting=cloud) app, you can connect GitLab and Jira Cloud to sync development information in real time. You can view this information in the [Jira development panel](../../integration/jira/development_panel.md).
To set up the GitLab for Jira Cloud app on your GitLab Self-Managed instance, do one of the following:
@@ -48,8 +54,11 @@ To create an OAuth application on your GitLab Self-Managed instance:
- If you're installing the app manually, enter `<instance_url>/-/jira_connect/oauth_callbacks` and replace `<instance_url>` with the URL of your instance.
1. Clear the **Trusted** and **Confidential** checkboxes.
- NOTE:
- You must clear these checkboxes to avoid [errors](jira_cloud_app_troubleshooting.md#error-failed-to-sign-in-to-gitlab).
+ {{< alert type="note" >}}
+
+You must clear these checkboxes to avoid [errors](jira_cloud_app_troubleshooting.md#error-failed-to-sign-in-to-gitlab).
+
+ {{< /alert >}}
1. In **Scopes**, select the `api` checkbox only.
1. Select **Save application**.
@@ -61,7 +70,11 @@ To create an OAuth application on your GitLab Self-Managed instance:
## Jira user requirements
-> - Support for the `org-admins` group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420687) in GitLab 16.6.
+{{< history >}}
+
+- Support for the `org-admins` group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420687) in GitLab 16.6.
+
+{{< /history >}}
In your [Atlassian organization](https://admin.atlassian.com), you must ensure that the Jira user that is used to set up the GitLab for Jira Cloud app is a member of
either:
@@ -83,7 +96,11 @@ If necessary:
## Install the GitLab for Jira Cloud app from the Atlassian Marketplace
-> - Introduced in GitLab 15.7.
+{{< history >}}
+
+- Introduced in GitLab 15.7.
+
+{{< /history >}}
You can use the official GitLab for Jira Cloud app from the Atlassian Marketplace with your GitLab Self-Managed instance.
@@ -164,11 +181,14 @@ to check if Jira Cloud is linked to:
## Install the GitLab for Jira Cloud app manually
-WARNING:
+{{< alert type="warning" >}}
+
In GitLab 17.5 and earlier, you might encounter an issue when you install the GitLab for Jira Cloud app manually.
For more information, see [issue 505372](https://gitlab.com/gitlab-org/gitlab/-/issues/505372).
This issue does not affect [installations from the Atlassian Marketplace](#install-the-gitlab-for-jira-cloud-app-from-the-atlassian-marketplace).
+{{< /alert >}}
+
If you do not want to [use the official Atlassian Marketplace listing](#install-the-gitlab-for-jira-cloud-app-from-the-atlassian-marketplace),
install the GitLab for Jira Cloud app manually.
@@ -421,7 +441,11 @@ For more information, see [issue 21319](https://gitlab.com/gitlab-org/gitlab/-/i
### Set an additional JWT audience
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/498587) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/498587) in GitLab 17.7.
+
+{{< /history >}}
When GitLab receives a JWT token from Jira,
GitLab verifies the token by checking the JWT audience.
diff --git a/doc/administration/settings/jira_cloud_app_troubleshooting.md b/doc/administration/settings/jira_cloud_app_troubleshooting.md
index 3b5b5d7c08ddd706aea6a59164e933f143d2c026..d2913208015fde853134380a78493e5308d7ce36 100644
--- a/doc/administration/settings/jira_cloud_app_troubleshooting.md
+++ b/doc/administration/settings/jira_cloud_app_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting GitLab for Jira Cloud app administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When administering the GitLab for Jira Cloud app, you might encounter the following issues.
@@ -198,9 +201,12 @@ GitLab Support can then investigate the issue in the GitLab.com server logs.
#### GitLab Support
-NOTE:
+{{< alert type="note" >}}
+
These steps can only be completed by GitLab Support.
+{{< /alert >}}
+
Each `GET` request made to the Jira Connect Proxy URL `https://gitlab.com/-/jira_connect/installations` generates two log entries.
To locate the relevant log entries in Kibana, either:
diff --git a/doc/administration/settings/localization.md b/doc/administration/settings/localization.md
index 0d51216b027ecda67b3b953865199aebd49c8db3..ac6092f404f4bd5b9946c2741343b5aadbc90668 100644
--- a/doc/administration/settings/localization.md
+++ b/doc/administration/settings/localization.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Localization
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
As an instance administrator, you can manage the behavior of your
deployment.
diff --git a/doc/administration/settings/package_registry_rate_limits.md b/doc/administration/settings/package_registry_rate_limits.md
index 1d34661abf5aecb1a30a471bfc807a5a2f4bc276..b056a904e260d0755503cdd30544063bfd6737eb 100644
--- a/doc/administration/settings/package_registry_rate_limits.md
+++ b/doc/administration/settings/package_registry_rate_limits.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Package registry rate limits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
With the [GitLab package registry](../../user/packages/package_registry/_index.md),
you can use GitLab as a private or public registry for a variety of common package managers. You can
diff --git a/doc/administration/settings/project_integration_management.md b/doc/administration/settings/project_integration_management.md
index 8832ae95726d547b2264cf101eca101e9b767876..ad38468bf70f068c39843ba8b5364e3e6c179b93 100644
--- a/doc/administration/settings/project_integration_management.md
+++ b/doc/administration/settings/project_integration_management.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Integration administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This page contains administrator documentation for project and group integrations. For user documentation, see [Project integrations](../../user/project/integrations/_index.md).
+{{< /alert >}}
+
Project and group administrators can configure and enable integrations.
As an instance administrator, you can:
@@ -32,10 +38,13 @@ To configure default settings for an integration:
1. Complete the fields.
1. Select **Save changes**.
-WARNING:
+{{< alert type="warning" >}}
+
This may affect all or most of the groups and projects on your GitLab instance. Review the details
below.
+{{< /alert >}}
+
If this is the first time you are setting up instance-level settings for an integration:
- The integration is enabled for all groups and projects that don't already have this integration configured,
@@ -89,10 +98,17 @@ To view projects in your instance that [use custom settings](../../user/project/
## Integration allowlist
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/500610) in GitLab 17.7.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/500610) in GitLab 17.7.
+{{< /history >}}
By default, project and group administrators can enable integrations.
However, instance administrators can configure an allowlist to control
diff --git a/doc/administration/settings/protected_paths.md b/doc/administration/settings/protected_paths.md
index 616af30b6e01587cc49573f123e1d8db0192b17d..25d45ddd78993e622bb0faf3ee7ad24ca1f0296b 100644
--- a/doc/administration/settings/protected_paths.md
+++ b/doc/administration/settings/protected_paths.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Protected paths
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Rate limiting is a technique that improves the security and durability of a web
application. For more details, see [Rate limits](../../security/rate_limits.md).
diff --git a/doc/administration/settings/push_event_activities_limit.md b/doc/administration/settings/push_event_activities_limit.md
index 1035c6b5185a586062e61c86958c84405550d63f..e93750d12c598b370e3dcb37c543df1aaedd4a76 100644
--- a/doc/administration/settings/push_event_activities_limit.md
+++ b/doc/administration/settings/push_event_activities_limit.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Configure limits on the number of single push events your instance will allow."
+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
+description: Configure limits on the number of single push events your instance will allow.
title: Push event activities limit and bulk push events
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Set the number of branches or tags to limit the number of single push events
allowed at once. If the number of events is greater than this, GitLab creates
diff --git a/doc/administration/settings/rate_limit_on_groups_api.md b/doc/administration/settings/rate_limit_on_groups_api.md
index fb0bd13b0ad94b834af4c1e1a52014041da5d009..a52176658f3aa70a63ad9d8ce54fe767a17c9f47 100644
--- a/doc/administration/settings/rate_limit_on_groups_api.md
+++ b/doc/administration/settings/rate_limit_on_groups_api.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limit on Groups API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - Rate limit for groups and projects API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152733) in GitLab 17.1. with a [flag](../feature_flags.md) named `rate_limit_groups_and_projects_api`. Disabled by default.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- Rate limit for groups and projects API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152733) in GitLab 17.1. with a [flag](../feature_flags.md) named `rate_limit_groups_and_projects_api`. Disabled by default.
+
+{{< /history >}}
You can configure the per minute rate limit per IP address and per user for requests to the following [groups API](../../api/groups.md).
diff --git a/doc/administration/settings/rate_limit_on_issues_creation.md b/doc/administration/settings/rate_limit_on_issues_creation.md
index c094654d5b58d3186e268fb0cec5453acee753ce..6e1c6aea251c0c4c21373578c796bc833fff1afa 100644
--- a/doc/administration/settings/rate_limit_on_issues_creation.md
+++ b/doc/administration/settings/rate_limit_on_issues_creation.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limits on issue and epic creation
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Rate limits control the pace at which new epics and issues can be created.
For example, if you set the limit to `300`, the
diff --git a/doc/administration/settings/rate_limit_on_members_api.md b/doc/administration/settings/rate_limit_on_members_api.md
index 6e5ea665c258599455c38f4dca58038edd034352..7f548f3b76cace9427e780c3fd6ec7df537d9c77 100644
--- a/doc/administration/settings/rate_limit_on_members_api.md
+++ b/doc/administration/settings/rate_limit_on_members_api.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limit on Members API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140633) in GitLab 16.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140633) in GitLab 16.9.
+
+{{< /history >}}
You can configure the rate limit per group (or project) per user to the
[delete members API](../../api/members.md#remove-a-member-from-a-group-or-project).
diff --git a/doc/administration/settings/rate_limit_on_notes_creation.md b/doc/administration/settings/rate_limit_on_notes_creation.md
index b7cf2f46e6b14452fa7ccd27a5fa61ef861509c4..4bd5f33ed9bc977e1780902d56500d90c169db21 100644
--- a/doc/administration/settings/rate_limit_on_notes_creation.md
+++ b/doc/administration/settings/rate_limit_on_notes_creation.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limits on note creation
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can configure the per-user rate limit for requests to the note creation endpoint.
diff --git a/doc/administration/settings/rate_limit_on_organizations_api.md b/doc/administration/settings/rate_limit_on_organizations_api.md
index 05a6ff3a05b265bdcaae0abc4302c3f1cde669fc..0d1754f65d62699a0ca3d6eae489c01766d69870 100644
--- a/doc/administration/settings/rate_limit_on_organizations_api.md
+++ b/doc/administration/settings/rate_limit_on_organizations_api.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limit on Organizations API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/470613) in GitLab 17.5 with a [flag](../feature_flags.md) named `allow_organization_creation`. Disabled by default. This feature is an [experiment](../../policy/development_stages_support.md).
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/470613) in GitLab 17.5 with a [flag](../feature_flags.md) named `allow_organization_creation`. Disabled by default. This feature is an [experiment](../../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Requests over the rate limit are logged into the `auth.log` file.
For example, if you set a limit of 400 for `POST /organizations`, requests to the API endpoint that
diff --git a/doc/administration/settings/rate_limit_on_pipelines_creation.md b/doc/administration/settings/rate_limit_on_pipelines_creation.md
index 30b4d804087d1824114ad7cb46d646dd8f1249fc..e9e473e93066b3e3aa929951b48489b2a3c73718 100644
--- a/doc/administration/settings/rate_limit_on_pipelines_creation.md
+++ b/doc/administration/settings/rate_limit_on_pipelines_creation.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limits on pipeline creation
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362475) in GitLab 15.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362475) in GitLab 15.0.
+
+{{< /history >}}
You can set a limit so that users and processes can't request more than a certain number of pipelines each minute. This limit can help save resources and improve stability.
diff --git a/doc/administration/settings/rate_limit_on_projects_api.md b/doc/administration/settings/rate_limit_on_projects_api.md
index 0a3c166daf4dfabc3ccbbf0e393b78f2126a1fb8..4be49afdf32180861af596c808f3364c83b9ad7b 100644
--- a/doc/administration/settings/rate_limit_on_projects_api.md
+++ b/doc/administration/settings/rate_limit_on_projects_api.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limit on Projects API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112283) in GitLab 15.10 with a [flag](../feature_flags.md) named `rate_limit_for_unauthenticated_projects_api_access`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/391922) on May 08, 2023.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119603) in GitLab 16.0 by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120445) in GitLab 16.0. Feature flag `rate_limit_for_unauthenticated_projects_api_access` removed.
-> - Rate limit for group and projects API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152733) in GitLab 17.1. with a [flag](../feature_flags.md) named `rate_limit_groups_and_projects_api`. Disabled by default.
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112283) in GitLab 15.10 with a [flag](../feature_flags.md) named `rate_limit_for_unauthenticated_projects_api_access`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/391922) on May 08, 2023.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119603) in GitLab 16.0 by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120445) in GitLab 16.0. Feature flag `rate_limit_for_unauthenticated_projects_api_access` removed.
+- Rate limit for group and projects API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152733) in GitLab 17.1. with a [flag](../feature_flags.md) named `rate_limit_groups_and_projects_api`. Disabled by default.
+
+{{< /history >}}
You can configure the rate limit per IP address and per user for requests to the following [projects API](../../api/projects.md#list-all-projects).
diff --git a/doc/administration/settings/rate_limit_on_users_api.md b/doc/administration/settings/rate_limit_on_users_api.md
index 1b29ba6a5cb28d3d80a94c52dfe238cdc9f8d767..306004aa4342509665c5c4a17fce3c2aa83254e1 100644
--- a/doc/administration/settings/rate_limit_on_users_api.md
+++ b/doc/administration/settings/rate_limit_on_users_api.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limits on Users API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can configure the per user rate limit for requests to [Users API](../../api/users.md).
diff --git a/doc/administration/settings/rate_limits_on_git_ssh_operations.md b/doc/administration/settings/rate_limits_on_git_ssh_operations.md
index dbc34ef594f65363ecd21006d9f601d077e4df56..a198c78b1fc82ddcb8aa73a7d65f1654ebc86ee2 100644
--- a/doc/administration/settings/rate_limits_on_git_ssh_operations.md
+++ b/doc/administration/settings/rate_limits_on_git_ssh_operations.md
@@ -2,15 +2,22 @@
stage: Create
group: Source Code
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
-description: "Configure rate limits on Git SSH operations on GitLab Self-Managed."
+description: Configure rate limits on Git SSH operations on GitLab Self-Managed.
title: Rate limits on Git SSH operations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Available by default](https://gitlab.com/gitlab-org/gitlab/-/issues/367998) in GitLab 15.8. [Feature flag](../feature_flags.md) `rate_limit_gitlab_shell` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Available by default](https://gitlab.com/gitlab-org/gitlab/-/issues/367998) in GitLab 15.8. [Feature flag](../feature_flags.md) `rate_limit_gitlab_shell` removed.
+
+{{< /history >}}
GitLab applies rate limits to Git operations that use SSH by user account and project. When the rate limit is exceeded, GitLab rejects
further connection requests from that user for the project.
@@ -25,7 +32,11 @@ Because the same commands are shared by `git-upload-pack`, `git pull`, and `git
## Configure GitLab Shell operation limit
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123761) in GitLab 16.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123761) in GitLab 16.2.
+
+{{< /history >}}
`Git operations using SSH` is enabled by default. Defaults to 600 per user per minute.
diff --git a/doc/administration/settings/rate_limits_on_raw_endpoints.md b/doc/administration/settings/rate_limits_on_raw_endpoints.md
index 4ace32ed9bf99819a06f16eeff29b9ff866e2797..b02b09c671ec5ccd3a9c598c0bd8be658bb3194f 100644
--- a/doc/administration/settings/rate_limits_on_raw_endpoints.md
+++ b/doc/administration/settings/rate_limits_on_raw_endpoints.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limits on raw endpoints
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This setting defaults to `300` requests per minute, and allows you to rate limit the requests to raw endpoints:
diff --git a/doc/administration/settings/scim_setup.md b/doc/administration/settings/scim_setup.md
index 6c0c5f38784046e60268b47b98ab3cf84d5009ba..b6163f2f1241362bcc51073eea8fd85895b03bad 100644
--- a/doc/administration/settings/scim_setup.md
+++ b/doc/administration/settings/scim_setup.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure SCIM for GitLab Self-Managed
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8902) in GitLab 15.8.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8902) in GitLab 15.8.
+
+{{< /history >}}
You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically:
@@ -43,9 +50,12 @@ You can configure the following as an identity provider:
- [Okta](#configure-okta).
- [Microsoft Entra ID (formerly Azure Active Directory)](#configure-microsoft-entra-id-formerly-azure-active-directory)
-NOTE:
+{{< alert type="note" >}}
+
Other identity providers can work with GitLab but they have not been tested and are not supported. You should contact the provider for support. GitLab support can assist by reviewing related log entries.
+{{< /alert >}}
+
### Configure Okta
The SAML application created during [single sign-on](../../integration/saml.md) set up for Okta must be set up for SCIM.
@@ -84,7 +94,11 @@ To configure Okta for SCIM:
### Configure Microsoft Entra ID (formerly Azure Active Directory)
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143146) to Microsoft Entra ID terminology in GitLab 16.10.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143146) to Microsoft Entra ID terminology in GitLab 16.10.
+
+{{< /history >}}
Prerequisites:
@@ -95,10 +109,13 @@ The SAML application created during [single sign-on](../../integration/saml.md)
[Azure Active Directory](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/view-applications-portal)
must be set up for SCIM. For an example, see [example configuration](../../user/group/saml_sso/example_saml_config.md#scim-mapping).
-NOTE:
+{{< alert type="note" >}}
+
You must configure SCIM provisioning exactly as detailed in the following instructions. If misconfigured, you will encounter issues with user provisioning
and sign in, which require a lot of effort to resolve. If you have any trouble or questions with any step, contact GitLab support.
+{{< /alert >}}
+
To configure Microsoft Entra ID, you configure:
- Microsoft Entra ID for SCIM.
@@ -132,8 +149,11 @@ Under the **Mappings** section, first provision the groups:
SCIM group provisioning is not supported in GitLab. Leaving group provisioning enabled does not break the SCIM user provisioning, but it causes errors in the
Entra ID SCIM provisioning log that might be confusing and misleading.
- NOTE:
- Even when **Provision Microsoft Entra ID Groups** is disabled, the mappings section may display "Enabled: Yes". This behavior is a display bug that you can safely ignore.
+ {{< alert type="note" >}}
+
+Even when **Provision Microsoft Entra ID Groups** is disabled, the mappings section may display "Enabled: Yes". This behavior is a display bug that you can safely ignore.
+
+ {{< /alert >}}
1. Select **Save**.
@@ -161,10 +181,13 @@ Next, provision the users:
##### Configure attribute mappings
-NOTE:
+{{< alert type="note" >}}
+
While Microsoft transitions from Azure Active Directory to Entra ID naming schemes, you might notice inconsistencies in
your user interface. If you're having trouble, you can view an older version of this document or contact GitLab Support.
+{{< /alert >}}
+
While [configuring Entra ID for SCIM](#configure-microsoft-entra-id-formerly-azure-active-directory), you configure
attribute mappings. For an example, see [example configuration](../../user/group/saml_sso/example_saml_config.md#scim-mapping).
@@ -214,10 +237,13 @@ Under the **Settings** section:
After you have configured the mappings and the settings, return to the app overview page and select **Start provisioning** to start automatic SCIM provisioning of users in GitLab.
-WARNING:
+{{< alert type="warning" >}}
+
Once synchronized, changing the field mapped to `id` and `externalId` might cause errors. These include
provisioning errors, duplicate users, and might prevent existing users from accessing the GitLab group.
+{{< /alert >}}
+
## Remove access
Removing or deactivating a user on the identity provider blocks the user on
@@ -228,8 +254,12 @@ To update the user SCIM identity, use the
### Reactivate access
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379149) in GitLab 16.0 [with a flag](../feature_flags.md) named `skip_saml_identity_destroy_during_scim_deprovision`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121226) in GitLab 16.4. Feature flag `skip_saml_identity_destroy_during_scim_deprovision` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379149) in GitLab 16.0 [with a flag](../feature_flags.md) named `skip_saml_identity_destroy_during_scim_deprovision`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121226) in GitLab 16.4. Feature flag `skip_saml_identity_destroy_during_scim_deprovision` removed.
+
+{{< /history >}}
After a user is removed or deactivated through SCIM, you can reactivate that user by
adding them to the SCIM identity provider.
diff --git a/doc/administration/settings/security_and_compliance.md b/doc/administration/settings/security_and_compliance.md
index 238206e69957706494545a7e8fc68cb59bf059c7..ffbe70e85f7bed02063181eaaf37911253b83d00 100644
--- a/doc/administration/settings/security_and_compliance.md
+++ b/doc/administration/settings/security_and_compliance.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Security and compliance Admin area settings
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The settings for package metadata synchronization are located in the [**Admin** area](_index.md).
diff --git a/doc/administration/settings/security_contact_information.md b/doc/administration/settings/security_contact_information.md
index e8d0aa0c3f1a9aef88eb5d70824a3979b26c3b85..e726318c7c6eef2579e037d973fd459364557c1a 100644
--- a/doc/administration/settings/security_contact_information.md
+++ b/doc/administration/settings/security_contact_information.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Provide public security contact information
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433210) in GitLab 16.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433210) in GitLab 16.7.
+
+{{< /history >}}
Organizations can facilitate the responsible disclosure of security issues by
providing public contact information. GitLab supports using a
diff --git a/doc/administration/settings/sidekiq_job_limits.md b/doc/administration/settings/sidekiq_job_limits.md
index 6a170277f387819ec5400723e7409f8d1043fb1d..3c9f639bd0bfee153e55454cdd02f17ed14338ca 100644
--- a/doc/administration/settings/sidekiq_job_limits.md
+++ b/doc/administration/settings/sidekiq_job_limits.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sidekiq job size limits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
[Sidekiq](../sidekiq/_index.md) jobs get stored in
Redis. To avoid excessive memory for Redis, we:
diff --git a/doc/administration/settings/sign_in_restrictions.md b/doc/administration/settings/sign_in_restrictions.md
index 2860d9af7923deb90cdc94a1f049267d65f1d7f2..c4b0c32309742ff5d5b12b24e35419bdbf7b10a1 100644
--- a/doc/administration/settings/sign_in_restrictions.md
+++ b/doc/administration/settings/sign_in_restrictions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sign-in restrictions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can use **Sign-in restrictions** to customize authentication restrictions for web interfaces as well as Git over HTTP(S).
@@ -183,7 +186,11 @@ see [Email notification for unknown sign-ins](../../user/profile/notifications.m
## Sign-in information
-> - **Sign-in text** setting [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/410885) in GitLab 17.0.
+{{< history >}}
+
+- **Sign-in text** setting [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/410885) in GitLab 17.0.
+
+{{< /history >}}
All users that are not logged in are redirected to the page represented by the configured
**Home page URL** if value is not empty.
diff --git a/doc/administration/settings/sign_up_restrictions.md b/doc/administration/settings/sign_up_restrictions.md
index f4bbb63f67278f1462da5a57409c270b31abf88c..8bfbb296f79fedeb90cc14cfe3bac32832ea9006 100644
--- a/doc/administration/settings/sign_up_restrictions.md
+++ b/doc/administration/settings/sign_up_restrictions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sign-up restrictions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can enforce the following restrictions on sign ups:
@@ -52,16 +55,23 @@ To require administrator approval for new sign ups:
If an administrator disables this setting, the users in pending approval state are
automatically approved in a background job.
-NOTE:
+{{< alert type="note" >}}
+
This setting doesn't apply to LDAP or OmniAuth users. To enforce approvals for new users
signing up using OmniAuth or LDAP, set `block_auto_created_users` to `true` in the
[OmniAuth configuration](../../integration/omniauth.md#configure-common-settings) or
[LDAP configuration](../auth/ldap/_index.md#basic-configuration-settings).
A [user cap](#user-cap) can also be used to enforce approvals for new users.
+{{< /alert >}}
+
## Confirm user email
-> - Soft email confirmation [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107302/diffs) from a feature flag to an application setting in GitLab 15.9.
+{{< history >}}
+
+- Soft email confirmation [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107302/diffs) from a feature flag to an application setting in GitLab 15.9.
+
+{{< /history >}}
You can send confirmation emails during sign up and require that users confirm
their email address before they are allowed to sign in.
@@ -81,12 +91,19 @@ The following settings are available:
## Turn on restricted access
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/501717) in GitLab 17.8.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/501717) in GitLab 17.8.
+
+{{< /history >}}
Use restricted access to prevent overage fees.
Overage fees occur when you exceed the number of licensed users in your subscription,
@@ -132,11 +149,14 @@ If an administrator increases or removes the user cap, users pending approval ar
You can also set up [user caps for individual groups](../../user/group/manage.md#user-cap-for-groups).
-NOTE:
+{{< alert type="note" >}}
+
For instances that use LDAP or OmniAuth, when [administrator approval for new sign-ups](#require-administrator-approval-for-new-sign-ups)
is enabled or disabled, downtime might occur due to changes in the Rails configuration.
You can set a user cap to enforce approvals for new users.
+{{< /alert >}}
+
### Set a user cap
Set a user cap to restrict the number of users who can sign up without administrator approval.
@@ -183,11 +203,18 @@ the minimum number of characters a user must have in their password using the Gi
### Password complexity requirements
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354965) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354965) in GitLab 15.2.
+
+{{< /history >}}
By default, the only requirement for user passwords is [minimum password length](#minimum-password-length-limit).
You can add additional complexity requirements. Changes to password complexity requirements apply to new passwords:
@@ -247,17 +274,27 @@ See the [documentation on setting up an LDAP user filter](../auth/ldap/_index.md
## Turn on administrator approval for role promotions
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433166) in GitLab 16.9 [with a flag](../feature_flags.md) named `member_promotion_management`.
-> - Feature flag `member_promotion_management` [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167757/) from `wip` to `beta` and enabled by default in GitLab 17.5.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433166) in GitLab 16.9 [with a flag](../feature_flags.md) named `member_promotion_management`.
+- Feature flag `member_promotion_management` [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167757/) from `wip` to `beta` and enabled by default in GitLab 17.5.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
+{{< /alert >}}
+
To prevent existing users from being promoted into a billable role in a project or group,
turn on administrator approval for role promotions. You can then approve or reject promotion requests
that are [pending administrator approval](../moderate_users.md#view-users-pending-role-promotion).
diff --git a/doc/administration/settings/slack_app.md b/doc/administration/settings/slack_app.md
index 9efffd338436bcc5dae50f7ab192681e529a63d0..b7c176ae6e7718803c7769ee158074db1b3971c5 100644
--- a/doc/administration/settings/slack_app.md
+++ b/doc/administration/settings/slack_app.md
@@ -5,15 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab for Slack app administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for GitLab Self-Managed in GitLab 16.2.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for GitLab Self-Managed in GitLab 16.2.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
This page contains administrator documentation for the GitLab for Slack app. For user documentation, see [GitLab for Slack app](../../user/project/integrations/gitlab_slack_application.md).
+{{< /alert >}}
+
The GitLab for Slack app distributed through the Slack App Directory only works with GitLab.com.
On GitLab Self-Managed, you can create your own copy of the GitLab for Slack app from a [manifest file](https://api.slack.com/reference/manifests#creating_apps) and configure your instance.
@@ -71,9 +81,13 @@ To use Slash commands for a project, configure the [GitLab for Slack app](../../
## Install the GitLab for Slack app
-> - Installation for a specific instance [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391526) in GitLab 16.10 [with a flag](../feature_flags.md) named `gitlab_for_slack_app_instance_and_group_level`. Disabled by default.
-> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147820) in GitLab 16.11.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175803) in GitLab 17.8. Feature flag `gitlab_for_slack_app_instance_and_group_level` removed.
+{{< history >}}
+
+- Installation for a specific instance [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391526) in GitLab 16.10 [with a flag](../feature_flags.md) named `gitlab_for_slack_app_instance_and_group_level`. Disabled by default.
+- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147820) in GitLab 16.11.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175803) in GitLab 17.8. Feature flag `gitlab_for_slack_app_instance_and_group_level` removed.
+
+{{< /history >}}
Prerequisites:
diff --git a/doc/administration/settings/terms.md b/doc/administration/settings/terms.md
index 36466e1c2b550453bfd9cf7fc4c296403cb9b68d..568d83c2345e865915646e666dec5019858c854d 100644
--- a/doc/administration/settings/terms.md
+++ b/doc/administration/settings/terms.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Terms of Service and Privacy Policy
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
An administrator can enforce acceptance of a terms of service and privacy policy.
When this option is enabled, new and existing users must accept the terms.
diff --git a/doc/administration/settings/terraform_limits.md b/doc/administration/settings/terraform_limits.md
index 9d0ff0c405dca5eb42ff73c50b64b3f3a2b3c848..f1a396c50907bb6c113a3928d831214cf91c817c 100644
--- a/doc/administration/settings/terraform_limits.md
+++ b/doc/administration/settings/terraform_limits.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Terraform limits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352951) in GitLab 15.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352951) in GitLab 15.7.
+
+{{< /history >}}
You can limit the total storage of [Terraform state files](../terraform_state.md).
The limit applies to each individual
diff --git a/doc/administration/settings/third_party_offers.md b/doc/administration/settings/third_party_offers.md
index 24010e767ac1ee817b0aa85031fb441c2b9ff2fe..c9606d79a327fddddf9b710a99acee0e956ce9a7 100644
--- a/doc/administration/settings/third_party_offers.md
+++ b/doc/administration/settings/third_party_offers.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Customer experience improvement and third-party offers
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Within GitLab, we inform users of available third-party offers they might find valuable in order
to enhance the development of their projects. An example is the Google Cloud Platform free credit
diff --git a/doc/administration/settings/usage_statistics.md b/doc/administration/settings/usage_statistics.md
index 11fe6596004eb97d02e229b22079e82882f845ff..319e50165db99e27ad080ef7b72c5802cb8510a9 100644
--- a/doc/administration/settings/usage_statistics.md
+++ b/doc/administration/settings/usage_statistics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Usage statistics
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab Inc. periodically collects information about your instance in order
to perform various actions.
@@ -43,9 +46,12 @@ GitLab Enterprise Edition can receive paid features by registering with GitLab a
activity data through Service Ping. Features introduced here do not remove the feature from its paid
tier. Instances on a paid tier are subject to our [Product Usage Data policy](https://handbook.gitlab.com/handbook/legal/privacy/customer-product-usage-information/) managed by [Cloud Licensing](https://about.gitlab.com/pricing/licensing-faq/cloud-licensing/).
-NOTE:
+{{< alert type="note" >}}
+
Registration is not required for participation.
+{{< /alert >}}
+
### Available features
In the following table, you can see:
@@ -134,13 +140,16 @@ If your GitLab instance is behind a proxy, set the appropriate
## Enable or disable Service Ping
-NOTE:
+{{< alert type="note" >}}
+
Whether you can disable Service Ping completely depends on the instance's tier and the specific license.
For more information, see [Customer Product Usage Information](https://handbook.gitlab.com/handbook/legal/privacy/customer-product-usage-information/#service-ping-formerly-known-as-usage-ping).
Service Ping settings only control whether the data is being shared with GitLab, or limited to only internal use by the instance.
Even if you disable Service Ping, the `gitlab_service_ping_worker` background job still periodically generates a Service Ping payload for your instance.
The payload is available in the [Metrics and profiling](#manually-upload-service-ping-payload) admin section.
+{{< /alert >}}
+
### Through the UI
To enable or disable Service Ping:
@@ -156,9 +165,9 @@ To enable or disable Service Ping:
To disable Service Ping and prevent it from being configured in the future through
the **Admin** area.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -172,7 +181,9 @@ the **Admin** area.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -190,7 +201,9 @@ the **Admin** area.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Enable or disable optional data in Service Ping
@@ -209,9 +222,9 @@ To enable or disable optional data in Service Ping:
### Through the configuration file
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -225,7 +238,9 @@ To enable or disable optional data in Service Ping:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -243,7 +258,9 @@ To enable or disable optional data in Service Ping:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Access the Service Ping payload
diff --git a/doc/administration/settings/user_and_ip_rate_limits.md b/doc/administration/settings/user_and_ip_rate_limits.md
index 3d1e8197107bfbb44f20013ac4571dddda8ade82..21aafe30f68a0258c97e83c7a567b69966ae16ed 100644
--- a/doc/administration/settings/user_and_ip_rate_limits.md
+++ b/doc/administration/settings/user_and_ip_rate_limits.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User and IP rate limits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Rate limiting is a common technique used to improve the security and durability
of a web application. For more details, see
@@ -20,13 +23,18 @@ The following limits are disabled by default:
- [Authenticated API requests (per user)](#enable-authenticated-api-request-rate-limit).
- [Authenticated web requests (per user)](#enable-authenticated-web-request-rate-limit).
-NOTE:
+{{< alert type="note" >}}
+
By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations
may trigger the rate limits configured for unauthenticated requests.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The rate limits for API requests don't affect requests made by the frontend, as these are always
counted as web traffic.
+{{< /alert >}}
## Enable unauthenticated API request rate limit
@@ -99,7 +107,11 @@ To use a custom response:
## Maximum authenticated requests to `project/:id/jobs` per minute
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129319) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129319) in GitLab 16.5.
+
+{{< /history >}}
To reduce timeouts, the `project/:id/jobs` endpoint has a default [rate limit](../../security/rate_limits.md#project-jobs-api-endpoint) of 600 calls per authenticated user.
diff --git a/doc/administration/settings/visibility_and_access_controls.md b/doc/administration/settings/visibility_and_access_controls.md
index 0808c320e577728dd0847817c0fee3e0f9d03065..5dc7d92f2f1a6f51b51f360c67e624edcee3ed9d 100644
--- a/doc/administration/settings/visibility_and_access_controls.md
+++ b/doc/administration/settings/visibility_and_access_controls.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Control project visibility, creation, retention, and deletion on GitLab Self-Managed."
+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
+description: Control project visibility, creation, retention, and deletion on GitLab Self-Managed.
title: Control access and visibility
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab enables users with administrator access to enforce
specific controls on branches, projects, snippets, groups, and more.
@@ -44,17 +47,27 @@ Prerequisites:
- Developers and Maintainers.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
If you select **Administrators** and [Admin Mode](sign_in_restrictions.md#admin-mode)
is turned on, administrators must enter Admin Mode to create new projects.
+{{< /alert >}}
+
## Restrict project deletion to administrators
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
-> - User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1.
+- User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1.
+
+{{< /history >}}
Prerequisites:
@@ -77,21 +90,32 @@ To disable the restriction:
## Deletion protection
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) from default delayed project deletion in GitLab 15.1.
-> - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1.
-> - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3.
-> - [Removed option to delete immediately](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 15.11 [with a flag](../feature_flags.md) named `always_perform_delayed_deletion`. Disabled by default.
-> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) from default delayed project deletion in GitLab 15.1.
+- [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1.
+- [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3.
+- [Removed option to delete immediately](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 15.11 [with a flag](../feature_flags.md) named `always_perform_delayed_deletion`. Disabled by default.
+- Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+
+{{< /history >}}
These protections help guard against accidental deletion of groups and projects on your instance.
### Retention period
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1.
+
+{{< /history >}}
Groups and projects remain restorable during the retention period you define. By default,
this is 7 days, but you can change it. If you set the retention period to `0` days, GitLab
@@ -106,8 +130,12 @@ any application setting, GitLab:
### Delayed project deletion
-> - User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1.
-> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+{{< history >}}
+
+- User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1.
+- Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+
+{{< /history >}}
Prerequisites:
@@ -118,9 +146,9 @@ Prerequisites:
To configure delayed project deletion:
-::Tabs
+{{< tabs >}}
-:::TabTitle GitLab 16.0 and later
+{{< tab title="GitLab 16.0 and later" >}}
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Settings > General**.
@@ -128,7 +156,9 @@ To configure delayed project deletion:
1. Scroll to **Deletion protection** and set the retention period to a value between `1` and `90` days.
1. Select **Save changes**.
-:::TabTitle GitLab 15.11 and earlier
+{{< /tab >}}
+
+{{< tab title="GitLab 15.11 and earlier" >}}
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Settings > General**.
@@ -140,12 +170,18 @@ To configure delayed project deletion:
default for newly-created groups**, then set the retention period.
1. Select **Save changes**.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Delayed group deletion
-> - User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1.
-> - [Changed to default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) on the Premium and Ultimate tier in GitLab 16.0.
+{{< history >}}
+
+- User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1.
+- [Changed to default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) on the Premium and Ultimate tier in GitLab 16.0.
+
+{{< /history >}}
Groups remain restorable if the retention period is `1` or more days.
@@ -227,9 +263,13 @@ For more details on group visibility, see
## Restrict visibility levels
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124649) in GitLab 16.3 to prevent restricting default project and group visibility, [with a flag](../feature_flags.md) named `prevent_visibility_restriction`. Disabled by default.
-> - `prevent_visibility_restriction` [enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131203) by default in GitLab 16.4.
-> - `prevent_visibility_restriction` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/433280) in GitLab 16.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124649) in GitLab 16.3 to prevent restricting default project and group visibility, [with a flag](../feature_flags.md) named `prevent_visibility_restriction`. Disabled by default.
+- `prevent_visibility_restriction` [enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131203) by default in GitLab 16.4.
+- `prevent_visibility_restriction` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/433280) in GitLab 16.7.
+
+{{< /history >}}
When restricting visibility levels, consider how these restrictions interact
with permissions for subgroups and projects that inherit their visibility from
@@ -261,10 +301,13 @@ Prerequisites:
- Only administrators can create private groups, projects, and snippets.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
You cannot restrict a visibility level that is set as the default for new projects or groups.
Conversely, you cannot set a restricted visibility level as the default for new projects or groups.
+{{< /alert >}}
+
## Configure enabled Git access protocols
With GitLab access restrictions, you can select the protocols users can use to
@@ -293,11 +336,14 @@ Prerequisites:
- Only HTTP(S).
1. Select **Save changes**.
-WARNING:
+{{< alert type="warning" >}}
+
GitLab [allows the HTTP(S) protocol](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18021)
for Git clone or fetch requests performed [with GitLab CI/CD job tokens](../../ci/jobs/ci_job_token.md).
This happens even if you select **Only SSH**, because GitLab Runner and CI/CD jobs require this setting.
+{{< /alert >}}
+
## Customize Git clone URL for HTTP(S)
You can customize project Git clone URLs for HTTP(S), which affects the clone
@@ -360,8 +406,12 @@ Prerequisites:
## Configure globally-allowed IP address ranges
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87579) in GitLab 15.1 [with a flag](../feature_flags.md) named `group_ip_restrictions_allow_global`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) in GitLab 15.4. [Feature flag `group_ip_restrictions_allow_global`](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87579) in GitLab 15.1 [with a flag](../feature_flags.md) named `group_ip_restrictions_allow_global`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) in GitLab 15.4. [Feature flag `group_ip_restrictions_allow_global`](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) removed.
+
+{{< /history >}}
Administrators can combine IP address ranges with
[IP restrictions per group](../../user/group/access_and_permissions.md#restrict-group-access-by-ip-address).
diff --git a/doc/administration/sidekiq/_index.md b/doc/administration/sidekiq/_index.md
index e3060eec86bda5c5a3a4b5dcd647e264043a25fd..11c09d01a4dacbf90558eafbce2053f71b8320a1 100644
--- a/doc/administration/sidekiq/_index.md
+++ b/doc/administration/sidekiq/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure an external Sidekiq instance
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can configure an external Sidekiq instance by using the Sidekiq that's bundled in the GitLab package. Sidekiq requires connection to the Redis,
PostgreSQL, and Gitaly instances.
@@ -128,7 +131,11 @@ To configure the metrics server:
### Enable HTTPS
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364771) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364771) in GitLab 15.2.
+
+{{< /history >}}
To serve metrics via HTTPS instead of HTTP, enable TLS in the exporter settings:
diff --git a/doc/administration/sidekiq/extra_sidekiq_processes.md b/doc/administration/sidekiq/extra_sidekiq_processes.md
index daff5fec65424c31a316b1d7f189441b0642c594..66b8d81c6e20e4ac476d7dddd00496adffbfd63f 100644
--- a/doc/administration/sidekiq/extra_sidekiq_processes.md
+++ b/doc/administration/sidekiq/extra_sidekiq_processes.md
@@ -5,17 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Run multiple Sidekiq processes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab allows you to start multiple Sidekiq processes to process background jobs
at a higher rate on a single instance. By default, Sidekiq starts one worker
process and only uses a single core.
-NOTE:
+{{< alert type="note" >}}
+
The information in this page applies only to Linux package installations.
+{{< /alert >}}
+
## Start multiple processes
When starting multiple processes, the number of processes should at most equal
@@ -82,7 +88,11 @@ for more details.
#### Manage thread counts with concurrency field
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439687) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439687) in GitLab 16.9.
+
+{{< /history >}}
In GitLab 16.9 and later, you can set the concurrency by setting `concurrency`. This value explicitly sets each process
with this amount of concurrency.
@@ -122,11 +132,14 @@ processes:
## Troubleshoot using the CLI
-WARNING:
+{{< alert type="warning" >}}
+
It's recommended to use `/etc/gitlab/gitlab.rb` to configure the Sidekiq processes.
If you experience a problem, you should contact GitLab support. Use the command
line at your own risk.
+{{< /alert >}}
+
For debugging purposes, you can start extra Sidekiq processes by using the command
`/opt/gitlab/embedded/service/gitlab-rails/bin/sidekiq-cluster`. This command
takes arguments using the following syntax:
diff --git a/doc/administration/sidekiq/processing_specific_job_classes.md b/doc/administration/sidekiq/processing_specific_job_classes.md
index 719de02c052b7799112defb7738e9c850bd656ff..15298d213e55b20cd9f95b88bfe06d921c546610 100644
--- a/doc/administration/sidekiq/processing_specific_job_classes.md
+++ b/doc/administration/sidekiq/processing_specific_job_classes.md
@@ -5,11 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Processing specific job classes
---
-WARNING:
+{{< alert type="warning" >}}
+
These are advanced settings. While they are used on GitLab.com, most GitLab
instances should only add more processes that listen to all queues. This is the
same approach described in the [Reference Architectures](../reference_architectures/_index.md).
+{{< /alert >}}
+
Most GitLab instances should have [all processes to listen to all queues](extra_sidekiq_processes.md#start-multiple-processes).
Another alternative is to use [routing rules](#routing-rules) which direct specific
@@ -19,15 +22,22 @@ lowers the load on Redis, which is important on very large-scale deployments.
## Routing rules
-> - [Default routing rule value](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97908) introduced in GitLab 15.4.
-> - Queue selectors [replaced by routing rules](https://gitlab.com/gitlab-org/gitlab/-/issues/390787) in GitLab 17.0.
+{{< history >}}
+
+- [Default routing rule value](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97908) introduced in GitLab 15.4.
+- Queue selectors [replaced by routing rules](https://gitlab.com/gitlab-org/gitlab/-/issues/390787) in GitLab 17.0.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
Mailer jobs cannot be routed by routing rules, and always go to the
`mailers` queue. When using routing rules, ensure that at least one process is
listening to the `mailers` queue. Typically this can be placed alongside the
`default` queue.
+{{< /alert >}}
+
We recommend most GitLab instances using routing rules to manage their Sidekiq
queues. This allows administrators to choose single queue names for groups of
job classes based on their attributes. The syntax is an ordered array of pairs of `[query, queue]`:
diff --git a/doc/administration/sidekiq/sidekiq_health_check.md b/doc/administration/sidekiq/sidekiq_health_check.md
index b1c9c1e584cbb05920974c395ef55e48de06c89d..b81eb05a71520163a3d7b28837a26fcfdb92b2d0 100644
--- a/doc/administration/sidekiq/sidekiq_health_check.md
+++ b/doc/administration/sidekiq/sidekiq_health_check.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sidekiq health check
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides liveness and readiness probes to indicate service health and
reachability to the Sidekiq cluster. These endpoints
diff --git a/doc/administration/sidekiq/sidekiq_job_migration.md b/doc/administration/sidekiq/sidekiq_job_migration.md
index a1dc64c424c35ba35869a83fe0712268e710a251..18d8bf379e05a92375565ceb9cb85b894166c213 100644
--- a/doc/administration/sidekiq/sidekiq_job_migration.md
+++ b/doc/administration/sidekiq/sidekiq_job_migration.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sidekiq job migration Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This operation should be very uncommon. We do not recommend it for the vast majority of GitLab instances.
+{{< /alert >}}
+
Sidekiq routing rules allow administrators to re-route certain background jobs from their regular queue to an alternative queue. By default, GitLab uses one queue per background job type. GitLab has over 400 background job types, and so correspondingly it has over 400 queues.
Most administrators do not need to change this setting. In some cases with particularly large background job processing workloads, Redis performance may suffer due to the number of queues that GitLab listens to.
diff --git a/doc/administration/sidekiq/sidekiq_troubleshooting.md b/doc/administration/sidekiq/sidekiq_troubleshooting.md
index 4d9987494dcd8f65232407b20fe60178cecea71c..aad5747c149b941eb88f5a6af8907990df22da70 100644
--- a/doc/administration/sidekiq/sidekiq_troubleshooting.md
+++ b/doc/administration/sidekiq/sidekiq_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Sidekiq
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Sidekiq is the background job processor GitLab uses to asynchronously run
tasks. When things go wrong it can be difficult to troubleshoot. These
@@ -231,7 +234,7 @@ function in Rugged. In the stack, we can see `rev_parse` is being called by the
in [containerized environments](https://rbspy.github.io/using-rbspy/index.html#containers).
It requires at least the `SYS_PTRACE` capability, otherwise it terminates with a `permission denied` error.
-::Tabs
+{{< tabs >}}
::: TabTitle Kubernetes
@@ -242,13 +245,15 @@ securityContext:
- SYS_PTRACE
```
-:::TabTitle Docker
+{{< tab title="Docker" >}}
```shell
docker run --cap-add SYS_PTRACE [...]
```
-:::TabTitle Docker Compose
+{{< /tab >}}
+
+{{< tab title="Docker Compose" >}}
```yaml
services:
@@ -258,7 +263,9 @@ services:
- SYS_PTRACE
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Process profiling with `perf`
diff --git a/doc/administration/silent_mode/_index.md b/doc/administration/silent_mode/_index.md
index 2c061494d6b663ea05deb28336a3fac1d53fb229..7c9ead3123958283d6138d0da2bbcd1e3ceedf22 100644
--- a/doc/administration/silent_mode/_index.md
+++ b/doc/administration/silent_mode/_index.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Silent Mode
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9826) in GitLab 15.11. This feature was an [experiment](../../policy/development_stages_support.md#experiment).
-> - Enabling and disabling Silent Mode through the web UI was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131090) in GitLab 16.4.
-> - [Generally available](../../policy/development_stages_support.md#generally-available) in GitLab 16.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9826) in GitLab 15.11. This feature was an [experiment](../../policy/development_stages_support.md#experiment).
+- Enabling and disabling Silent Mode through the web UI was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131090) in GitLab 16.4.
+- [Generally available](../../policy/development_stages_support.md#generally-available) in GitLab 16.6.
+
+{{< /history >}}
Silent Mode allows you to silence outbound communication, such as emails, from GitLab. Silent Mode is not intended to be used on environments which are in-use. Two use-cases are:
diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md
index ad9b8951050fe8dfad678bbf566c762c0b32a935..4d511fa6e79a215359556892d84632d658a5bde9 100644
--- a/doc/administration/smime_signing_email.md
+++ b/doc/administration/smime_signing_email.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Signing outgoing email with S/MIME
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Notification emails sent by GitLab can be signed with S/MIME for improved
security.
@@ -29,10 +32,13 @@ files must be provided:
Optionally, you can also provide a bundle of CA certs (PEM-encoded) to be
included on each signature. This is typically an intermediate CA.
-WARNING:
+{{< alert type="warning" >}}
+
Be mindful of the access levels for your private keys and visibility to
third parties.
+{{< /alert >}}
+
For Linux package installations:
1. Edit `/etc/gitlab/gitlab.rb` and adapt the file paths:
diff --git a/doc/administration/snippets/_index.md b/doc/administration/snippets/_index.md
index 9feb93e40e9647c80283a3b63f9e2d720815a99b..c43e90f0dcff8d15ab0a84fff7c50045abf03f78 100644
--- a/doc/administration/snippets/_index.md
+++ b/doc/administration/snippets/_index.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Configure snippets settings for your GitLab instance."
+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
+description: Configure snippets settings for your GitLab instance.
title: Snippets
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can configure a maximum size for a snippet to prevent abuse.
The default limit is 52428800 bytes (50 MB).
diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md
index f26ca4785e38e32b6b41e10af686808f79c01f0a..777747b11e0de5199e16b1da7ef716127595036b 100644
--- a/doc/administration/static_objects_external_storage.md
+++ b/doc/administration/static_objects_external_storage.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Remote Development
-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"
-description: "Configure external storage, such as a CDN, for static objects in your GitLab repository."
+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
+description: Configure external storage, such as a CDN, for static objects in your GitLab repository.
title: External storage for static objects
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Configure GitLab to serve repository static objects (such as archives or raw blobs) from external
storage such as a content delivery network (CDN).
diff --git a/doc/administration/system_hooks.md b/doc/administration/system_hooks.md
index 6458c6c3bb623d5f071ae99651f5adc146e9f6a2..10475c14b7dcab44129dc19048b618f01f7b606d 100644
--- a/doc/administration/system_hooks.md
+++ b/doc/administration/system_hooks.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: System hooks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
System hooks (not to be confused with [server hooks](server_hooks.md) or [file hooks](file_hooks.md)) perform HTTP POST
requests and are triggered on the following events:
@@ -52,12 +55,19 @@ As an example, use system hooks for logging or changing information in an LDAP s
You can also enable triggers for other events, such as push events, and disable the `repository_update` event
when you create a system hook.
-NOTE:
+{{< alert type="note" >}}
+
For push and tag events, the same structure and deprecations are followed as [project and group webhooks](../user/project/integrations/webhooks.md). However, commits are never displayed.
+{{< /alert >}}
+
## Create a system hook
-> - **Name** and **Description** [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141977) in GitLab 16.9.
+{{< history >}}
+
+- **Name** and **Description** [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141977) in GitLab 16.9.
+
+{{< /history >}}
To create a system hook:
diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md
index 442f4c4f999b1325f176d6d8c27e7d4d69fc3337..a8516828d3e4442851cb5b8028be39de5fe2e549 100644
--- a/doc/administration/terraform_state.md
+++ b/doc/administration/terraform_state.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Terraform state administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab can be used as a backend for [Terraform](../user/infrastructure/_index.md) state
files. The files are encrypted before being stored. This feature is enabled by default.
@@ -93,9 +96,12 @@ For self-compiled installations:
## Using object storage
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Instead of storing Terraform state files on disk, we recommend the use of
[one of the supported object storage options](object_storage.md#supported-object-storage-providers).
@@ -118,11 +124,14 @@ The following settings are:
### Migrate to object storage
-WARNING:
+{{< alert type="warning" >}}
+
It's not possible to migrate Terraform state files from object storage back to local storage,
so proceed with caution. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/350187)
to change this behavior.
+{{< /alert >}}
+
To migrate Terraform state files to object storage:
- For Linux package installations:
@@ -167,9 +176,9 @@ This section describes the earlier configuration format.
See [the available connection settings for different providers](object_storage.md#configure-the-connection-settings).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines; replacing with
the values you want:
@@ -185,8 +194,11 @@ See [the available connection settings for different providers](object_storage.m
}
```
- NOTE:
- If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
+ {{< alert type="note" >}}
+
+ If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
+
+ {{< /alert >}}
```ruby
gitlab_rails['terraform_state_object_store_connection'] = {
@@ -199,7 +211,9 @@ See [the available connection settings for different providers](object_storage.m
1. Save the file and [reconfigure GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
1. [Migrate any existing local states to the object storage](#migrate-to-object-storage)
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
@@ -220,7 +234,9 @@ See [the available connection settings for different providers](object_storage.m
1. Save the file and [restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect.
1. [Migrate any existing local states to the object storage](#migrate-to-object-storage)
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Find a Terraform state file path
diff --git a/doc/administration/timezone.md b/doc/administration/timezone.md
index cf0a3a6b971cfd5622c8fef6c41850be8974f7d8..9bd1c590834b9c345335091a00cd705b1ae94ae3 100644
--- a/doc/administration/timezone.md
+++ b/doc/administration/timezone.md
@@ -5,16 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Change your time zone
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
Users can set their [time zone in their profile](../user/profile/_index.md#set-your-time-zone).
New users do not have a default time zone and must
explicitly set it before it displays on their profile.
On GitLab.com, the default time zone is UTC.
+{{< /alert >}}
+
The default time zone in GitLab is UTC, but you can change it to your liking.
To update the time zone of your GitLab instance:
@@ -29,9 +35,9 @@ To update the time zone of your GitLab instance:
1. Change the time zone, for example to `America/New_York`.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -46,7 +52,9 @@ To update the time zone of your GitLab instance:
sudo gitlab-ctl restart
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -67,7 +75,9 @@ To update the time zone of your GitLab instance:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -86,7 +96,9 @@ To update the time zone of your GitLab instance:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -106,4 +118,6 @@ To update the time zone of your GitLab instance:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/administration/troubleshooting/_index.md b/doc/administration/troubleshooting/_index.md
index 3390f692a7405e9bf07e838277eca25b4b1aaea5..9d3da52f2827d3f0f18b0a688fe31f72becdd322 100644
--- a/doc/administration/troubleshooting/_index.md
+++ b/doc/administration/troubleshooting/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting a GitLab installation
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page documents a collection of resources to help you troubleshoot a GitLab
installation.
@@ -40,11 +43,14 @@ information useful for troubleshooting. However, if you are experiencing trouble
GitLab instance, you should check your [support options](https://about.gitlab.com/support/)
before referring to these documents.
-WARNING:
+{{< alert type="warning" >}}
+
The commands in the following documentation might result in data loss or
other damage to a GitLab instance. They should be used only by experienced administrators
who are aware of the risks.
+{{< /alert >}}
+
- [Diagnostics tools](diagnostics_tools.md)
- [Linux commands](linux_cheat_sheet.md)
- [Troubleshooting Kubernetes](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html)
diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md
index 5d35ad370249aa74d5b4cea84e25bc2ec34c5f38..cef652c4a06a4f63c6e8233e5ca22ea8eefe8843 100644
--- a/doc/administration/troubleshooting/diagnostics_tools.md
+++ b/doc/administration/troubleshooting/diagnostics_tools.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Diagnostics tools
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
These are some of the diagnostics tools the GitLab Support team uses during troubleshooting.
They are listed here for transparency, and for users with experience
diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md
index 1eb81d671e50b88fc950fe5c3b737d4cddf52de8..d4be56891f716884b44be099db8019f0c385b935 100644
--- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md
+++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Rails Console Cheat Sheet
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This was the GitLab Support Team's collection of information regarding the GitLab Rails
console, for use while troubleshooting. It is listed here for posterity,
@@ -21,19 +24,24 @@ our guide on [the Rails console](../operations/rails_console.md),
and your [support options](https://about.gitlab.com/support/),
before attempting the information pointed to from here.
-WARNING:
+{{< alert type="warning" >}}
+
Some of these scripts could be damaging if not run correctly,
or under the right conditions. We highly recommend running them under the
guidance of a Support Engineer, or running them in a test environment with a
backup of the instance ready to be restored, just in case.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
As GitLab changes, changes to the code are inevitable,
and so some scripts may not work as they once used to. These are not kept
up-to-date as these scripts/commands were added as they were found/needed. As
mentioned above, we recommend running these scripts under the supervision of a
Support Engineer, who can also verify that they continue to work as they
should and, if needed, update the script for the latest version of GitLab.
+{{< /alert >}}
## Mirrors
diff --git a/doc/administration/troubleshooting/linux_cheat_sheet.md b/doc/administration/troubleshooting/linux_cheat_sheet.md
index 7494c62a580a2b09dc5eb22d9069f02f20153a13..1747482cf1fdf7fb5c16290b0161b77028a6512e 100644
--- a/doc/administration/troubleshooting/linux_cheat_sheet.md
+++ b/doc/administration/troubleshooting/linux_cheat_sheet.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Linux cheat sheet
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This is the GitLab Support Team's collection of information regarding Linux, that they
sometimes use while troubleshooting. It is listed here for transparency,
@@ -15,11 +18,14 @@ and for users with experience with Linux. If you are currently
having an issue with GitLab, you may want to check your [support options](https://about.gitlab.com/support/)
first, before attempting to use this information.
-WARNING:
+{{< alert type="warning" >}}
+
It is [beyond the scope of GitLab Support to assist in systems administration](https://about.gitlab.com/support/statement-of-support/#training). GitLab administrators are expected to know these commands for their distribution
of choice. If you are a GitLab Support Engineer, consider this a cross-reference to
translate `yum` -> `apt-get` and the like.
+{{< /alert >}}
+
Most of the commands below have not been labeled as to which distribution they work
on. Contributions are welcome to help add them.
diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md
index 3ae850660e64ff80a6cbe5064169df21cc7116f8..c8403113caf7461ffe39382fa1547e32094fa0a6 100644
--- a/doc/administration/troubleshooting/postgresql.md
+++ b/doc/administration/troubleshooting/postgresql.md
@@ -5,27 +5,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: PostgreSQL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page contains information about PostgreSQL the GitLab Support team uses
when troubleshooting. GitLab makes this information public, so that anyone can
make use of the Support team's collected knowledge.
-WARNING:
+{{< alert type="warning" >}}
+
Some procedures documented here may break your GitLab instance. Use at your
own risk.
+{{< /alert >}}
+
If you're on a [paid tier](https://about.gitlab.com/pricing/) and aren't sure
how to use these commands, [contact Support](https://about.gitlab.com/support/)
for assistance with any issues you're having.
## Start a database console
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
Recommended for:
@@ -44,13 +50,17 @@ it takes longer to initialize:
sudo gitlab-rails db-console --database main
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
docker exec -it <container-id> gitlab-psql
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Use the `psql` command that's part of [your PostgreSQL installation](../../install/installation.md#7-database).
@@ -58,7 +68,9 @@ Use the `psql` command that's part of [your PostgreSQL installation](../../insta
sudo -u git -H psql -d gitlabhq_production
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
- If you run a hybrid environment, and PostgreSQL runs on a Linux packaged installation (Omnibus),
the recommended approach is to use the database console locally on those servers. Refer to the details
@@ -67,7 +79,9 @@ sudo -u git -H psql -d gitlabhq_production
- Run `gitlab-rails db-console` in the toolbox pod.
- Refer to our [Kubernetes cheat sheet](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html#gitlab-specific-kubernetes-information) for details.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To exit the console, type: `quit`.
@@ -135,7 +149,8 @@ Quoting from issue [#30528](https://gitlab.com/gitlab-org/gitlab/-/issues/30528)
<!-- vale gitlab_base.FutureTense = YES -->
-NOTE:
+{{< alert type="note" >}}
+
In Support, our general approach to reconfiguring timeouts (applies also to the
HTTP stack) is that it's acceptable to do it temporarily as a workaround. If it
makes GitLab usable for the customer, then it buys time to understand the
@@ -143,6 +158,8 @@ problem more completely, implement a hot fix, or make some other change that
addresses the root cause. Generally, the timeouts should be put back to
reasonable defaults after the root cause is resolved.
+{{< /alert >}}
+
In this case, the guidance we had from development was to drop `deadlock_timeout`
or `statement_timeout`, but to leave the third setting at 60 seconds. Setting
`idle_in_transaction` protects the database from sessions potentially hanging for
@@ -185,17 +202,23 @@ postgresql['idle_in_transaction_session_timeout'] = '60s'
Once saved, [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-NOTE:
+{{< alert type="note" >}}
+
These are Linux package settings. If an external database, such as a customer's PostgreSQL installation
or Amazon RDS is being used, these values don't get set, and would have to be set externally.
+{{< /alert >}}
+
### Temporarily changing the statement timeout
-WARNING:
+{{< alert type="warning" >}}
+
The following advice does not apply in case
[PgBouncer](../postgresql/pgbouncer.md) is enabled,
because the changed timeout might affect more transactions than intended.
+{{< /alert >}}
+
In some situations, it may be desirable to set a different statement timeout
without having to [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation),
which in this case would restart Puma and Sidekiq.
diff --git a/doc/administration/troubleshooting/test_environments.md b/doc/administration/troubleshooting/test_environments.md
index b9bbe426282f40128e4d4bd6a602df94c2ee6371..29dc8e41af2691f586677c1901c0935230ea38f9 100644
--- a/doc/administration/troubleshooting/test_environments.md
+++ b/doc/administration/troubleshooting/test_environments.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Apps for a testing environment
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This is the GitLab Support Team's collection of information regarding testing environments,
for use while troubleshooting. It is listed here for transparency, and it may be useful
@@ -15,10 +18,13 @@ for users with experience with these tools. If you are currently having an issue
GitLab, you may want to check your [support options](https://about.gitlab.com/support/)
first, before attempting to use this information.
-NOTE:
+{{< alert type="note" >}}
+
This page was initially written for Support Engineers, so some of the links
are only available internally at GitLab.
+{{< /alert >}}
+
## Docker
The following were tested on Docker containers running in the cloud. Support Engineers,
diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md
index 49dba5e94cd9d60c09f3d14dec15dac71683d3e3..af4776beb6d618e5073dafb6192c794b41ddeeb2 100644
--- a/doc/administration/uploads.md
+++ b/doc/administration/uploads.md
@@ -5,27 +5,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Uploads administration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Uploads represent all user data that may be sent to GitLab as a single file. For example, avatars and note attachments are uploads. Uploads are integral to GitLab functionality and therefore cannot be disabled.
-NOTE:
+{{< alert type="note" >}}
+
Attachments added to comments or descriptions are deleted **only** when the parent project or group
is deleted. Attachments remain in file storage even when the comment or resource (like issue, merge
request, epic) where they were uploaded is deleted.
+{{< /alert >}}
+
## Using local storage
This is the default configuration. To change the location where the uploads are
stored locally, use the steps in this section based on your installation method:
-NOTE:
+{{< alert type="note" >}}
+
For historical reasons, uploads for the whole instance (for example the [favicon](appearance.md#customize-the-favicon)) are stored in a base directory,
which by default is `uploads/-/system`. Changing the base
directory on an existing GitLab installation is strongly discouraged.
+{{< /alert >}}
+
For Linux package installations:
_The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/uploads`._
@@ -59,9 +68,12 @@ _The uploads are stored by default in
## Using object storage
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you don't want to use the local disk where GitLab is installed to store the
uploads, you can use an object storage provider like AWS S3 instead.
diff --git a/doc/administration/user_cohorts.md b/doc/administration/user_cohorts.md
index fa97b5d56b50e02cf6f65acb6f73c200fe2dd71e..09a236cbd414cdca1a8b6cb60fb21a5c259fdeb2 100644
--- a/doc/administration/user_cohorts.md
+++ b/doc/administration/user_cohorts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User Cohorts
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can analyze your users' GitLab activities over time.
diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md
index 154e1d409a0884ac7525859718ff4ccc5879ccb9..767d1cb4293109d1b43ea7f0e458000572076a7e 100644
--- a/doc/administration/user_settings.md
+++ b/doc/administration/user_settings.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Modify global user settings
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can modify settings for every user in your GitLab instance.
@@ -28,9 +31,9 @@ To prevent new users from creating top-level groups:
- The [Application settings API](../api/settings.md#update-application-settings).
- In GitLab 15.4 and earlier, modify a configuration file:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -40,7 +43,9 @@ To prevent new users from creating top-level groups:
1. [Reconfigure and restart GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `config/gitlab.yml` and uncomment the following line:
@@ -50,7 +55,9 @@ To prevent new users from creating top-level groups:
1. [Restart GitLab](restart_gitlab.md#self-compiled-installations).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### For existing users
@@ -63,9 +70,9 @@ To prevent existing users from creating top-level groups, use either:
By default, users can change their usernames. To prevent users from changing their usernames:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -75,7 +82,9 @@ By default, users can change their usernames. To prevent users from changing the
1. [Reconfigure and restart GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `config/gitlab.yml` and uncomment the following line:
@@ -85,7 +94,9 @@ By default, users can change their usernames. To prevent users from changing the
1. [Restart GitLab](restart_gitlab.md#self-compiled-installations).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Prevent Guest users from promoting to a higher role
diff --git a/doc/administration/whats-new.md b/doc/administration/whats-new.md
index cc6dfe346fc100bd62b4a00dd7be3f6228b570f3..ed5f9335b1d8ed887c46e4bef20557898a9d9feb 100644
--- a/doc/administration/whats-new.md
+++ b/doc/administration/whats-new.md
@@ -5,9 +5,12 @@ info: For assistance with this What's new page, see https://handbook.gitlab.com/
title: What's new
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can view some of the highlights from the last 10
GitLab versions in the **What's new** feature. It lists new features available in different
@@ -18,15 +21,18 @@ All users can see the feature list, but the entries might differ depending on th
- Features only available on GitLab.com are not shown on GitLab Self-Managed instances.
- Features only available to GitLab Self-Managed instances are not shown on GitLab.com.
- NOTE:
- For GitLab Self-Managed, the updated **What's new** is included
+ {{< alert type="note" >}}
+
+For GitLab Self-Managed, the updated **What's new** is included
in the first patch release after a new version, such as `13.10.1`.
+ {{< /alert >}}
+
## Access What's new
To access the **What's new** feature:
-1. On the left sidebar, at the bottom, select **Help** (**{question}**).
+1. On the left sidebar, at the bottom, select **Help** ({{< icon name="question" >}}).
1. Select **What's new** from the menu.
## Configure What's new
@@ -42,6 +48,6 @@ or you can hide it. To configure it:
| ------ | ----------- |
| Enable What's new: All tiers | Presents new features from all tiers. |
| Enable What's new: Current tier only | Presents new features for your current subscription tier, and hides new features outside of your tier. |
- | Disable What's new | Disables this feature, so it no longer displays under the **{question}** icon. |
+ | Disable What's new | Disables this feature, so it no longer displays under the {{< icon name="question" >}} icon. |
1. Select **Save changes**.
diff --git a/doc/administration/wikis/_index.md b/doc/administration/wikis/_index.md
index c20d8ef46812fa27d36b42e894938cf6b724a920..3a7e577cd3791343f732741bb23617c24f6ca8f0 100644
--- a/doc/administration/wikis/_index.md
+++ b/doc/administration/wikis/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Wiki settings
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Adjust the wiki settings of your GitLab instance.
@@ -30,9 +33,12 @@ This setting is not available through the [**Admin** area settings](../settings/
To configure this setting, use either the Rails console
or the [Application settings API](../../api/settings.md).
-NOTE:
+{{< alert type="note" >}}
+
The value of the limit must be in bytes. The minimum value is 1024 bytes.
+{{< /alert >}}
+
#### Through the Rails console
To configure this setting through the Rails console:
@@ -84,7 +90,11 @@ read the documentation on [reducing repository size](../../user/project/reposito
## Allow URI includes for AsciiDoc
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348687) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348687) in GitLab 16.1.
+
+{{< /history >}}
Include directives import content from separate pages or external URLs,
and display them as part of the content of the current document. To enable
diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md
index 87778efee51409a3bb859f31e40bc6445a773eb2..6dbf8f78c60323e9eff81e777b65d463a6d22f17 100644
--- a/doc/api/access_requests.md
+++ b/doc/api/access_requests.md
@@ -1,13 +1,16 @@
---
stage: Software Supply Chain Security
group: Authentication
-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"
+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
title: Group and project access requests API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with access requests for group and projects.
diff --git a/doc/api/admin/token.md b/doc/api/admin/token.md
index 26d13561cf854952119eb0f676f1ca53edc70cb9..83268d63dfc628e3e2f3677b7dea4abf358984e4 100644
--- a/doc/api/admin/token.md
+++ b/doc/api/admin/token.md
@@ -2,14 +2,17 @@
stage: Software Supply Chain Security
group: Authentication
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
-description: "Documentation for the REST API that exposes token information."
+description: Documentation for the REST API that exposes token information.
title: Token information API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
Use this API to retrieve details about arbitrary tokens and to revoke them. Unlike other APIs that expose token information, this API allows you to retrieve details or revoke tokens without knowing the specific type of token.
@@ -23,17 +26,21 @@ Prerequisites:
## Get information on a token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165157) in GitLab 17.5 [with a flag](../../administration/feature_flags.md) named `admin_agnostic_token_finder`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/490572) in GitLab 17.8. Feature flag `admin_agnostic_token_finder` removed.
-> - [Feed tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169821) in GitLab 17.6.
-> - [OAuth application secrets added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172985) in GitLab 17.7.
-> - [Cluster agent tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172932) in GitLab 17.7.
-> - [Runner authentication tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173987) in GitLab 17.7.
-> - [Pipeline trigger tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174030) in GitLab 17.7.
-> - [CI/CD Job Tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175234) in GitLab 17.9.
-> - [Feature flags client tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/177431) in GitLab 17.9.
-> - [GitLab session cookies added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178022) in GitLab 17.9.
-> - [Incoming email tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/177077) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165157) in GitLab 17.5 [with a flag](../../administration/feature_flags.md) named `admin_agnostic_token_finder`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/490572) in GitLab 17.8. Feature flag `admin_agnostic_token_finder` removed.
+- [Feed tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169821) in GitLab 17.6.
+- [OAuth application secrets added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172985) in GitLab 17.7.
+- [Cluster agent tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172932) in GitLab 17.7.
+- [Runner authentication tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173987) in GitLab 17.7.
+- [Pipeline trigger tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174030) in GitLab 17.7.
+- [CI/CD Job Tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175234) in GitLab 17.9.
+- [Feature flags client tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/177431) in GitLab 17.9.
+- [GitLab session cookies added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178022) in GitLab 17.9.
+- [Incoming email tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/177077) in GitLab 17.9.
+
+{{< /history >}}
Gets information for a given token. This endpoint supports the following tokens:
@@ -107,18 +114,25 @@ Example response:
## Revoke a token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170421) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `api_admin_token_revoke`. Disabled by default.
-> - [Cluster agent tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178211) in GitLab 17.9.
-> - [Runner authentication tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/179066) in GitLab 17.9.
-> - [OAuth application secrets added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/179035) in GitLab 17.9.
-> - [Incoming email tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/180763) in GitLab 17.9.
-> - [Feature flags client tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/181096) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170421) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `api_admin_token_revoke`. Disabled by default.
+- [Cluster agent tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178211) in GitLab 17.9.
+- [Runner authentication tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/179066) in GitLab 17.9.
+- [OAuth application secrets added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/179035) in GitLab 17.9.
+- [Incoming email tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/180763) in GitLab 17.9.
+- [Feature flags client tokens added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/181096) in GitLab 17.9.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Revokes or resets a given token based on the token type. This endpoint supports the following token types:
| Token type | Supported action |
diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md
index 64818dd94f737788a1cb3dda2d3e37ea8a050ef1..415b639690e08d709627dcf8edd242fd237e35b4 100644
--- a/doc/api/admin_sidekiq_queues.md
+++ b/doc/api/admin_sidekiq_queues.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sidekiq queues administration API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Delete jobs from a Sidekiq queue that match the given
[metadata](../development/logging.md#logging-context-metadata-through-rails-or-grape-requests).
diff --git a/doc/api/alert_management_alerts.md b/doc/api/alert_management_alerts.md
index 0b449579e5838ce5994176770cb26d5d54d303cc..fcef7ebc79444dca7c6a90a09704f5cb217a2d2c 100644
--- a/doc/api/alert_management_alerts.md
+++ b/doc/api/alert_management_alerts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Alert Management alerts API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Alert Management alerts API is limited to metric images. For more API endpoints, see the
[GraphQL API](graphql/reference/_index.md#alertmanagementalert).
diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md
index bf0f82588a56bc3ed23598237846055a97699e30..93b7ed7035c01751d64b424ce6a5603f66d38785 100644
--- a/doc/api/api_resources.md
+++ b/doc/api/api_resources.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: REST API resources
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Available resources for the [GitLab REST API](_index.md) can be grouped in the following contexts:
diff --git a/doc/api/appearance.md b/doc/api/appearance.md
index 9275c344a5527e61214792155caeb25c92e02666..b1a94b83ead491cfc0343a577b3c33e62476447a 100644
--- a/doc/api/appearance.md
+++ b/doc/api/appearance.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Application appearance API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to control the appearance of your GitLab instance. For more information, see [GitLab Appearance](../administration/appearance.md).
diff --git a/doc/api/applications.md b/doc/api/applications.md
index d0b1d49a37eb7c4f48be0b96fa6303b67b28a6e3..eec7691dc5f3ede8ffec0344fa329cd1d003649f 100644
--- a/doc/api/applications.md
+++ b/doc/api/applications.md
@@ -5,18 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Applications API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact instance-wide OAuth applications for:
- [Using GitLab as an authentication provider](../integration/oauth_provider.md).
- [Allowing access to GitLab resources on a user's behalf](oauth2.md).
-NOTE:
+{{< alert type="note" >}}
+
You cannot use this API to manage group applications or individual user applications.
+{{< /alert >}}
+
Prerequisites:
- You must have administrator access to the instance.
@@ -89,9 +95,12 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
The `secret` value is not exposed by this API.
+{{< /alert >}}
+
## Delete an application
Delete a specific application.
@@ -116,7 +125,11 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git
## Renew an application secret
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422420) in GitLab 16.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422420) in GitLab 16.11.
+
+{{< /history >}}
Renews an application secret. Returns `200` if the request succeeds.
diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md
index 821740d8af4744300f4c02af57e9c5351fa72172..fcc87ace46752eb0eddabab0a18cb8c21878628c 100644
--- a/doc/api/audit_events.md
+++ b/doc/api/audit_events.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Audit events API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Author Email added to the response body](https://gitlab.com/gitlab-org/gitlab/-/issues/386322) in GitLab 15.9.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Author Email added to the response body](https://gitlab.com/gitlab-org/gitlab/-/issues/386322) in GitLab 15.9.
+
+{{< /history >}}
## Instance audit events
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to retrieve instance audit events.
@@ -23,8 +33,12 @@ To retrieve audit events using the API, you must [authenticate yourself](rest/au
### Retrieve all instance audit events
-> - Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367528) in GitLab 15.11.
-> - Entity type `Gitlab::Audit::InstanceScope` for instance audit events [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418185) in GitLab 16.2.
+{{< history >}}
+
+- Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367528) in GitLab 15.11.
+- Entity type `Gitlab::Audit::InstanceScope` for instance audit events [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418185) in GitLab 16.2.
+
+{{< /history >}}
```plaintext
GET /audit_events
@@ -168,7 +182,11 @@ Example response:
## Group audit events
-> - Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2.
+{{< history >}}
+
+- Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2.
+
+{{< /history >}}
Use this API to retrieve group audit events.
@@ -182,7 +200,11 @@ pagination is recommended when requesting consecutive pages of results.
### Retrieve all group audit events
-> - Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2.
+{{< history >}}
+
+- Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2.
+
+{{< /history >}}
```plaintext
GET /groups/:id/audit_events
@@ -292,7 +314,11 @@ A user with a Developer role is limited to project audit events based on their i
### Retrieve all project audit events
-> - Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367528) in GitLab 15.10.
+{{< history >}}
+
+- Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367528) in GitLab 15.10.
+
+{{< /history >}}
```plaintext
GET /projects/:id/audit_events
diff --git a/doc/api/avatar.md b/doc/api/avatar.md
index db0a72bcdf499d166d11a51b5e711a08b69483e4..4d5e97d70fbeadbc706d37524a743bc9258691c2 100644
--- a/doc/api/avatar.md
+++ b/doc/api/avatar.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Avatar API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with user avatars.
diff --git a/doc/api/boards.md b/doc/api/boards.md
index aaea90b266703680fcf301e57390ab510ec6129a..95aa1d807a8ae953cb0ed1a893ccd3b98ca39cfa 100644
--- a/doc/api/boards.md
+++ b/doc/api/boards.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project issue boards API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every API call to [issue boards](../user/project/issue_board.md) must be authenticated.
@@ -425,12 +428,15 @@ POST /projects/:id/boards/:board_id/lists
| `assignee_id` | integer | no | The ID of a user. Premium and Ultimate only. |
| `milestone_id` | integer | no | The ID of a milestone. Premium and Ultimate only. |
-NOTE:
+{{< alert type="note" >}}
+
Label, assignee and milestone arguments are mutually exclusive,
that is, only one of them are accepted in a request.
Check the [issue board documentation](../user/project/issue_board.md)
for more information regarding the required license for each list type.
+{{< /alert >}}
+
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards/1/lists?label_id=5"
```
diff --git a/doc/api/branches.md b/doc/api/branches.md
index 142feb4e87e3ec23a1635da75a0bbb6cb2a021d8..3971822b578f89ac197954afeed78e515837d6d0 100644
--- a/doc/api/branches.md
+++ b/doc/api/branches.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Documentation for the REST API for Git branches in GitLab."
+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
+description: Documentation for the REST API for Git branches in GitLab.
title: Branches API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This API operates on [repository branches](../user/project/repository/branches/_index.md).
@@ -18,9 +21,12 @@ See also [Protected branches API](protected_branches.md).
Get a list of repository branches from a project, sorted by name alphabetically.
-NOTE:
+{{< alert type="note" >}}
+
This endpoint can be accessed without authentication if the repository is publicly accessible.
+{{< /alert >}}
+
```plaintext
GET /projects/:id/repository/branches
```
@@ -81,9 +87,12 @@ Example response:
Get a single project repository branch.
-NOTE:
+{{< alert type="note" >}}
+
This endpoint can be accessed without authentication if the repository is publicly accessible.
+{{< /alert >}}
+
```plaintext
GET /projects/:id/repository/branches/:branch
```
@@ -206,9 +215,12 @@ Example response:
Delete a branch from the repository.
-NOTE:
+{{< alert type="note" >}}
+
In the case of an error, an explanation message is provided.
+{{< /alert >}}
+
```plaintext
DELETE /projects/:id/repository/branches/:branch
```
@@ -228,18 +240,24 @@ curl --request DELETE \
--url "https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch"
```
-NOTE:
+{{< alert type="note" >}}
+
Deleting a branch does not completely erase all related data.
Some information persists to maintain project history and to support recovery processes.
For more information, see [Handle sensitive information](../topics/git/undo.md#handle-sensitive-information).
+{{< /alert >}}
+
## Delete merged branches
Deletes all branches that are merged into the project's default branch.
-NOTE:
+{{< alert type="note" >}}
+
[Protected branches](../user/project/repository/branches/protected.md) are not deleted as part of this operation.
+{{< /alert >}}
+
```plaintext
DELETE /projects/:id/repository/merged_branches
```
diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md
index 30afbb54c629be298e07b4535d9102033e70f9fb..05b592beddac11a55398f5e94ded307e67375855 100644
--- a/doc/api/broadcast_messages.md
+++ b/doc/api/broadcast_messages.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Broadcast Messages API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - `target_access_levels` [introduced](https://gitlab.com/gitlab-org/growth/team-tasks/-/issues/461) in GitLab 14.8 [with a flag](../administration/feature_flags.md) named `role_targeted_broadcast_messages`. Disabled by default.
-> - `color` parameter [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95829) in GitLab 15.6.
-> - `theme` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/498900) in GitLab 17.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- `target_access_levels` [introduced](https://gitlab.com/gitlab-org/growth/team-tasks/-/issues/461) in GitLab 14.8 [with a flag](../administration/feature_flags.md) named `role_targeted_broadcast_messages`. Disabled by default.
+- `color` parameter [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95829) in GitLab 15.6.
+- `theme` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/498900) in GitLab 17.6.
+
+{{< /history >}}
Broadcast messages API operates on [broadcast messages](../administration/broadcast_messages.md).
@@ -22,9 +29,12 @@ GET requests do not require authentication. All other broadcast message API endp
## Get all broadcast messages
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
List all broadcast messages.
@@ -60,9 +70,12 @@ Example response:
## Get a specific broadcast message
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Get a specific broadcast message.
diff --git a/doc/api/bulk_imports.md b/doc/api/bulk_imports.md
index 4a45830e6b822a09228eb8d20790c1bc88d379fc..d2754bbf94352eb77f70b28320af83e23705ca0d 100644
--- a/doc/api/bulk_imports.md
+++ b/doc/api/bulk_imports.md
@@ -5,19 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group and project migration by direct transfer API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Project migration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390515) in GitLab 15.11.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Project migration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390515) in GitLab 15.11.
+
+{{< /history >}}
With the group migration by direct transfer API, you can start and view the progress of migrations initiated with
[group migration by direct transfer](../user/group/import/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
Migrating projects with this API is in [beta](../policy/development_stages_support.md#beta). This feature is not
ready for production use.
+{{< /alert >}}
+
## Prerequisites
For information on prerequisites for group migration by direct transfer API, see
@@ -25,7 +35,11 @@ prerequisites for [migrating groups by direct transfer](../user/group/import/dir
## Start a new group or project migration
-> - `project_entity` source type [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390515) in GitLab 15.11.
+{{< history >}}
+
+- `project_entity` source type [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390515) in GitLab 15.11.
+
+{{< /history >}}
Use this endpoint to start a new group or project migration. Specify:
@@ -384,7 +398,11 @@ curl --request GET \
## Get list of failed import records for group or project migration entity
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428016) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428016) in GitLab 16.6.
+
+{{< /history >}}
```plaintext
GET /bulk_imports/:id/entities/:entity_id/failures
@@ -409,7 +427,11 @@ curl --request GET \
## Cancel a migration
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438281) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438281) in GitLab 17.1.
+
+{{< /history >}}
Cancel a direct transfer migration.
diff --git a/doc/api/chat.md b/doc/api/chat.md
index 28bb119c23c9b901e0a61dece922ba0adead42bf..b1b22cfd61dc78763b9ed9269567218e09a6f171 100644
--- a/doc/api/chat.md
+++ b/doc/api/chat.md
@@ -2,7 +2,7 @@
stage: AI-Powered
group: Duo Chat
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
-description: "Documentation for the REST API for Duo Chat."
+description: Documentation for the REST API for Duo Chat.
title: GitLab Duo Chat Completions API
---
@@ -10,17 +10,24 @@ The GitLab Duo Chat Completions API generates Chat responses. This API is for in
## Generate Chat responses
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133015) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `access_rest_chat`. Disabled by default. This feature is internal-only.
-> - [Added additional_context parameter](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162650) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `duo_additional_context`. Disabled by default. This feature is internal-only.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133015) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `access_rest_chat`. Disabled by default. This feature is internal-only.
+- [Added additional_context parameter](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162650) in GitLab 17.4 [with a flag](../administration/feature_flags.md) named `duo_additional_context`. Disabled by default. This feature is internal-only.
+
+{{< /history >}}
```plaintext
POST /chat/completions
```
-NOTE:
+{{< alert type="note" >}}
+
Requests to this endpoint are proxied to the
[AI gateway](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/docs/api.md).
+{{< /alert >}}
+
Supported attributes:
| Attribute | Type | Required | Description |
diff --git a/doc/api/cluster_agents.md b/doc/api/cluster_agents.md
index f3a7c9208abd29cf3b3c42b993c0d72ec8afdbdd..c7f1925a6934335cac88461c9d8aab0f4e65fade 100644
--- a/doc/api/cluster_agents.md
+++ b/doc/api/cluster_agents.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Agents API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Agent Tokens API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Agent Tokens API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
+
+{{< /history >}}
Use the Agents API to work with the GitLab agent for Kubernetes.
@@ -242,7 +249,11 @@ curl --request DELETE --header "Private-Token: <your_access_token>" "https://git
## List tokens for an agent
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
+
+{{< /history >}}
Returns a list of active tokens for an agent.
@@ -304,12 +315,19 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
The `last_used_at` field for a token is only returned when getting a single agent token.
+{{< /alert >}}
+
## Get a single agent token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
+
+{{< /history >}}
Gets a single agent token.
@@ -367,9 +385,13 @@ Example response:
## Create an agent token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
-> - Two-token limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361030/) in GitLab 16.1 with a [flag](../administration/feature_flags.md) named `cluster_agents_limit_tokens_created`.
-> - Two-token limit [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/412399) in GitLab 16.2. Feature flag `cluster_agents_limit_tokens_created` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
+- Two-token limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361030/) in GitLab 16.1 with a [flag](../administration/feature_flags.md) named `cluster_agents_limit_tokens_created`.
+- Two-token limit [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/412399) in GitLab 16.2. Feature flag `cluster_agents_limit_tokens_created` removed.
+
+{{< /history >}}
Creates a new token for an agent.
@@ -406,9 +428,12 @@ The response is the new token with the following fields:
| `last_used_at` | string or null | ISO8601 datetime when the token was last used. |
| `token` | string | The secret token value. |
-NOTE:
+{{< alert type="note" >}}
+
The `token` is only returned in the response of the `POST` endpoint and cannot be retrieved afterwards.
+{{< /alert >}}
+
Example request:
```shell
@@ -435,7 +460,11 @@ Example response:
## Revoke an agent token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347046) in GitLab 15.0.
+
+{{< /history >}}
Revokes an agent token.
@@ -461,11 +490,18 @@ curl --request DELETE --header "Private-Token: <your_access_token>" "https://git
## Receptive agents
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12180) in GitLab 17.4.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12180) in GitLab 17.4.
+{{< /history >}}
[Receptive agents](../user/clusters/agent/_index.md#receptive-agents) allow GitLab to integrate with Kubernetes clusters
that cannot establish a network connection to the GitLab instance, but can be connected to by GitLab.
@@ -520,9 +556,12 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
Either `public_key` or `client_cert` is set, but never both.
+{{< /alert >}}
+
### Get a single agent URL configuration
Gets a single agent URL configuration.
@@ -572,9 +611,12 @@ Example response:
}
```
-NOTE:
+{{< alert type="note" >}}
+
Either `public_key` or `client_cert` is set, but never both.
+{{< /alert >}}
+
### Create an agent URL configuration
Creates a new URL configuration for an agent.
@@ -651,9 +693,12 @@ Example response for mTLS:
}
```
-NOTE:
+{{< alert type="note" >}}
+
If the `client_cert` and `client_key` are not provided, a private-public key pair is generated and JWT authentication is used instead of mTLS.
+{{< /alert >}}
+
### Delete an agent URL configuration
Deletes an agent URL configuration.
diff --git a/doc/api/cluster_discovery.md b/doc/api/cluster_discovery.md
index 430eec27ec94c6fec62baba9b8c01ecfa7427d3c..92dfbf5d8c67dfbe3f9ec39de54afbd7408d34e0 100644
--- a/doc/api/cluster_discovery.md
+++ b/doc/api/cluster_discovery.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Cluster discovery API (certificate-based) (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< /alert >}}
+
## Discover certificate-based clusters
Gets certificate-based clusters that are registered to a group, subgroup, or project. Disabled and enabled clusters are also returned.
diff --git a/doc/api/code_suggestions.md b/doc/api/code_suggestions.md
index 48f999262cff28a00a9d580da17fe2c3af292df6..aec7f23364286f0e7568aac75102ff8536a56c4e 100644
--- a/doc/api/code_suggestions.md
+++ b/doc/api/code_suggestions.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Creation
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
-description: "Documentation for the REST API for Code Suggestions."
+description: Documentation for the REST API for Code Suggestions.
title: Code Suggestions API
---
@@ -10,26 +10,39 @@ Use the Code Suggestions API to access the Code Suggestions feature.
## Generate code completions
-DETAILS:
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415581) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `code_suggestions_completion_api`. Disabled by default. This feature is an experiment.
-> - Requirement to generate a JWT before calling this endpoint was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127863) in GitLab 16.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/416371) in GitLab 16.8. [Feature flag `code_suggestions_completion_api`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138174) removed.
-> - `context` and `user_instruction` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462750) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `code_suggestions_context`. Disabled by default.
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415581) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `code_suggestions_completion_api`. Disabled by default. This feature is an experiment.
+- Requirement to generate a JWT before calling this endpoint was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127863) in GitLab 16.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/416371) in GitLab 16.8. [Feature flag `code_suggestions_completion_api`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138174) removed.
+- `context` and `user_instruction` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462750) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `code_suggestions_context`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the `context` and `user_instruction` attributes is controlled by a feature flag.
For more information, see the history.
These attributes are available for testing, but are not ready for production use.
+{{< /alert >}}
+
```plaintext
POST /code_suggestions/completions
```
-NOTE:
+{{< alert type="note" >}}
+
This endpoint rate-limits each user to 60 requests per 1-minute window.
+{{< /alert >}}
+
Use the AI abstraction layer to generate code completions.
Requests to this endpoint are proxied to the
@@ -102,7 +115,11 @@ Example response:
## Validate that Code Suggestions is enabled
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138814) in GitLab 16.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138814) in GitLab 16.7.
+
+{{< /history >}}
Use this endpoint to validate if either:
@@ -141,16 +158,23 @@ curl --request POST \
## Fetch direct connection information
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/452044) in GitLab 17.0 [with a flag](../administration/feature_flags.md) named `code_suggestions_direct_completions`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/456443) in GitLab 17.2. Feature flag `code_suggestions_direct_completions` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/452044) in GitLab 17.0 [with a flag](../administration/feature_flags.md) named `code_suggestions_direct_completions`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/456443) in GitLab 17.2. Feature flag `code_suggestions_direct_completions` removed.
+
+{{< /history >}}
```plaintext
POST /code_suggestions/direct_access
```
-NOTE:
+{{< alert type="note" >}}
+
This endpoint rate-limits each user to 10 requests per 5-minute window.
+{{< /alert >}}
+
Returns user-specific connection details which can be used by IDEs/clients to send completion requests directly to AI gateway.
Example request:
diff --git a/doc/api/commits.md b/doc/api/commits.md
index 3973bbe8f9527989062ffb77f287a6fe9a30ac71..6b2e0ff5f450d700388617d246fab52517d27d72 100644
--- a/doc/api/commits.md
+++ b/doc/api/commits.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Documentation for the REST API for Git commits in GitLab."
+description: Documentation for the REST API for Git commits in GitLab.
title: Commits API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository). Read more about [GitLab-specific information](../user/project/repository/_index.md#commit-changes-to-a-repository) for commits.
@@ -24,7 +27,11 @@ information:
## List repository commits
-> - Commits by author [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114417) in GitLab 15.10.
+{{< history >}}
+
+- Commits by author [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114417) in GitLab 15.10.
+
+{{< /history >}}
Get a list of repository commits in a project.
@@ -313,7 +320,11 @@ Example response:
## Get the sequence of a commit
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438151) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438151) in GitLab 16.9.
+
+{{< /history >}}
Get the sequence number of a commit in a project by following the parent links from the given commit.
diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md
index 3399a1e5d73edf7759f1bccc4603f3079a19ae69..13e100529fd76a18d56711fcfd3a1b9674ff1745 100644
--- a/doc/api/container_registry.md
+++ b/doc/api/container_registry.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Container registry API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use these API endpoints to work with the [GitLab container registry](../user/packages/container_registry/_index.md).
@@ -116,7 +119,11 @@ Example response:
### Within a group
-> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336912) the `tags` and `tag_count` attributes in GitLab 15.0.
+{{< history >}}
+
+- [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336912) the `tags` and `tag_count` attributes in GitLab 15.0.
+
+{{< /history >}}
Get a list of registry repositories in a group.
@@ -226,13 +233,20 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
### Within a project
-> - Keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432470) in GitLab 16.10 for GitLab.com only.
+{{< history >}}
+
+- Keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432470) in GitLab 16.10 for GitLab.com only.
+
+{{< /history >}}
Get a list of tags for given registry repository.
-NOTE:
+{{< alert type="note" >}}
+
Offset pagination is deprecated and keyset pagination is now the preferred pagination method.
+{{< /alert >}}
+
```plaintext
GET /projects/:id/registry/repositories/:repository_id/tags
```
@@ -360,13 +374,16 @@ You can run this at most once an hour for a given container repository. This
action doesn't delete blobs. To delete them and recycle disk space,
[run the garbage collection](../administration/packages/container_registry.md#container-registry-garbage-collection).
-WARNING:
+{{< alert type="warning" >}}
+
The number of tags deleted by this API is limited on GitLab.com
because of the scale of the container registry there.
If your container registry has a large number of tags to delete,
only some of them are deleted, and you might need to call this API multiple times.
To schedule tags for automatic deletion, use a [cleanup policy](../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy) instead.
+{{< /alert >}}
+
Examples:
- Remove tag names that are matching the regex (Git SHA), keep always at least 5,
@@ -416,9 +433,12 @@ the container registry has its own endpoints.
To query those, follow the Registry's built-in mechanism to obtain and use an
[authentication token](https://distribution.github.io/distribution/spec/auth/token/).
-NOTE:
+{{< alert type="note" >}}
+
These are different from project or personal access tokens in the GitLab application.
+{{< /alert >}}
+
### Obtain token from GitLab
```plaintext
@@ -437,7 +457,11 @@ $ curl --request GET --user "${CI_REGISTRY_USER}:${CI_REGISTRY_PASSWORD}" \
### Delete image tags by reference
-> - Endpoint `v2/<name>/manifests/<tag>` [introduced](https://gitlab.com/gitlab-org/container-registry/-/issues/1091) and endpoint `v2/<name>/tags/reference/<tag>` [deprecated](https://gitlab.com/gitlab-org/container-registry/-/issues/1094) in GitLab 16.4.
+{{< history >}}
+
+- Endpoint `v2/<name>/manifests/<tag>` [introduced](https://gitlab.com/gitlab-org/container-registry/-/issues/1091) and endpoint `v2/<name>/tags/reference/<tag>` [deprecated](https://gitlab.com/gitlab-org/container-registry/-/issues/1094) in GitLab 16.4.
+
+{{< /history >}}
```plaintext
DELETE http(s)://${CI_REGISTRY}/v2/${CI_REGISTRY_IMAGE}/tags/reference/${CI_COMMIT_SHORT_SHA}
diff --git a/doc/api/container_repository_protection_rules.md b/doc/api/container_repository_protection_rules.md
index f26f914b36e1495d3ad9c561e9b068191d534abe..809f81829ddefe99019a2ec150241bd2e24304bb 100644
--- a/doc/api/container_repository_protection_rules.md
+++ b/doc/api/container_repository_protection_rules.md
@@ -1,18 +1,25 @@
---
stage: Package
group: Container Registry
-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"
-description: "Documentation for the REST API for container repository protection rules in GitLab."
+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
+description: Documentation for the REST API for container repository protection rules in GitLab.
title: Container repository protection rules API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155798) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `container_registry_protected_containers`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/429074) in GitLab 17.8.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/480385) in GitLab 17.8. Feature flag `container_registry_protected_containers` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155798) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `container_registry_protected_containers`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/429074) in GitLab 17.8.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/480385) in GitLab 17.8. Feature flag `container_registry_protected_containers` removed.
+
+{{< /history >}}
## List container repository protection rules
@@ -67,7 +74,11 @@ Example response:
## Create a container repository protection rule
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/457518) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/457518) in GitLab 17.2.
+
+{{< /history >}}
Create a container repository protection rule for a project's container registry.
@@ -111,7 +122,11 @@ curl --request POST \
## Update a container repository protection rule
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/457518) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/457518) in GitLab 17.2.
+
+{{< /history >}}
Update a container repository protection rule for a project's container registry.
@@ -154,7 +169,11 @@ curl --request PATCH \
## Delete a container repository protection rule
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/457518) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/457518) in GitLab 17.4.
+
+{{< /history >}}
Deletes a container repository protection rule from a project's container registry.
diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md
index c8f88449921ed5e1d3036b496212bb9e0449205c..20f8395e8c39485ae1f3a6fd9b394acf9ea2a953 100644
--- a/doc/api/custom_attributes.md
+++ b/doc/api/custom_attributes.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Custom Attributes API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every API call to custom attributes must be authenticated as administrator.
diff --git a/doc/api/database_migrations.md b/doc/api/database_migrations.md
index 1fea960ee2057f9150fd384a9c685f3d5a9a0f88..df98a894caea6dec0acc261cf389cec198c2196e 100644
--- a/doc/api/database_migrations.md
+++ b/doc/api/database_migrations.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Database migrations API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123408) in GitLab 16.2.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123408) in GitLab 16.2.
+
+{{< /history >}}
This API is for managing database migrations used in the development of GitLab.
diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md
index bba93db4fada14a87b445d0757c430845cdbb0bb..f0cf6fc97afd2e6f8de6f1a6bfa1095297830175 100644
--- a/doc/api/dependencies.md
+++ b/doc/api/dependencies.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dependencies API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every call to this endpoint requires authentication. To perform this call, user should be authorized to read repository.
To see vulnerabilities in response, user should be authorized to read
diff --git a/doc/api/dependency_list_export.md b/doc/api/dependency_list_export.md
index 25efcd88a25917f6a0c16bc4e2a4ac0a740a5546..76db72ca0cf80ff0741883c98eea37cbc55ac893 100644
--- a/doc/api/dependency_list_export.md
+++ b/doc/api/dependency_list_export.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dependency list export API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every call to this endpoint requires authentication.
## Create a pipeline-level dependency list export
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333463) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `merge_sbom_api`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/425312) in GitLab 16.7. Feature flag `merge_sbom_api` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333463) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `merge_sbom_api`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/425312) in GitLab 16.7. Feature flag `merge_sbom_api` removed.
+
+{{< /history >}}
Create a new CycloneDX JSON export for all the project dependencies detected in a pipeline.
diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md
index a8a0d898645244a9c344af2478c565145b29d49b..057c3a1fe4bdb41c279de8f26950be2ccb107258 100644
--- a/doc/api/dependency_proxy.md
+++ b/doc/api/dependency_proxy.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dependency Proxy API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Purge the dependency proxy for a group
diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md
index 1e2fcb9ef4bf5745a5b1f84c4aea6449ea661d37..afbb9a339661625598d2278f9811d72f45b0259b 100644
--- a/doc/api/deploy_keys.md
+++ b/doc/api/deploy_keys.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deploy keys API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The deploy keys API can return in responses fingerprints of the public key in the following fields:
@@ -16,9 +19,12 @@ The deploy keys API can return in responses fingerprints of the public key in th
## List all deploy keys
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> `projects_with_readonly_access` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119147) in GitLab 16.0.
@@ -101,11 +107,18 @@ Example response:
## Add deploy key
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/478476) in GitLab 17.5.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/478476) in GitLab 17.5.
+
+{{< /history >}}
Create a deploy key for the GitLab instance. This endpoint requires administrator
access.
@@ -190,7 +203,11 @@ Example response:
## List project deploy keys for user
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88917) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88917) in GitLab 15.1.
+
+{{< /history >}}
Get a list of a specified user (requestee) and the authenticated user's (requester) common [project deploy keys](../user/project/deploy_keys/_index.md#scope). It lists only the **enabled project keys from the common projects of requester and requestee**.
diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md
index 98b64a3b0588c567e3fbcfbec82496ef3c504e29..f4eba47bbf824080e77530ffe32a42821b0663a4 100644
--- a/doc/api/deploy_tokens.md
+++ b/doc/api/deploy_tokens.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deploy Tokens API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## List all deploy tokens
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Get a list of all deploy tokens across the GitLab instance. This endpoint requires administrator access.
diff --git a/doc/api/deployments.md b/doc/api/deployments.md
index cb8d4c7fd8e466b505d0e225ecee39517afc1740..600674e6e29c580c7176c7c239b890eaba4dfa65 100644
--- a/doc/api/deployments.md
+++ b/doc/api/deployments.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deployments API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> Support for [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) authentication [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414549) in GitLab 16.2.
@@ -35,9 +38,12 @@ GET /projects/:id/deployments
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments"
```
-NOTE:
+{{< alert type="note" >}}
+
When using `finished_before` or `finished_after`, you should specify the `order_by` to be `finished_at` and `status` should be `success`.
+{{< /alert >}}
+
Example response:
```json
@@ -488,11 +494,14 @@ Example responses:
## List of merge requests associated with a deployment
-NOTE:
+{{< alert type="note" >}}
+
Not all deployments can be associated with merge requests. See
[Track what merge requests were deployed to an environment](../ci/environments/deployments.md#track-newly-included-merge-requests-per-deployment)
for more information.
+{{< /alert >}}
+
This API retrieves the list of merge requests shipped with a given deployment:
```plaintext
@@ -507,12 +516,19 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
## Approve or reject a blocked deployment
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `deployment_approvals`. Disabled by default.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/347342) in GitLab 14.8.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `deployment_approvals`. Disabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/347342) in GitLab 14.8.
+{{< /history >}}
See [Deployment Approvals](../ci/environments/deployment_approvals.md) for more information about this feature.
diff --git a/doc/api/discussions.md b/doc/api/discussions.md
index bfec71919103794edeb1a60633e3f4db5e75a4ee..93bc092754bb024e2d0bdd155036efa48ea55173 100644
--- a/doc/api/discussions.md
+++ b/doc/api/discussions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Discussions API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Discussions are attached to:
@@ -191,9 +194,12 @@ curl --request POST \
Adds a new note to the thread. This can also [create a thread from a single comment](../user/discussions/_index.md#create-a-thread-by-replying-to-a-standard-comment).
-WARNING:
+{{< alert type="warning" >}}
+
Notes can be added to other items than comments, such as system notes, making them threads.
+{{< /alert >}}
+
```plaintext
POST /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes
```
@@ -484,17 +490,23 @@ curl --request DELETE \
## Epics
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0
and is planned for removal in v5 of the API.
In GitLab 17.4 or later, if your administrator [enabled the new look for epics](../user/group/epics/epic_work_items.md), use the
[Work Items API](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/) instead. For more information, see the [guide how to migrate your existing APIs](graphql/epic_work_items_api_migration_guide.md).
This change is a breaking change.
+{{< /alert >}}
+
### List group epic discussion items
Gets a list of all discussion items for a single epic.
diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md
index e06f7d8edd00c1b1f643ae88d4fb3c3171a1e740..d372523f230703219e164b168a8fc43137ea3238 100644
--- a/doc/api/dora/metrics.md
+++ b/doc/api/dora/metrics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: DevOps Research and Assessment (DORA) key metrics API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can also retrieve [DORA metrics](../../user/analytics/dora_metrics.md) with the [GraphQL API](../graphql/reference/_index.md).
@@ -102,5 +105,8 @@ parameter:
| `lead_time_for_changes` | The median number of seconds between the merge of the merge request (MR) and the deployment of the MR commits for all MRs deployed during the time period. |
| `time_to_restore_service` | The median number of seconds an incident was open during the time period. Available only for production environment. |
-NOTE:
+{{< alert type="note" >}}
+
The API returns the `monthly` and `all` intervals by calculating the median of the daily median values. This can introduce a slight inaccuracy in the returned data.
+
+{{< /alert >}}
diff --git a/doc/api/draft_notes.md b/doc/api/draft_notes.md
index e2be69928493e19187ec87c845c4f42eb3cc057a..4989f9d404ce6d5479f0bc0eb81e08cc895da6d6 100644
--- a/doc/api/draft_notes.md
+++ b/doc/api/draft_notes.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Documentation for the REST API for draft notes (unpublished comments) in GitLab."
+description: Documentation for the REST API for draft notes (unpublished comments) in GitLab.
title: Draft Notes API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Draft notes are pending, unpublished comments on merge requests. They can either:
diff --git a/doc/api/emoji_reactions.md b/doc/api/emoji_reactions.md
index 8d42770600775d59d6d627da7990631750e7e6e4..52d43d2616ecf8aeb8f3b33fea4679dbc59ee08d 100644
--- a/doc/api/emoji_reactions.md
+++ b/doc/api/emoji_reactions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Emoji reactions API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from "award emoji" to "emoji reactions" in GitLab 16.0.
@@ -27,7 +30,11 @@ For information on using these endpoints with comments, see [Add reactions to co
### List an awardable's emoji reactions
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public awardables.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public awardables.
+
+{{< /history >}}
Get a list of all emoji reactions for a specified awardable. This endpoint can
be accessed without authentication if the awardable is publicly accessible.
@@ -92,7 +99,11 @@ Example response:
### Get single emoji reaction
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public awardables.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public awardables.
+
+{{< /history >}}
Get a single emoji reaction from an issue, snippet, or merge request. This endpoint can
be accessed without authentication if the awardable is publicly accessible.
@@ -209,14 +220,21 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git
Comments (also known as notes) are a sub-resource of issues, merge requests, and snippets.
-NOTE:
+{{< alert type="note" >}}
+
The examples below describe working with emoji reactions on an issue's comments, but can be
adapted to comments on merge requests and snippets. Therefore, you have to replace
`issue_iid` either with `merge_request_iid` or with the `snippet_id`.
+{{< /alert >}}
+
### List a comment's emoji reactions
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public comments.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public comments.
+
+{{< /history >}}
Get all emoji reactions for a comment (note). This endpoint can
be accessed without authentication if the comment is publicly accessible.
@@ -264,7 +282,11 @@ Example response:
### Get an emoji reaction for a comment
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public comments.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public comments.
+
+{{< /history >}}
Get a single emoji reaction for a comment (note). This endpoint can
be accessed without authentication if the comment is publicly accessible.
diff --git a/doc/api/environments.md b/doc/api/environments.md
index 885789eab5c1f79fdf94c8467263def6b421a34a..9e13b658eed12aba39f2d7cb3ff9f6a343adcdfc 100644
--- a/doc/api/environments.md
+++ b/doc/api/environments.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Environments API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> Parameter `auto_stop_setting` [added](https://gitlab.com/gitlab-org/gitlab/-/issues/428625) in GitLab 17.8.
> Support for [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) authentication [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414549) in GitLab 16.2.
@@ -241,7 +244,11 @@ Example response:
## Update an existing environment
-> - Parameter `name` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) in GitLab 16.0.
+{{< history >}}
+
+- Parameter `name` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) in GitLab 16.0.
+
+{{< /history >}}
Updates an existing environment's name and/or `external_url`.
diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md
index 9b941b709927504a6f86b6fbd3bbd510c69abe27..80f55e0efa18db04af645cfc9bff3003d6199a13 100644
--- a/doc/api/epic_issues.md
+++ b/doc/api/epic_issues.md
@@ -5,17 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Epic Issues API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0
and is planned for removal in v5 of the API.
In GitLab 17.4 or later, if your administrator [enabled the new look for epics](../user/group/epics/epic_work_items.md), use the
[Work Items API](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/) instead. For more information, see the [guide how to migrate your existing APIs](graphql/epic_work_items_api_migration_guide.md).
This change is a breaking change.
+{{< /alert >}}
+
Every API call to the epic issues API endpoint must be authenticated.
If a user is not a member of a group and the group is private, a `GET` request on that group
diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md
index b84aa5dc395b5865c540e6a88f5e641939798597..914122b5ad60b2778bf204b865ad7a310d0d6b92 100644
--- a/doc/api/epic_links.md
+++ b/doc/api/epic_links.md
@@ -5,17 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Epic Links API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0
and is planned for removal in v5 of the API.
In GitLab 17.4 or later, if your administrator [enabled the new look for epics](../user/group/epics/epic_work_items.md), use the
[Work Items API](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/) instead. For more information, see the [guide how to migrate your existing APIs](graphql/epic_work_items_api_migration_guide.md).
This change is a breaking change.
+{{< /alert >}}
+
Manages parent-child [epic relationships](../user/group/epics/manage_epics.md#multi-level-child-epics).
Every API call to `epic_links` must be authenticated.
diff --git a/doc/api/epics.md b/doc/api/epics.md
index 3eda5e76a645e440138a5bbc3a54c3eff3c2ee74..7cac0f4a421106be483b00199c0c2ea6443d869d 100644
--- a/doc/api/epics.md
+++ b/doc/api/epics.md
@@ -5,17 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Epics API (deprecated)
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0
and is planned for removal in v5 of the API.
In GitLab 17.4 or later, if your administrator [enabled the new look for epics](../user/group/epics/epic_work_items.md), use the
[Work Items API](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/) instead. For more information, see the [guide how to migrate your existing APIs](graphql/epic_work_items_api_migration_guide.md).
This change is a breaking change.
+{{< /alert >}}
+
Every API call to epic must be authenticated.
If a user is not a member of a private group, a `GET` request on that group results in a `404` status code.
@@ -44,15 +50,21 @@ are paginated.
Read more on [pagination](rest/_index.md#pagination).
-WARNING:
+{{< alert type="warning" >}}
+
In [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) and later,
the `reference` attribute in responses is deprecated in favor of `references`.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
`references.relative` is relative to the group that the epic is being requested from. When an epic
is fetched from its origin group, the `relative` format is the same as the `short` format.
When an epic is requested across groups, the `relative` format is expected to be the same as the `full` format.
+{{< /alert >}}
+
## List epics for a group
Gets all epics of the requested group and its subgroups.
@@ -274,11 +286,14 @@ Example response:
Creates a new epic.
-NOTE:
+{{< alert type="note" >}}
+
Starting with GitLab [11.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6448), `start_date` and `end_date` should no longer be assigned
directly, as they now represent composite values. You can configure it via the `*_is_fixed` and
`*_fixed` fields instead.
+{{< /alert >}}
+
```plaintext
POST /groups/:id/epics
```
diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md
index 622e08c3d7774a0092a2e5ad363acf370a3ee25d..e55458b4bf6e19f5a1a951af33d7bdbfdf9f4c80 100644
--- a/doc/api/error_tracking.md
+++ b/doc/api/error_tracking.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Error Tracking settings API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Error Tracking project settings
@@ -43,14 +46,21 @@ Example response:
### Create Error Tracking settings
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393035/) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393035/) in GitLab 15.10.
+
+{{< /history >}}
The API allows you to create Error Tracking settings for a project. Only for users with Maintainer role for
the project.
-NOTE:
+{{< alert type="note" >}}
+
This API is only available when used with [integrated error tracking](../operations/integrated_error_tracking.md).
+{{< /alert >}}
+
```plaintext
PUT /projects/:id/error_tracking/settings
```
diff --git a/doc/api/events.md b/doc/api/events.md
index c892d643be22c33d8111ffbe5477c59dd2de5f52..44ca13f5714279264b687efc7931af52fd84be6b 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Events API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Filter parameters
@@ -18,7 +21,11 @@ These options are in lowercase.
### Target types
-> - Support for epics [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13056) in GitLab 17.3. Your administrator must have [enabled the new look for epics](../user/group/epics/epic_work_items.md).
+{{< history >}}
+
+- Support for epics [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13056) in GitLab 17.3. Your administrator must have [enabled the new look for epics](../user/group/epics/epic_work_items.md).
+
+{{< /history >}}
Available target types for the `target_type` parameter are:
@@ -280,9 +287,12 @@ Example response:
## List a Project's visible events
-NOTE:
+{{< alert type="note" >}}
+
This endpoint has been around longer than the others. Documentation was formerly located in the [Projects API pages](projects.md).
+{{< /alert >}}
+
Get a list of visible events for a particular project.
```plaintext
diff --git a/doc/api/experiments.md b/doc/api/experiments.md
index 6f829c127cb1655b6305e3a1a56f8d574287cd53..a244ae9d06b594e0f89b9c5e799e9b4a54535685 100644
--- a/doc/api/experiments.md
+++ b/doc/api/experiments.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Experiments API (GitLab team only)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
This API is for listing A/B experiments [defined in GitLab](../development/experiment_guide/_index.md).
diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md
index 036f23dbd2ceaa281624e8af06a2ca4b208e734d..65a5ed74e8e70d4378d119e553e5b57dbf4225be 100644
--- a/doc/api/feature_flag_user_lists.md
+++ b/doc/api/feature_flag_user_lists.md
@@ -5,21 +5,31 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Feature flag user lists API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205409) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205409) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5.
+
+{{< /history >}}
API for accessing GitLab feature flag user lists.
Users with at least the Developer [role](../user/permissions.md) can access the feature flag user lists API.
-NOTE:
+{{< alert type="note" >}}
+
`GET` requests return twenty results at a time because the API results
are [paginated](rest/_index.md#pagination). You can change this value.
+{{< /alert >}}
+
## List all feature flag user lists for a project
Gets all feature flag user lists for the requested project.
diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md
index 2099c09857352ce32d9b4cb1fbf13c8945f43309..8a46a193b90da38189ca0ce162f0a722a48e57d4 100644
--- a/doc/api/feature_flags.md
+++ b/doc/api/feature_flags.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Feature flags API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in GitLab Premium 12.5.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in GitLab Premium 12.5.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5.
+
+{{< /history >}}
API for accessing resources of [GitLab feature flags](../operations/feature_flags.md).
diff --git a/doc/api/features.md b/doc/api/features.md
index 50b6817ade4cfa1d5e03e2dd11cc1dc7d6393a76..f742938be00667ab0bc10e56cfbaac1ee6944fb1 100644
--- a/doc/api/features.md
+++ b/doc/api/features.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Feature flags API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This API is for managing Flipper-based [feature flags used in development of GitLab](../development/feature_flags/_index.md).
@@ -110,9 +113,12 @@ Set a feature's gate value. If a feature with the given name doesn't exist yet,
it's created. The value can be a boolean, or an integer to indicate
percentage of time.
-WARNING:
+{{< alert type="warning" >}}
+
Before you enable a feature still in development, you should understand the [security and stability risks](../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
+{{< /alert >}}
+
```plaintext
POST /features/:name
```
diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md
index e5793e067b934aff1993afae7ce059f2ab620140..f2445ce1ed703efa9b7a835336ffea8f63f61d44 100644
--- a/doc/api/freeze_periods.md
+++ b/doc/api/freeze_periods.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Freeze Periods API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use the Freeze Periods API to manipulate GitLab [Freeze Period](../user/project/releases/_index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze) entries.
diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md
index 06353b58c4b0015d85ae3f7df771bb8f947336b0..66d4a3bd6cb0f32dac4930d116f70fbe330d791b 100644
--- a/doc/api/geo_nodes.md
+++ b/doc/api/geo_nodes.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo Nodes API (deprecated)
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Geo Nodes API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369140) in GitLab 16.0
and is planned for removal in v5 of the API. Use the [Geo Sites API](geo_sites.md) instead.
This change is a breaking change.
+{{< /alert >}}
+
To interact with Geo node endpoints, you must authenticate yourself as an
administrator.
@@ -954,5 +960,8 @@ Example response:
}
```
-NOTE:
+{{< alert type="note" >}}
+
The `health_status` parameter can only be in an "Healthy" or "Unhealthy" state, while the `health` parameter can be empty, "Healthy", or contain the actual error message.
+
+{{< /alert >}}
diff --git a/doc/api/geo_sites.md b/doc/api/geo_sites.md
index 7055799c991dd1867c40707d96e20d8a8d8e0c0d..7e4fc37cdc80288937542cc35bac5df5573c5751 100644
--- a/doc/api/geo_sites.md
+++ b/doc/api/geo_sites.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo sites API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369140) in GitLab 16.0.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369140) in GitLab 16.0.
+
+{{< /history >}}
Use the Geo sites API to manage Geo site endpoints.
@@ -968,5 +975,8 @@ Example response:
}
```
-NOTE:
+{{< alert type="note" >}}
+
The `health_status` parameter can only be in an "Healthy" or "Unhealthy" state, while the `health` parameter can be empty, "Healthy", or contain the actual error message.
+
+{{< /alert >}}
diff --git a/doc/api/get_started/get_started_extending.md b/doc/api/get_started/get_started_extending.md
index 0c2a1268be9b92e4af879e9afe10b407ed924ea0..890d30b49febe0fe11ae4a022c280071d89b8ad1 100644
--- a/doc/api/get_started/get_started_extending.md
+++ b/doc/api/get_started/get_started_extending.md
@@ -1,7 +1,7 @@
---
stage: none
group: none
-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"
+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
title: Get started extending GitLab
---
diff --git a/doc/api/google_cloud_integration.md b/doc/api/google_cloud_integration.md
index 175218a6723995e59c505567c9ea757678438f03..81fc91bad9b65434e35725dcd0a9d71c466c1bba 100644
--- a/doc/api/google_cloud_integration.md
+++ b/doc/api/google_cloud_integration.md
@@ -5,23 +5,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Google Cloud integration API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+- Status: Experiment
+
+{{< /details >}}
Use this API to interact with the Google Cloud integration. For more information, see [GitLab and Google Cloud integration](../ci/gitlab_google_cloud_integration/_index.md).
## Project-level Google Cloud integration scripts
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141870) in GitLab 16.10. This feature is an [experiment](../policy/development_stages_support.md).
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141870) in GitLab 16.10. This feature is an [experiment](../policy/development_stages_support.md).
+{{< /history >}}
### Workload identity federation creation script
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141870) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141870) in GitLab 16.10.
+
+{{< /history >}}
Users with at least the Maintainer role for the project can use the following endpoint to
query a shell script that creates and configures the workload identity
@@ -52,7 +66,11 @@ curl --request GET \
### Script to set up a Google Cloud integration
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144787) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144787) in GitLab 16.10.
+
+{{< /history >}}
Users with at least the Maintainer role for the project can use the following endpoint to
query a shell script to set up a Google Cloud integration:
@@ -88,7 +106,11 @@ curl --request GET \
### Script to configure a Google Cloud project for runner provisioning
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145525) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145525) in GitLab 16.10.
+
+{{< /history >}}
Users with at least the Maintainer role for the project can use the following endpoint to
query a shell script to configure a Google Cloud project for runner provisioning and execution:
diff --git a/doc/api/graphql/_index.md b/doc/api/graphql/_index.md
index e957efefa72e4275d530dd86599c14d6f16da714..c251d23656086671c4b43cb6c4400ae0066c7c23 100644
--- a/doc/api/graphql/_index.md
+++ b/doc/api/graphql/_index.md
@@ -1,14 +1,17 @@
---
stage: Foundations
group: Import and Integrate
-description: Programmatic interaction with GitLab.
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
+description: Programmatic interaction with GitLab.
title: GraphQL API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[GraphQL](https://graphql.org/) is a query language for APIs. You can use it to
request the exact data you need, and therefore limit the number of requests you need.
@@ -221,15 +224,22 @@ time without notice.
Fields behind a feature flag and disabled by default do not follow the
deprecation and removal process. These fields can be removed at any time without notice.
-WARNING:
+{{< alert type="warning" >}}
+
GitLab makes all attempts to follow the [deprecation and removal process](#deprecation-and-removal-process).
GitLab might make immediate breaking changes to the GraphQL
API to patch critical security or performance concerns if the deprecation
process would pose significant risk.
+{{< /alert >}}
+
### Verify against the future breaking-change schema
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353642) in GitLab 15.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353642) in GitLab 15.6.
+
+{{< /history >}}
You can make calls against the GraphQL API as if all deprecated items were already removed.
This way, you can verify API calls ahead of a [breaking-change release](#deprecation-and-removal-process)
@@ -359,11 +369,14 @@ GraphQL mutations can be detected as spam. If a mutation is detected as spam and
Only [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) is supported.
- Resubmit the request with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set.
-NOTE:
+{{< alert type="note" >}}
+
The GitLab GraphiQL implementation doesn't permit passing of headers, so we must write
this as a cURL query. `--data-binary` is used to properly handle escaped double quotes
in the JSON-embedded query.
+{{< /alert >}}
+
```shell
export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>"
export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
diff --git a/doc/api/graphql/assign_gitlab_duo_seats.md b/doc/api/graphql/assign_gitlab_duo_seats.md
index 4fa70820c1dd41f874f0fe9ae3f8e484eaf2c7aa..afb19942c8d29bf4f0d7bd11f075f843433d1f3c 100644
--- a/doc/api/graphql/assign_gitlab_duo_seats.md
+++ b/doc/api/graphql/assign_gitlab_duo_seats.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Assign GitLab Duo seats by using GraphQL
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Use the GraphQL API to assign GitLab Duo seats to users.
diff --git a/doc/api/graphql/audit_event_streaming_groups.md b/doc/api/graphql/audit_event_streaming_groups.md
index 87bbf7b46932374de7bbcea1ab1ef058a221add0..b9b13693a59469316f521a73a2cd38010c11ea21 100644
--- a/doc/api/graphql/audit_event_streaming_groups.md
+++ b/doc/api/graphql/audit_event_streaming_groups.md
@@ -5,17 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Audit event streaming GraphQL API for top-level groups
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-
-> - Custom HTTP headers API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361216) in GitLab 15.1 [with a flag](../feature_flags.md) named `streaming_audit_event_headers`. Disabled by default.
-> - Custom HTTP headers API [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/362941) in GitLab 15.2.
-> - Custom HTTP headers API [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366524) in GitLab 15.3. [Feature flag `streaming_audit_event_headers`](https://gitlab.com/gitlab-org/gitlab/-/issues/362941) removed.
-> - User-specified verification token API support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360813) in GitLab 15.4.
-> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2.
-> - User-specified destination name API support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413894) in GitLab 16.2.
-> - API [feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/417708) removed in GitLab 16.4.
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Custom HTTP headers API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361216) in GitLab 15.1 [with a flag](../feature_flags.md) named `streaming_audit_event_headers`. Disabled by default.
+- Custom HTTP headers API [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/362941) in GitLab 15.2.
+- Custom HTTP headers API [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366524) in GitLab 15.3. [Feature flag `streaming_audit_event_headers`](https://gitlab.com/gitlab-org/gitlab/-/issues/362941) removed.
+- User-specified verification token API support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360813) in GitLab 15.4.
+- [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2.
+- User-specified destination name API support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413894) in GitLab 16.2.
+- API [feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/417708) removed in GitLab 16.4.
+
+{{< /history >}}
Manage audit event streaming destinations for top-level groups by using a GraphQL API.
@@ -27,9 +34,12 @@ Manage HTTP streaming destinations for top-level groups.
Add a new streaming destination to top-level groups.
-WARNING:
+{{< alert type="warning" >}}
+
Streaming destinations receive **all** audit event data, which could include sensitive information. Make sure you trust the streaming destination.
+{{< /alert >}}
+
Prerequisites:
- Owner role for a top-level group.
@@ -281,12 +291,16 @@ The header is deleted if the returned `errors` object is empty.
### Event type filters
-> - Event type filters API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344845) in GitLab 15.7.
+{{< history >}}
+
+- Event type filters API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344845) in GitLab 15.7.
+
+{{< /history >}}
When this feature is enabled for a group, you can use an API to permit users to filter streamed audit events per destination.
If the feature is enabled with no filters, the destination receives all audit events.
-A streaming destination that has an event type filter set has a **filtered** (**{filter}**) label.
+A streaming destination that has an event type filter set has a **filtered** ({{< icon name="filter" >}}) label.
#### Use the API to add an event type filter
@@ -338,12 +352,16 @@ Event type filters are removed if:
### Namespace filters
-> - Namespace filters API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344845) in GitLab 16.7.
+{{< history >}}
+
+- Namespace filters API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344845) in GitLab 16.7.
+
+{{< /history >}}
When you apply a namespace filter to a group, users can filter streamed audit events per destination for a specific subgroup or project of the group. Otherwise, the
destination receives all audit events.
-A streaming destination that has a namespace filter set has a **filtered** (**{filter}**) label.
+A streaming destination that has a namespace filter set has a **filtered** ({{< icon name="filter" >}}) label.
#### Use the API to add a namespace filter
@@ -425,7 +443,11 @@ Namespace filter is removed if:
## Google Cloud Logging destinations
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) in GitLab 16.1.
+
+{{< /history >}}
Manage Google Cloud Logging destinations for top-level groups.
diff --git a/doc/api/graphql/audit_event_streaming_instances.md b/doc/api/graphql/audit_event_streaming_instances.md
index 244cf1aec184035a18ba7b98bc84da5f89b2bc59..5aa7ba5e85ac171233f75c150a39a8895f7524d2 100644
--- a/doc/api/graphql/audit_event_streaming_instances.md
+++ b/doc/api/graphql/audit_event_streaming_instances.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Audit event streaming GraphQL API for instances
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335175) in GitLab 16.0 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default.
-> - APIs for custom HTTP headers for instance level streaming destinations [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404560) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default.
-> - [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2.
-> - User-specified destination name API support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413894) in GitLab 16.2.
-> - Instance streaming destinations [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) in GitLab 16.4. [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/417708) removed.
+- Tier: Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335175) in GitLab 16.0 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default.
+- APIs for custom HTTP headers for instance level streaming destinations [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404560) in GitLab 16.1 [with a flag](../feature_flags.md) named `ff_external_audit_events`. Disabled by default.
+- [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) enabled by default in GitLab 16.2.
+- User-specified destination name API support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413894) in GitLab 16.2.
+- Instance streaming destinations [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/393772) in GitLab 16.4. [Feature flag `ff_external_audit_events`](https://gitlab.com/gitlab-org/gitlab/-/issues/417708) removed.
+
+{{< /history >}}
Manage audit event streaming destinations for instances by using a GraphQL API.
@@ -228,12 +235,16 @@ The header is deleted if the returned `errors` object is empty.
### Event type filters
-> - Event type filters API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10868) in GitLab 16.2.
+{{< history >}}
+
+- Event type filters API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10868) in GitLab 16.2.
+
+{{< /history >}}
When this feature is enabled for an instance, you can use an API to permit users to filter streamed audit events per destination.
If the feature is enabled with no filters, the destination receives all audit events.
-A streaming destination that has an event type filter set has a **filtered** (**{filter}**) label.
+A streaming destination that has an event type filter set has a **filtered** ({{< icon name="filter" >}}) label.
#### Use the API to add an event type filter
@@ -285,7 +296,11 @@ Event type filters are removed if:
## Google Cloud Logging destinations
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11303) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11303) in GitLab 16.5.
+
+{{< /history >}}
Manage Google Cloud Logging destinations for an entire instance.
diff --git a/doc/api/graphql/audit_report.md b/doc/api/graphql/audit_report.md
index 2f18add0515ad064ded0fbdf17017f55981759b7..b3e5ec7b698a9f6c00ee9303173496bf67141fa0 100644
--- a/doc/api/graphql/audit_report.md
+++ b/doc/api/graphql/audit_report.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Create an audit report by using GraphQL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can create an audit report for a specific subset of users by using:
@@ -77,10 +80,13 @@ You can use GraphiQL to query information about a subset of users.
1. Select **Play**.
-NOTE:
+{{< alert type="note" >}}
+
[The GraphQL API returns a GlobalID, rather than a standard ID](getting_started.md#queries-and-mutations).
It also expects a GlobalID as an input rather than a single integer.
+{{< /alert >}}
+
This query returns the groups and projects that the user has been explicitly made a member of.
- Because GraphiQL uses the session token to authorize access to resources,
diff --git a/doc/api/graphql/branch_rules.md b/doc/api/graphql/branch_rules.md
index 924405a55ec2421aa919f189fd9e1be9111ea015..b52cf9cad42efc959d8f980a10bf65afe2657248 100644
--- a/doc/api/graphql/branch_rules.md
+++ b/doc/api/graphql/branch_rules.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: List branch rules for a project by using GraphQL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106954) in GitLab 15.8.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106954) in GitLab 15.8.
+
+{{< /history >}}
You can query for branch rules in a given project by using:
diff --git a/doc/api/graphql/custom_emoji.md b/doc/api/graphql/custom_emoji.md
index df3fb890eaadea13e516dd8a33592aacb899950b..0deeea5cc5c0f1b8c73116baab7a37ee61de4a15 100644
--- a/doc/api/graphql/custom_emoji.md
+++ b/doc/api/graphql/custom_emoji.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use custom emoji with GraphQL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../../administration/feature_flags.md) named `custom_emoji`. Disabled by default.
-> - Enabled on GitLab.com in GitLab 14.0.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138969) in GitLab 16.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 16.9. Feature flag `custom_emoji` removed.
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../../administration/feature_flags.md) named `custom_emoji`. Disabled by default.
+- Enabled on GitLab.com in GitLab 14.0.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138969) in GitLab 16.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 16.9. Feature flag `custom_emoji` removed.
+
+{{< /history >}}
To use [custom emoji](../../user/emoji_reactions.md) in comments and descriptions,
you can add them to a top-level group by using the GraphQL API.
diff --git a/doc/api/graphql/epic_work_items_api_migration_guide.md b/doc/api/graphql/epic_work_items_api_migration_guide.md
index d999bb5dd8de53afa0557fe5beb61721ed46615c..d57f313efced207fe1954d7add4fe60c555452a5 100644
--- a/doc/api/graphql/epic_work_items_api_migration_guide.md
+++ b/doc/api/graphql/epic_work_items_api_migration_guide.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrate epic APIs to work items
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9290) in GitLab 17.2 [with a flag](../../administration/feature_flags.md) named `work_item_epics`. Disabled by default. Your administrator must have [enabled the new look for epics](../../user/group/epics/epic_work_items.md). This feature is in [beta](../../policy/development_stages_support.md#beta).
-> - Listing epics using the [GraphQL API](reference/_index.md) [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12852) in GitLab 17.4.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/470685) in GitLab 17.6.
-> - [Enabled by default on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/468310) in GitLab 17.7.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9290) in GitLab 17.2 [with a flag](../../administration/feature_flags.md) named `work_item_epics`. Disabled by default. Your administrator must have [enabled the new look for epics](../../user/group/epics/epic_work_items.md). This feature is in [beta](../../policy/development_stages_support.md#beta).
+- Listing epics using the [GraphQL API](reference/_index.md) [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12852) in GitLab 17.4.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/470685) in GitLab 17.6.
+- [Enabled by default on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/468310) in GitLab 17.7.
+
+{{< /history >}}
In GitLab 17.2, we introduced [epics as work items](../../user/group/epics/epic_work_items.md).
@@ -65,10 +72,13 @@ around with existing queries:
### Query epics
-NOTE:
+{{< alert type="note" >}}
+
Epic IDs are different from work item IDs, but the IID (ID incremented for each group) remains the same.
For example, an epic at `/gitlab-org/-/epics/123` has the same IID `123` as a work item.
+{{< /alert >}}
+
**Before (Epic API):**
```graphql
diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md
index 387eb90bc237d51da82cbf1e9ec1e3f7e728eb3a..84bf929cf00e101fe85f711df4e270e7f8bf0455 100644
--- a/doc/api/graphql/getting_started.md
+++ b/doc/api/graphql/getting_started.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Run GraphQL API queries and mutations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This guide demonstrates basic usage of the GitLab GraphQL API.
@@ -68,9 +71,12 @@ curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_T
### Rails console
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GraphQL queries can be run in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session). For example, to search projects:
@@ -99,12 +105,15 @@ The GitLab GraphQL API can be used to perform:
- Queries for data retrieval.
- [Mutations](#mutations) for creating, updating, and deleting data.
-NOTE:
+{{< alert type="note" >}}
+
In the GitLab GraphQL API, `id` refers to a
[Global ID](https://graphql.org/learn/global-object-identification/),
which is an object identifier in the format of `"gid://gitlab/Issue/123"`.
For more information, see [Global IDs](_index.md#global-ids).
+{{< /alert >}}
+
[GitLab GraphQL Schema](reference/_index.md) outlines which objects and fields are
available for clients to query and their corresponding data types.
diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md
index 04e0f58e76da20b3442f2cded5e880d725269ed2..906538fdadf5aaac70cfb8cdf802e302920d03f7 100644
--- a/doc/api/graphql/removed_items.md
+++ b/doc/api/graphql/removed_items.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GraphQL API removed items
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GraphQL is a versionless API, unlike the REST API.
Occasionally, items have to be updated or removed from the GraphQL API.
diff --git a/doc/api/graphql/sample_issue_boards.md b/doc/api/graphql/sample_issue_boards.md
index c8aaaf89d0d7b821ee78c98ea586160abc839cff..acfc55ef33cfd801e189962eb24cd30a4ee05ad6 100644
--- a/doc/api/graphql/sample_issue_boards.md
+++ b/doc/api/graphql/sample_issue_boards.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Identify issue boards by using GraphQL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can identify [issue boards](../../user/project/issue_board.md) for a project by using:
diff --git a/doc/api/graphql/users_example.md b/doc/api/graphql/users_example.md
index aa985b673f3b18a5498d2f33b6c4458f1c212dd8..07bee44e696d03bdca74fc64294513f6e348bcec 100644
--- a/doc/api/graphql/users_example.md
+++ b/doc/api/graphql/users_example.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Query users by using GraphQL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can query a subset of users in a GitLab instance by using:
@@ -47,10 +50,13 @@ You can query a subset of users in a GitLab instance by using:
1. Select **Play**.
-NOTE:
+{{< alert type="note" >}}
+
[The GraphQL API returns a GlobalID, rather than a standard ID](getting_started.md#queries-and-mutations).
It also expects a GlobalID as an input rather than a single integer.
+{{< /alert >}}
+
This query returns the specified information for the three users with the listed username.
- Because GraphiQL uses the session token to authorize access to resources,
diff --git a/doc/api/group_access_tokens.md b/doc/api/group_access_tokens.md
index 525289a97a7e868a7f37f698d389b3ac3f5f7102..e5b40b88866f93cdb5db69671eb865b56265703f 100644
--- a/doc/api/group_access_tokens.md
+++ b/doc/api/group_access_tokens.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group access tokens API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with group access tokens. For more information, see [Group access tokens](../user/group/settings/group_access_tokens.md).
## List all group access tokens
-> - `state` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.2.
+{{< history >}}
+
+- `state` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.2.
+
+{{< /history >}}
Lists all group access tokens for a group.
@@ -109,7 +116,11 @@ curl --request GET \
## Create a group access token
-> - The `expires_at` attribute default was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120213) in GitLab 16.0.
+{{< history >}}
+
+- The `expires_at` attribute default was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120213) in GitLab 16.0.
+
+{{< /history >}}
Creates a group access token for a specified group.
@@ -157,8 +168,12 @@ curl --request POST \
## Rotate a group access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403042) in GitLab 16.0
-> - `expires_at` attribute [added](https://gitlab.com/gitlab-org/gitlab/-/issues/416795) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403042) in GitLab 16.0
+- `expires_at` attribute [added](https://gitlab.com/gitlab-org/gitlab/-/issues/416795) in GitLab 16.6.
+
+{{< /history >}}
Rotates a group access token. This immediately revokes the previous token and creates a new token. Generally, this endpoint rotates a specific group access token by authenticating with a personal access token. You can also use a group access token to rotate itself. For more information, see [Self-rotate](#self-rotate).
diff --git a/doc/api/group_activity_analytics.md b/doc/api/group_activity_analytics.md
index 1314841cdf1bd410571471954e1a0cf01e729cf6..ac7f6627a8807493c5bbc3fb6cb28d3c13a6374c 100644
--- a/doc/api/group_activity_analytics.md
+++ b/doc/api/group_activity_analytics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group Activity Analytics API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Get count of recently created issues for group
diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md
index b6902ffa70c5c45bb30376df4916912387ed22f9..0780c09e762815c08100aa59319a8965b36f807e 100644
--- a/doc/api/group_badges.md
+++ b/doc/api/group_badges.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group badges API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Placeholder tokens
diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md
index 694d099e403ace0ec7c712043b1b89cf07e50bf1..ba574d9d3a12c3e1ea837d31b29915519f3e5436 100644
--- a/doc/api/group_boards.md
+++ b/doc/api/group_boards.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group issue boards API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every API call to [group issue boards](../user/project/issue_board.md#group-issue-boards) must be authenticated.
@@ -247,9 +250,12 @@ Example response:
## Create a group issue board
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Creates a group issue board.
@@ -356,9 +362,12 @@ Example response:
## Delete a group issue board
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Deletes a group issue board.
diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md
index 4a25052e90eb18c743c32575ce578cac4d7c83f3..feb3bd7a22e5b71ec18f0180b6f787ee7c79bf5f 100644
--- a/doc/api/group_clusters.md
+++ b/doc/api/group_clusters.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group clusters API (certificate-based) (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< /alert >}}
+
Similarly to [project-level](../user/project/clusters/_index.md) and
[instance-level](../user/instance/clusters/_index.md) Kubernetes clusters,
group-level Kubernetes clusters allow you to connect a Kubernetes cluster to
@@ -252,11 +258,14 @@ Parameters:
| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. |
| `environment_scope` | string | no | The associated environment to the cluster. Premium and Ultimate only. |
-NOTE:
+{{< alert type="note" >}}
+
`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added
through the ["Add existing Kubernetes cluster"](../user/project/clusters/add_existing_cluster.md) option or
through the ["Add existing cluster to group"](#add-existing-cluster-to-group) endpoint.
+{{< /alert >}}
+
Example request:
```shell
diff --git a/doc/api/group_enterprise_users.md b/doc/api/group_enterprise_users.md
index 1a28ef39d5a5d78b84a2350cbff9f0a044ea0b0c..6c13da9f482dd770671af32bb31fa84df0df6a67 100644
--- a/doc/api/group_enterprise_users.md
+++ b/doc/api/group_enterprise_users.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group enterprise users API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Use this API to interact with enterprise users accounts. For more information, see [enterprise users](../user/enterprise_user/_index.md).
@@ -19,7 +22,11 @@ Prerequisites:
## List all enterprise users
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438366) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438366) in GitLab 17.7.
+
+{{< /history >}}
Lists all enterprise users for a given top-level group.
@@ -112,7 +119,11 @@ Example response:
## Get details on an enterprise user
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176328) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176328) in GitLab 17.9.
+
+{{< /history >}}
Gets details on a specified enterprise user.
@@ -194,7 +205,11 @@ Example response:
## Disable two-factor authentication for an enterprise user
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/177943) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/177943) in GitLab 17.9.
+
+{{< /history >}}
Disables two-factor authentication (2FA) for a specified enterprise user.
diff --git a/doc/api/group_epic_boards.md b/doc/api/group_epic_boards.md
index 2c857db26307908d8a19c51383e0069d9eb6b369..3805c52447a77315db3e1e744114bf00e53922ff 100644
--- a/doc/api/group_epic_boards.md
+++ b/doc/api/group_epic_boards.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group epic boards API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385903) in GitLab 15.9.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385903) in GitLab 15.9.
+
+{{< /history >}}
Every API call to [group epic boards](../user/group/epics/epic_boards.md) must be authenticated.
@@ -181,7 +188,11 @@ Example response:
## List group epic board lists
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385904) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385904) in GitLab 15.9.
+
+{{< /history >}}
Gets a list of the epic board's lists.
Does not include `open` and `closed` lists.
@@ -241,7 +252,11 @@ Example response:
## Single group epic board list
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385904) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385904) in GitLab 15.9.
+
+{{< /history >}}
Gets a single board list.
diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md
index 07756fe5223ec2f1062ac3e1962a193c3ec805a8..14be5864aa1fe58360a6dc6d13eafabbe706052f 100644
--- a/doc/api/group_import_export.md
+++ b/doc/api/group_import_export.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group import and export API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the group import and export API to export a group structure and import it to a new location.
When you use the group import and export API with the [project import and export API](project_import_export.md), you can preserve connections with
diff --git a/doc/api/group_integrations.md b/doc/api/group_integrations.md
index 638b6e997ab31857a5ee0b78bd20a751ed5ccfe9..f047d2f7bcf83758a614a4914c6a37cfd27ad90d 100644
--- a/doc/api/group_integrations.md
+++ b/doc/api/group_integrations.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group integrations API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328496) in GitLab 17.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328496) in GitLab 17.9.
+
+{{< /history >}}
Use this API to work with external services that integrate with GitLab.
@@ -677,14 +684,20 @@ GET /groups/:id/integrations/external-wiki
## GitGuardian
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `git_guardian_integration`.
On GitLab.com, this feature is not available. On GitLab Dedicated, this feature is available.
+{{< /alert >}}
+
[GitGuardian](https://www.gitguardian.com/) is a cybersecurity service that detects sensitive data such as API keys
and passwords in source code repositories.
It scans Git repositories, alerts on policy violations, and helps organizations
@@ -735,9 +748,12 @@ GET /groups/:id/integrations/git-guardian
## GitHub
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
### Set up GitHub
@@ -916,10 +932,13 @@ GET /groups/:id/integrations/hangouts-chat
## Google Artifact Management
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
+
+{{< /details >}}
This feature is in [beta](../policy/experiment-beta-support.md).
@@ -958,10 +977,13 @@ GET /groups/:id/integrations/google-cloud-platform-artifact-registry
## Google Cloud Identity and Access Management (IAM)
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
+
+{{< /details >}}
This feature is in [beta](../policy/experiment-beta-support.md).
diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md
index 3a3523755265a1e6a1326faf2ab1b53bc1c18cf6..e57d0f822c5267673b1c66ccdb07bb1363e4613f 100644
--- a/doc/api/group_iterations.md
+++ b/doc/api/group_iterations.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group iterations API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page describes the group iterations API.
There's a separate [project iterations API](iterations.md) page.
diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md
index 2045a41c0af8447beaf53c3ba852ddb3e5998ba4..40670aa24871af8e01511081dea332b145922870 100644
--- a/doc/api/group_labels.md
+++ b/doc/api/group_labels.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group labels API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This API supports managing [group labels](../user/project/labels.md#types-of-labels).
It allows users to list, create, update, and delete group labels. Furthermore, users can subscribe to and
@@ -178,9 +181,12 @@ Example response:
}
```
-NOTE:
+{{< alert type="note" >}}
+
An older endpoint `PUT /groups/:id/labels` with `name` in the parameters is still available, but deprecated.
+{{< /alert >}}
+
## Delete a group label
Deletes a group label with a given name.
@@ -198,9 +204,12 @@ DELETE /groups/:id/labels/:label_id
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"
```
-NOTE:
+{{< alert type="note" >}}
+
An older endpoint `DELETE /groups/:id/labels` with `name` in the parameters is still available, but deprecated.
+{{< /alert >}}
+
## Subscribe to a group label
Subscribes the authenticated user to a group label to receive notifications. If
diff --git a/doc/api/group_ldap_links.md b/doc/api/group_ldap_links.md
index 394d0f62bb7c5c26f5646dc071db9cf707b7fa82..94d21a8ffcb98b6d30720fee5de829d0a7d85b7b 100644
--- a/doc/api/group_ldap_links.md
+++ b/doc/api/group_ldap_links.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: LDAP group links
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
List, add, and delete [LDAP group links](../user/group/access_and_permissions.md#manage-group-memberships-with-ldap).
diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md
index a39980b5a2d8073d68b2ee5bbd434b4461dd2c64..60591145f4641b49d42a6f2f8f3fc892b0df2e5f 100644
--- a/doc/api/group_level_variables.md
+++ b/doc/api/group_level_variables.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group-level Variables API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## List group variables
@@ -54,7 +57,11 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
## Show variable details
-> - The `filter` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9.
+{{< history >}}
+
+- The `filter` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9.
+
+{{< /history >}}
Get the details of a group's specific variable. If there are multiple variables with the same key,
use `filter` to select the correct `environment_scope`.
@@ -89,7 +96,11 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
## Create variable
-> - `masked_and_hidden` and `hidden` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29674) in GitLab 17.4.
+{{< history >}}
+
+- `masked_and_hidden` and `hidden` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29674) in GitLab 17.4.
+
+{{< /history >}}
Create a new variable.
@@ -131,7 +142,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
## Update variable
-> - The `filter` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9.
+{{< history >}}
+
+- The `filter` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9.
+
+{{< /history >}}
Update a group's variable. If there are multiple variables with the same key,
use `filter` to select the correct `environment_scope`.
@@ -174,7 +189,11 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
## Remove variable
-> - The `filter` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9.
+{{< history >}}
+
+- The `filter` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9.
+
+{{< /history >}}
Remove a group's variable. If there are multiple variables with the same key,
use `filter` to select the correct `environment_scope`.
@@ -196,11 +215,18 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
## The `filter` parameter
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340185) in GitLab 16.9.
+{{< /history >}}
When multiple variables have the same `key`, [GET](#show-variable-details), [PUT](#update-variable),
or [DELETE](#remove-variable) requests might return:
diff --git a/doc/api/group_markdown_uploads.md b/doc/api/group_markdown_uploads.md
index e0cccb4565657749eeb1126175ed4a98119c421e..16d8d568570cc9844e4988a28b842a9c0ae4070b 100644
--- a/doc/api/group_markdown_uploads.md
+++ b/doc/api/group_markdown_uploads.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group Markdown uploads API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Markdown uploads are [files uploaded to a group](../security/user_file_uploads.md)
that can be referenced in Markdown text in an epic or a wiki page.
## List uploads
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+
+{{< /history >}}
Get all uploads of the group sorted by `created_at` in descending order.
@@ -61,7 +68,11 @@ Example response:
## Download an uploaded file by ID
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+
+{{< /history >}}
You must have at least the Maintainer role to use this endpoint.
@@ -86,7 +97,11 @@ If successful, returns [`200`](rest/troubleshooting.md#status-codes) and the upl
## Download an uploaded file by secret and filename
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164441) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164441) in GitLab 17.4.
+
+{{< /history >}}
You must have at least the Guest role to use this endpoint.
@@ -112,7 +127,11 @@ If successful, returns [`200`](rest/troubleshooting.md#status-codes) and the upl
## Delete an uploaded file by ID
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+
+{{< /history >}}
You must have at least the Maintainer role to use this endpoint.
@@ -137,7 +156,11 @@ If successful, returns [`204`](rest/troubleshooting.md#status-codes) status code
## Delete an uploaded file by secret and filename
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164441) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164441) in GitLab 17.4.
+
+{{< /history >}}
You must have at least the Maintainer role to use this endpoint.
diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md
index 0d58c104d455156073d2781f4ab537ef3e8c469f..997b7f53a3a32aef3c769d5be7a13659d5353c63 100644
--- a/doc/api/group_milestones.md
+++ b/doc/api/group_milestones.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group milestones API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the group [milestones](../user/project/milestones/_index.md) using the REST API.
There's a separate [project milestones API](milestones.md) page.
@@ -181,9 +184,12 @@ Parameters:
## Get all burndown chart events for a single milestone
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Get all burndown chart events for a single milestone.
diff --git a/doc/api/group_protected_branches.md b/doc/api/group_protected_branches.md
index b1d12897a5869f96ef579ae3222dbcb155ad1803..513d923a59a03d215004f8052419b1876717d99b 100644
--- a/doc/api/group_protected_branches.md
+++ b/doc/api/group_protected_branches.md
@@ -5,20 +5,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group-level protected branches API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110603) in GitLab 15.9 [with a flag](../administration/feature_flags.md) named `group_protected_branches`. Disabled by default.
-> - Flag `group_protected_branches` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116779) [flag](../administration/feature_flags.md) to `allow_protected_branches_for_group` GitLab 15.11.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/500250) in GitLab 17.6. Feature flag `group_protected_branches` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110603) in GitLab 15.9 [with a flag](../administration/feature_flags.md) named `group_protected_branches`. Disabled by default.
+- Flag `group_protected_branches` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116779) [flag](../administration/feature_flags.md) to `allow_protected_branches_for_group` GitLab 15.11.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/500250) in GitLab 17.6. Feature flag `group_protected_branches` removed.
+
+{{< /history >}}
Use the protected branches API for groups to manage protected branch rules.
It provides endpoints to list, create, update, and delete protected branch rules that apply to projects belonging to a group.
-WARNING:
+{{< alert type="warning" >}}
+
Protected branch settings for groups are restricted to top-level groups only.
+{{< /alert >}}
+
## Valid access levels
The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` method.
diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md
index 780233172c12a40e438909f8cfad881b3f2d90c3..371edb28843c87a42e0ac8d7ae461290b51ec98a 100644
--- a/doc/api/group_protected_environments.md
+++ b/doc/api/group_protected_environments.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group-level protected environments API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in GitLab 14.0. [Deployed behind the `group_level_protected_environments` flag](../administration/feature_flags.md), disabled by default.
-> - [Feature flag `group_level_protected_environments`](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) removed in GitLab 14.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) in GitLab 14.3.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in GitLab 14.0. [Deployed behind the `group_level_protected_environments` flag](../administration/feature_flags.md), disabled by default.
+- [Feature flag `group_level_protected_environments`](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) removed in GitLab 14.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) in GitLab 14.3.
+
+{{< /history >}}
Read more about [group-level protected environments](../ci/environments/protected_environments.md#group-level-protected-environments).
@@ -152,7 +159,11 @@ to `production` only after the QA group `"group_id": 134` and security group
## Update a protected environment
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351854) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351854) in GitLab 15.4.
+
+{{< /history >}}
Updates a single environment.
diff --git a/doc/api/group_push_rules.md b/doc/api/group_push_rules.md
index abbff99e3509268075ec76df8be97d7dc825549b..bd3db5609476fe2f24bb6eb109d79f3ddebafaea 100644
--- a/doc/api/group_push_rules.md
+++ b/doc/api/group_push_rules.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Use push rules to control the content and format of Git commits your repository will accept. Set standards for commit messages, and block secrets or credentials from being added accidentally."
+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
+description: Use push rules to control the content and format of Git commits your repository will accept. Set standards for commit messages, and block secrets or credentials from being added accidentally.
title: Group push rules API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The following [push rules](../user/group/access_and_permissions.md#group-push-rules)
endpoints are only available to group owners and administrators.
diff --git a/doc/api/group_relations_export.md b/doc/api/group_relations_export.md
index 8a20b95dfbaaf5ec2f62ddd5ee2a3a55b3f1964f..12553475f90950f395ce7b3d17bcfb1d1f201ce5 100644
--- a/doc/api/group_relations_export.md
+++ b/doc/api/group_relations_export.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group relations export API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The group relations export API partially exports a group's structure as separate files for each
top-level
diff --git a/doc/api/group_releases.md b/doc/api/group_releases.md
index d0fd4263a8256c2d0bba0c509a8a35a597e6f05e..ff4e10682c404c2756124de7ea1c25d75485de39 100644
--- a/doc/api/group_releases.md
+++ b/doc/api/group_releases.md
@@ -5,18 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group releases API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351703) in GitLab 14.10 [with a flag](../administration/feature_flags.md) named `group_releases_finder_inoperator`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/355463) in GitLab 15.0. Feature flag `group_releases_finder_inoperator` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351703) in GitLab 14.10 [with a flag](../administration/feature_flags.md) named `group_releases_finder_inoperator`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/355463) in GitLab 15.0. Feature flag `group_releases_finder_inoperator` removed.
+
+{{< /history >}}
Review your groups' [releases](../user/project/releases/_index.md) with the REST API.
-NOTE:
+{{< alert type="note" >}}
+
For more information about the project releases API, see [Releases API](releases/_index.md).
+{{< /alert >}}
+
## List group releases
Returns a list of group releases.
diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md
index 0ddfc7eb26b4c420eece71e558d7ac28b29a5b3a..ee14d5474b451b65dd66974932a22bdbf1e2f971 100644
--- a/doc/api/group_repository_storage_moves.md
+++ b/doc/api/group_repository_storage_moves.md
@@ -2,13 +2,16 @@
stage: Create
group: Remote Development
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
-description: "Documentation for the REST API for moving the storage for repositories in a GitLab group."
+description: Documentation for the REST API for moving the storage for repositories in a GitLab group.
title: Group repository storage moves API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Group wiki repositories can be moved between storages. This API can help you, for example,
[migrate to Gitaly Cluster](../administration/gitaly/_index.md#migrate-to-gitaly-cluster)
diff --git a/doc/api/group_security_settings.md b/doc/api/group_security_settings.md
index 5db04471825c531c6a9cf91eb6eba7b823fc6e58..4687b3d2c1dc88c6b540f4d5950fb92114d39c32 100644
--- a/doc/api/group_security_settings.md
+++ b/doc/api/group_security_settings.md
@@ -1,15 +1,22 @@
---
stage: Security Risk Management
group: Security Platform Management
-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"
+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
title: Group security settings API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/502827) in GitLab 17.7.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/502827) in GitLab 17.7.
+
+{{< /history >}}
Every API call to group security settings must be [authenticated](rest/authentication.md).
diff --git a/doc/api/group_service_accounts.md b/doc/api/group_service_accounts.md
index d95b5a79bf21b26b5306050f9cdbacc08171875d..a93340dbc4e4f6b78e03eccb0cb57ec52a05d5ea 100644
--- a/doc/api/group_service_accounts.md
+++ b/doc/api/group_service_accounts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group service accounts API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with service accounts for your groups. For more information, see [Service accounts](../user/profile/service_accounts.md).
@@ -17,7 +20,11 @@ Prerequisites:
## List all service account users
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416729) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416729) in GitLab 17.1.
+
+{{< /history >}}
Lists all service account users in a specified top-level group.
@@ -61,14 +68,21 @@ Example response:
## Create a service account user
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407775) in GitLab 16.1.
-> - Specify a service account user username or name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144841) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407775) in GitLab 16.1.
+- Specify a service account user username or name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144841) in GitLab 16.10.
+
+{{< /history >}}
Creates a service account user in a given top-level group.
-NOTE:
+{{< alert type="note" >}}
+
This endpoint only works on top-level groups.
+{{< /alert >}}
+
```plaintext
POST /groups/:id/service_accounts
```
@@ -99,13 +113,20 @@ Example response:
## Delete a service account user
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416729) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416729) in GitLab 17.1.
+
+{{< /history >}}
Deletes a service account user from a given top-level group.
-NOTE:
+{{< alert type="note" >}}
+
This endpoint only works on top-level groups.
+{{< /alert >}}
+
```plaintext
DELETE /groups/:id/service_accounts/:user_id
```
@@ -126,13 +147,20 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git
## Create a personal access token for a service account user
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/406781) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/406781) in GitLab 16.1.
+
+{{< /history >}}
Creates a personal access token for an existing service account user in a given top-level group.
-NOTE:
+{{< alert type="note" >}}
+
This endpoint only works on top-level groups.
+{{< /alert >}}
+
```plaintext
POST /groups/:id/service_accounts/:user_id/personal_access_tokens
```
@@ -172,13 +200,20 @@ Example response:
## Rotate a personal access token for a service account user
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/406781) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/406781) in GitLab 16.1.
+
+{{< /history >}}
Rotates a personal access token for an existing service account user in a given top-level group. This creates a new token valid for one week and revokes any existing tokens.
-NOTE:
+{{< alert type="note" >}}
+
This endpoint only works on top-level groups.
+{{< /alert >}}
+
```plaintext
POST /groups/:id/service_accounts/:user_id/personal_access_tokens/:token_id/rotate
```
diff --git a/doc/api/group_ssh_certificates.md b/doc/api/group_ssh_certificates.md
index 18df2af0da0b95c4a2b14438ef34364e868068a5..f1f77e6e0081d41928ee8313e4df6ff3253a62d0 100644
--- a/doc/api/group_ssh_certificates.md
+++ b/doc/api/group_ssh_certificates.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group SSH certificates API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.4 [with a flag](../user/feature_flags.md) named `ssh_certificates_rest_endpoints`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/424501) in GitLab 16.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/424501) in GitLab 17.7. Feature flag `ssh_certificates_rest_endpoints` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.4 [with a flag](../user/feature_flags.md) named `ssh_certificates_rest_endpoints`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/424501) in GitLab 16.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/424501) in GitLab 17.7. Feature flag `ssh_certificates_rest_endpoints` removed.
+
+{{< /history >}}
Use this API to create, read and delete SSH certificates for a group.
Only top-level groups can store SSH certificates.
diff --git a/doc/api/group_webhooks.md b/doc/api/group_webhooks.md
index 1523e5b87043f6bb7017c4ac8fe0773499048432..70f420b5cc6ed02a8702e5912aa30b932c67aad9 100644
--- a/doc/api/group_webhooks.md
+++ b/doc/api/group_webhooks.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group webhooks API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Interact with group [webhooks](../user/project/integrations/webhooks.md) by using the REST API. Also called group hooks.
These are different from [system hooks](system_hooks.md) that are system wide and [project webhooks](project_webhooks.md) that are limited to one project.
@@ -148,7 +151,11 @@ Example response:
## Get group hook events
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151048) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151048) in GitLab 17.3.
+
+{{< /history >}}
Get a list of events for a specific group hook in the past seven days from start date.
@@ -425,7 +432,11 @@ Example response:
### Resend group hook event
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151130) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151130) in GitLab 17.4.
+
+{{< /history >}}
Resends a specific hook event.
@@ -664,8 +675,12 @@ On success, no message is returned.
## Trigger a test group hook
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/455589) in GitLab 17.1.
-> - Special rate limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150486) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `web_hook_test_api_endpoint_rate_limit`. Enabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/455589) in GitLab 17.1.
+- Special rate limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150486) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `web_hook_test_api_endpoint_rate_limit`. Enabled by default.
+
+{{< /history >}}
Trigger a test hook for a specified group.
@@ -697,7 +712,11 @@ Example response:
## Set a custom header
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153768) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153768) in GitLab 17.1.
+
+{{< /history >}}
Sets a custom header.
@@ -724,7 +743,11 @@ On success, no message is returned.
## Delete a custom header
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153768) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153768) in GitLab 17.1.
+
+{{< /history >}}
Deletes a custom header.
@@ -750,7 +773,11 @@ On success, no message is returned.
## Set a URL variable
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+
+{{< /history >}}
```plaintext
PUT /groups/:id/hooks/:hook_id/url_variables/:key
@@ -775,7 +802,11 @@ On success, no message is returned.
## Delete a URL variable
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+
+{{< /history >}}
```plaintext
DELETE /groups/:id/hooks/:hook_id/url_variables/:key
diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md
index 7d9594243f2b432f65f10a929f3c4bd3b69363b4..285c8569a0d108590105937de65ce96499447d87 100644
--- a/doc/api/group_wikis.md
+++ b/doc/api/group_wikis.md
@@ -1,13 +1,16 @@
---
stage: Plan
group: Knowledge
-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"
+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
title: Group wikis API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The [group wikis](../user/project/wiki/group.md) API is available only in APIv4.
An API for [project wikis](wikis.md) is also available.
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 151ccf1ae7a1141cd490de4e74c1272a0abae685..5d9f9a7c34bd35b8dd1e7d12f96a661d27d0d5d8 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Groups API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Interact with [groups](../user/group/_index.md) by using the REST API.
@@ -32,10 +35,13 @@ Parameters:
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only). |
| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects in a group, use the [list a group's projects endpoint](#list-projects).) |
-NOTE:
+{{< alert type="note" >}}
+
The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797).
To get the details of all projects within a group, use either the [list a group's projects](#list-projects) or the [list a group's shared projects](#list-shared-projects) endpoint.
+{{< /alert >}}
+
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4"
```
@@ -574,9 +580,12 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
To distinguish between a project in the group and a project shared to the group, the `namespace` attribute can be used. When a project has been shared to the group, its `namespace` differs from the group the request is being made for.
+{{< /alert >}}
+
### List shared projects
Get a list of projects shared to this group. When accessed without authentication, only public shared projects are returned.
@@ -716,9 +725,12 @@ Example response:
### List provisioned users
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Get a list of users provisioned by a given group. Does not include subgroups.
@@ -791,12 +803,19 @@ Example response:
### List users
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424505) in GitLab 16.6. This feature is an [experiment](../policy/development_stages_support.md).
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424505) in GitLab 16.6. This feature is an [experiment](../policy/development_stages_support.md).
+
+{{< /history >}}
Get a list of users for a group. This endpoint returns users that are related to a top-level group regardless
of their current membership. For example, users that have a SAML identity connected to the group, or service accounts created
@@ -1228,9 +1247,12 @@ Example response:
### List audit events
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Group audit events can be accessed via the [Group audit events API](audit_events.md#group-audit-events)
@@ -1238,10 +1260,13 @@ Group audit events can be accessed via the [Group audit events API](audit_events
### Create a group
-NOTE:
+{{< alert type="note" >}}
+
On GitLab SaaS, you must use the GitLab UI to create groups without a parent group. You cannot
use the API to do this.
+{{< /alert >}}
+
Creates a new project group. Available only for users who can create groups.
```plaintext
@@ -1295,7 +1320,11 @@ The `default_branch_protection` attribute determines whether users with the Deve
#### Options for `default_branch_protection_defaults`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408314) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408314) in GitLab 17.0.
+
+{{< /history >}}
The `default_branch_protection_defaults` attribute describes the default branch
protection defaults. All parameters are optional.
@@ -1323,9 +1352,12 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
### Sync a group with LDAP
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Syncs the group with its linked LDAP group. Only available to group owners and administrators.
@@ -1339,13 +1371,20 @@ Parameters:
### Update group attributes
-> - `unique_project_download_limit`, `unique_project_download_limit_interval_in_seconds`, and `unique_project_download_limit_allowlist` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92970) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default.
+{{< history >}}
+
+- `unique_project_download_limit`, `unique_project_download_limit_interval_in_seconds`, and `unique_project_download_limit_allowlist` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92970) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default `unique_project_download_limit`, `unique_project_download_limit_interval_in_seconds`, `unique_project_download_limit_allowlist` and `auto_ban_user_on_excessive_projects_download` are not available.
To make them available, an administrator can [enable the feature flag](../administration/feature_flags.md)
named `limit_unique_project_downloads_per_namespace_user`.
+{{< /alert >}}
+
Updates the project group. Only available to group owners and administrators.
```plaintext
@@ -1398,10 +1437,13 @@ PUT /groups/:id
| `lock_duo_features_enabled` | boolean | no | Indicates whether the GitLab Duo features enabled setting is enforced for all subgroups. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144931) in GitLab 16.10. GitLab Self-Managed, Premium and Ultimate only. |
| `max_artifacts_size` | integer | No | The maximum file size in megabytes for individual job artifacts. |
-NOTE:
+{{< alert type="note" >}}
+
The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797).
To get the details of all projects within a group, use either the [list a group's projects](#list-projects) or the [list a group's shared projects](#list-shared-projects) endpoint.
+{{< /alert >}}
+
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/groups/5?name=Experimental"
@@ -1539,7 +1581,11 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab
#### Remove a group avatar
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96421) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96421) in GitLab 15.4.
+
+{{< /history >}}
To remove a group avatar, use a blank value for the `avatar` attribute.
@@ -1552,10 +1598,14 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab
### Delete a group
-> - Immediately deleting subgroups was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360008) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `immediate_delete_subgroup_api`. Disabled by default.
-> - Immediately deleting subgroups was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) in GitLab 15.4.
-> - Immediately deleting subgroups was [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) by default in GitLab 15.4.
-> - The flag `immediate_delete_subgroup_api` for immediately deleting subgroups was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/374069) in GitLab 15.9.
+{{< history >}}
+
+- Immediately deleting subgroups was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360008) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `immediate_delete_subgroup_api`. Disabled by default.
+- Immediately deleting subgroups was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) in GitLab 15.4.
+- Immediately deleting subgroups was [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) by default in GitLab 15.4.
+- The flag `immediate_delete_subgroup_api` for immediately deleting subgroups was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/374069) in GitLab 15.9.
+
+{{< /history >}}
Only available to group owners and administrators.
@@ -1579,14 +1629,20 @@ Parameters:
The response is `202 Accepted` if the user has authorization.
-NOTE:
+{{< alert type="note" >}}
+
A GitLab.com group can't be deleted if it is linked to a subscription. To delete such a group, first [link the subscription](../subscriptions/gitlab_com/_index.md#link-subscription-to-a-group) with a different group.
+{{< /alert >}}
+
#### Restore a group marked for deletion
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Restores a group marked for deletion.
@@ -1602,13 +1658,20 @@ Parameters:
### Revoke a token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371117) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `group_agnostic_token_revocation`. Disabled by default.
-> - Revocation of user feed tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468599) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371117) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `group_agnostic_token_revocation`. Disabled by default.
+- Revocation of user feed tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468599) in GitLab 17.3.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Revoke a token, if it has access to the group or any of its subgroups
and projects. If the token is revoked, or was already revoked, its
details are returned in the response.
@@ -1748,7 +1811,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
#### List locations available for group transfer
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371117) in GitLab 15.4
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371117) in GitLab 15.4
+
+{{< /history >}}
Retrieve a list of groups to which the user can transfer a group.
diff --git a/doc/api/import.md b/doc/api/import.md
index fc5422b6f1e8b466839bd10859ccc6a76362c269..b9b975fde8de2f6626776e42f161a011297d38da 100644
--- a/doc/api/import.md
+++ b/doc/api/import.md
@@ -5,20 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the Import API to import repositories from GitHub or Bitbucket Server.
## Import repository from GitHub
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups if the namespace or group name specified in `target_namespace` doesn't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken or `target_namespace` is blank.
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
-> - `collaborators_import` key in `optional_stages` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398154) in GitLab 16.0.
-> - Feature flag `github_import_extended_events` was introduced in GitLab 16.8. Disabled by default. This flag improves the performance of imports but disables the `single_endpoint_issue_events_import` optional stage.
-> - Feature flag `github_import_extended_events` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/435089) in GitLab 16.9.
-> - Improved import performance made [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435089) in GitLab 16.11. Feature flag `github_import_extended_events` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups if the namespace or group name specified in `target_namespace` doesn't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken or `target_namespace` is blank.
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+- `collaborators_import` key in `optional_stages` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398154) in GitLab 16.0.
+- Feature flag `github_import_extended_events` was introduced in GitLab 16.8. Disabled by default. This flag improves the performance of imports but disables the `single_endpoint_issue_events_import` optional stage.
+- Feature flag `github_import_extended_events` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/435089) in GitLab 16.9.
+- Improved import performance made [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435089) in GitLab 16.11. Feature flag `github_import_extended_events` removed.
+
+{{< /history >}}
Import your projects from GitHub to GitLab using the API.
@@ -91,7 +98,11 @@ Example response:
### Import a public project through the API using a group access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362683) in GitLab 15.7, projects are not imported into a [bot user's](../user/group/settings/group_access_tokens.md#bot-users-for-groups) namespace in any circumstances. Projects imported into a bot user's namespace could not be deleted by users with valid tokens, which represented a security risk.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362683) in GitLab 15.7, projects are not imported into a [bot user's](../user/group/settings/group_access_tokens.md#bot-users-for-groups) namespace in any circumstances. Projects imported into a bot user's namespace could not be deleted by users with valid tokens, which represented a security risk.
+
+{{< /history >}}
When you import a project from GitHub to GitLab through the API using a group access
token:
@@ -101,7 +112,11 @@ token:
### Cancel GitHub project import
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364783) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364783) in GitLab 15.5.
+
+{{< /history >}}
Cancel an in-progress GitHub project import using the API.
@@ -146,9 +161,13 @@ Returns the following status codes:
### Import GitHub gists into GitLab snippets
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371099) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `github_import_gists`. Disabled by default. Enabled on GitLab.com.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386579) in GitLab 15.10.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/386579) in GitLab 15.11. Feature flag `github_import_gists` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371099) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `github_import_gists`. Disabled by default. Enabled on GitLab.com.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386579) in GitLab 15.10.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/386579) in GitLab 15.11. Feature flag `github_import_gists` removed.
+
+{{< /history >}}
You can use the GitLab API to import personal GitHub gists (with up to 10 files) into personal GitLab snippets.
GitHub gists with more than 10 files are skipped. You should manually migrate these GitHub gists.
@@ -224,7 +243,11 @@ curl --request POST \
## Import repository from Bitbucket Cloud
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215036) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215036) in GitLab 17.0.
+
+{{< /history >}}
Import your projects from Bitbucket Cloud to GitLab using by the API.
diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md
index 2ac0122dc6f66f287c072cc98661e72870059cd9..ba6b403c7db7929b0db4a996ab504c4e98c13ee6 100644
--- a/doc/api/instance_clusters.md
+++ b/doc/api/instance_clusters.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Instance clusters API (certificate-based) (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< /alert >}}
+
With [instance-level Kubernetes clusters](../user/instance/clusters/_index.md),
you can connect a Kubernetes cluster to the GitLab instance and use the same cluster across all of
the projects within your instance.
@@ -241,11 +247,14 @@ Parameters:
| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. |
| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project |
-NOTE:
+{{< alert type="note" >}}
+
`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added
through the [Add existing Kubernetes cluster](../user/project/clusters/add_existing_cluster.md) option or
through the [Add existing instance cluster](#add-existing-instance-cluster) endpoint.
+{{< /alert >}}
+
Example request:
```shell
diff --git a/doc/api/instance_level_ci_variables.md b/doc/api/instance_level_ci_variables.md
index c7a449566ebb02ebe4cec5ae73d382be54afc021..c3c24d06e4a0c70b17a0cd9c757ce3f9f6167119 100644
--- a/doc/api/instance_level_ci_variables.md
+++ b/doc/api/instance_level_ci_variables.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Instance-level CI/CD variables API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## List all instance variables
-> - `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
+{{< history >}}
+
+- `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
+
+{{< /history >}}
Get the list of all instance-level variables.
@@ -48,7 +55,11 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
## Show instance variable details
-> - `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
+{{< history >}}
+
+- `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
+
+{{< /history >}}
Get the details of a specific instance-level variable.
@@ -78,7 +89,11 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
## Create instance variable
-> - `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
+{{< history >}}
+
+- `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
+
+{{< /history >}}
Create a new instance-level variable.
@@ -117,7 +132,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
## Update instance variable
-> - `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
+{{< history >}}
+
+- `description` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418331) in GitLab 16.8.
+
+{{< /history >}}
Update an instance-level variable.
diff --git a/doc/api/integrations.md b/doc/api/integrations.md
index 3f4e7b2eee774e26b29035d68020604593fa596d..f44ac377ccd4ccf2cb4ac69eb9bc015156964d16 100644
--- a/doc/api/integrations.md
+++ b/doc/api/integrations.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project integrations API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to work with external services that integrate with GitLab.
@@ -15,9 +18,13 @@ This API requires an access token with the Maintainer or Owner role.
## List all active integrations
-> - `vulnerability_events` field [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131831) in GitLab 16.4.
-> - `inherited` field [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/154915) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `inherited` field [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `vulnerability_events` field [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131831) in GitLab 16.4.
+- `inherited` field [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/154915) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `inherited` field [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
Get a list of all active project integrations. The `vulnerability_events` field is only available for GitLab Enterprise Edition.
@@ -82,8 +89,12 @@ Example response:
## Apple App Store Connect
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Apple App Store Connect
@@ -122,8 +133,12 @@ GET /projects/:id/integrations/apple_app_store
## Asana
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Asana
@@ -159,8 +174,12 @@ GET /projects/:id/integrations/asana
## Assembla
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Assembla
@@ -196,8 +215,12 @@ GET /projects/:id/integrations/assembla
## Atlassian Bamboo
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Atlassian Bamboo
@@ -238,8 +261,12 @@ GET /projects/:id/integrations/bamboo
## Bugzilla
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Bugzilla
@@ -276,8 +303,12 @@ GET /projects/:id/integrations/bugzilla
## Buildkite
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Buildkite
@@ -317,8 +348,12 @@ GET /projects/:id/integrations/buildkite
## Campfire Classic
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
You can integrate with Campfire Classic. However, Campfire Classic is an old product that is
[no longer sold](https://gitlab.com/gitlab-org/gitlab/-/issues/329337) by Basecamp.
@@ -358,9 +393,13 @@ GET /projects/:id/integrations/campfire
## ClickUp
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120732) in GitLab 16.1.
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120732) in GitLab 16.1.
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up ClickUp
@@ -396,8 +435,12 @@ GET /projects/:id/integrations/clickup
## Confluence Workspace
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
Use a Confluence Cloud Workspace as your project wiki.
@@ -434,8 +477,12 @@ GET /projects/:id/integrations/confluence
## Custom issue tracker
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up a custom issue tracker
@@ -472,8 +519,12 @@ GET /projects/:id/integrations/custom-issue-tracker
## Datadog
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Datadog
@@ -515,8 +566,12 @@ GET /projects/:id/integrations/datadog
## Diffblue Cover
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Diffblue Cover
@@ -553,9 +608,13 @@ GET /projects/:id/integrations/diffblue-cover
## Discord Notifications
-> - `_channel` parameters [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125621) in GitLab 16.3.
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `_channel` parameters [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125621) in GitLab 16.3.
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Discord Notifications
@@ -616,8 +675,12 @@ GET /projects/:id/integrations/discord
## Drone
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Drone
@@ -657,8 +720,12 @@ GET /projects/:id/integrations/drone-ci
## Emails on push
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up emails on push
@@ -698,8 +765,12 @@ GET /projects/:id/integrations/emails-on-push
## Engineering Workflow Management (EWM)
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up EWM
@@ -736,8 +807,12 @@ GET /projects/:id/integrations/ewm
## External wiki
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up an external wiki
@@ -772,15 +847,22 @@ GET /projects/:id/integrations/external-wiki
## GitGuardian
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435706) in GitLab 16.9 [with a flag](../administration/feature_flags.md) named `git_guardian_integration`. Enabled by default. Disabled on GitLab.com.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/438695#note_2226917025) in GitLab 17.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176391) in GitLab 17.8. Feature flag `git_guardian_integration` removed.
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435706) in GitLab 16.9 [with a flag](../administration/feature_flags.md) named `git_guardian_integration`. Enabled by default. Disabled on GitLab.com.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/438695#note_2226917025) in GitLab 17.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176391) in GitLab 17.8. Feature flag `git_guardian_integration` removed.
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
[GitGuardian](https://www.gitguardian.com/) is a cybersecurity service that detects sensitive data such as API keys
and passwords in source code repositories.
@@ -832,12 +914,19 @@ GET /projects/:id/integrations/git-guardian
## GitHub
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up GitHub
@@ -902,8 +991,12 @@ GET /projects/:id/integrations/jira-cloud-app
## GitLab for Slack app
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up GitLab for Slack app
@@ -974,8 +1067,12 @@ GET /projects/:id/integrations/gitlab-slack-application
## Google Chat
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Google Chat
@@ -1022,15 +1119,22 @@ GET /projects/:id/integrations/hangouts-chat
## Google Artifact Management
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425066) in GitLab 16.9 as a [beta](../policy/development_stages_support.md) feature [with a flag](../administration/feature_flags.md) named `google_cloud_support_feature_flag`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425066) in GitLab 16.9 as a [beta](../policy/development_stages_support.md) feature [with a flag](../administration/feature_flags.md) named `google_cloud_support_feature_flag`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< /history >}}
This feature is in [beta](../policy/development_stages_support.md).
@@ -1069,15 +1173,22 @@ GET /projects/:id/integrations/google-cloud-platform-artifact-registry
## Google Cloud Identity and Access Management (IAM)
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439200) in GitLab 16.10 as a [beta](../policy/development_stages_support.md) feature [with a flag](../administration/feature_flags.md) named `google_cloud_support_feature_flag`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439200) in GitLab 16.10 as a [beta](../policy/development_stages_support.md) feature [with a flag](../administration/feature_flags.md) named `google_cloud_support_feature_flag`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
This feature is in [beta](../policy/development_stages_support.md).
@@ -1117,8 +1228,12 @@ GET /projects/:id/integration/google-cloud-platform-workload-identity-federation
## Google Play
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Google Play
@@ -1156,8 +1271,12 @@ GET /projects/:id/integrations/google-play
## Harbor
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Harbor
@@ -1195,8 +1314,12 @@ GET /projects/:id/integrations/harbor
## irker (IRC gateway)
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up irker
@@ -1235,8 +1358,12 @@ GET /projects/:id/integrations/irker
## Jenkins
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Jenkins
@@ -1278,8 +1405,12 @@ GET /projects/:id/integrations/jenkins
## JetBrains TeamCity
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up JetBrains TeamCity
@@ -1323,8 +1454,12 @@ GET /projects/:id/integrations/teamcity
## Jira issues
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Jira issues
@@ -1373,8 +1508,12 @@ GET /projects/:id/integrations/jira
## Matrix notifications
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Matrix notifications
@@ -1422,8 +1561,12 @@ GET /projects/:id/integrations/matrix
## Mattermost notifications
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Mattermost notifications
@@ -1483,8 +1626,12 @@ GET /projects/:id/integrations/mattermost
## Mattermost slash commands
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Mattermost slash commands
@@ -1519,8 +1666,12 @@ GET /projects/:id/integrations/mattermost-slash-commands
## Microsoft Teams notifications
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Microsoft Teams notifications
@@ -1567,8 +1718,12 @@ GET /projects/:id/integrations/microsoft-teams
## Mock CI
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
This integration is only available in a development environment.
For an example Mock CI server, see [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service).
@@ -1607,8 +1762,12 @@ GET /projects/:id/integrations/mock-ci
## Packagist
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Packagist
@@ -1648,9 +1807,13 @@ GET /projects/:id/integrations/packagist
## Phorge
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145863) in GitLab 16.11.
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145863) in GitLab 16.11.
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Phorge
@@ -1686,8 +1849,12 @@ GET /projects/:id/integrations/phorge
## Pipeline status emails
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up pipeline status emails
@@ -1726,8 +1893,12 @@ GET /projects/:id/integrations/pipelines-email
## Pivotal Tracker
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Pivotal Tracker
@@ -1763,8 +1934,12 @@ GET /projects/:id/integrations/pivotaltracker
## Pumble
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Pumble
@@ -1810,8 +1985,12 @@ GET /projects/:id/integrations/pumble
## Pushover
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Pushover
@@ -1850,8 +2029,12 @@ GET /projects/:id/integrations/pushover
## Redmine
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Redmine
@@ -1888,8 +2071,12 @@ GET /projects/:id/integrations/redmine
## Slack notifications
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Slack notifications
@@ -1957,8 +2144,12 @@ GET /projects/:id/integrations/slack
## Slack slash commands
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Slack slash commands
@@ -2019,9 +2210,13 @@ Example response:
## Squash TM
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337855) in GitLab 15.10.
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337855) in GitLab 15.10.
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Squash TM
@@ -2057,8 +2252,12 @@ GET /projects/:id/integrations/squash-tm
## Telegram
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Telegram
@@ -2107,8 +2306,12 @@ GET /projects/:id/integrations/telegram
## Unify Circuit
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Unify Circuit
@@ -2154,8 +2357,12 @@ GET /projects/:id/integrations/unify-circuit
## Webex Teams
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up Webex Teams
@@ -2201,8 +2408,12 @@ GET /projects/:id/integrations/webex-teams
## YouTrack
-> - `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
-> - `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+{{< history >}}
+
+- `use_inherited_settings` parameter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467089) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `integration_api_inheritance`. Disabled by default.
+- `use_inherited_settings` parameter [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467186) in GitLab 17.3. Feature flag `integration_api_inheritance` removed.
+
+{{< /history >}}
### Set up YouTrack
diff --git a/doc/api/invitations.md b/doc/api/invitations.md
index 14b82990f291e57db255eb96769f0fbf8d5cb473..74b44cf4c51d19a6a4457941df2a897a52dc2914 100644
--- a/doc/api/invitations.md
+++ b/doc/api/invitations.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Invitations API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the Invitations API to invite or add users to a group or project, and to list pending
invitations.
@@ -73,9 +76,12 @@ When there was any error sending the email:
}
```
-NOTE:
+{{< alert type="note" >}}
+
If [administrator approval for role promotions](../administration/settings/sign_up_restrictions.md#turn-on-administrator-approval-for-role-promotions) is turned on, membership requests that promote existing users into a billable role require administrator approval.
+{{< /alert >}}
+
To enable **Manage non-billable promotions**,
you must first enable the `enable_member_promotion_management` application setting.
diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md
index aebbe9c3a1a0cb6b8c5bc2b59980c1ffd1dae845..51a1d0063f533d6ffd82b0c1563b13fc6514bccc 100644
--- a/doc/api/issue_links.md
+++ b/doc/api/issue_links.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Issue links API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to GitLab Free in 13.4.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to GitLab Free in 13.4.
+
+{{< /history >}}
## List issue relations
@@ -68,7 +75,11 @@ Parameters:
## Get an issue link
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88228) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88228) in GitLab 15.1.
+
+{{< /history >}}
Gets details about an issue link.
diff --git a/doc/api/issues.md b/doc/api/issues.md
index e172112729084d648f17c82b151739da35160d39..1e7e8587030238384127f967dc3953e544448e7d 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Issues API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Interact with [GitLab Issues](../user/project/issues/_index.md) using the REST API.
@@ -20,11 +23,14 @@ By default, `GET` requests return 20 results at a time because the API results
are paginated.
Read more on [pagination](rest/_index.md#pagination).
-NOTE:
+{{< alert type="note" >}}
+
The `references.relative` attribute is relative to the group or project of the issue being requested.
When an issue is fetched from its project, the `relative` format is the same as the `short` format.
When requested across groups or projects, it's expected to be the same as the `full` format.
+{{< /alert >}}
+
## List issues
Get all issues the authenticated user has access to. By default it
@@ -249,13 +255,18 @@ Issues created by users on GitLab Ultimate include the `health_status` property:
]
```
-WARNING:
+{{< alert type="warning" >}}
+
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform
to the GitLab EE API.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
+{{< /alert >}}
## List group issues
@@ -457,12 +468,17 @@ Issues created by users on GitLab Ultimate include the `health_status` property:
]
```
-WARNING:
+{{< alert type="warning" >}}
+
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
+{{< /alert >}}
## List project issues
@@ -670,12 +686,17 @@ Issues created by users on GitLab Ultimate include the `health_status` property:
]
```
-WARNING:
+{{< alert type="warning" >}}
+
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
+{{< /alert >}}
## Single issue
@@ -841,13 +862,18 @@ property:
]
```
-WARNING:
+{{< alert type="warning" >}}
+
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform
to the GitLab EE API.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The `epic_iid` attribute is deprecated, and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
+{{< /alert >}}
## Single project issue
@@ -1007,12 +1033,17 @@ property:
]
```
-WARNING:
+{{< alert type="warning" >}}
+
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
+{{< /alert >}}
## New issue
@@ -1159,12 +1190,17 @@ Issues created by users on GitLab Ultimate include the `health_status` property:
]
```
-WARNING:
+{{< alert type="warning" >}}
+
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
+{{< /alert >}}
### Rate limits
@@ -1339,12 +1375,17 @@ Issues created by users on GitLab Ultimate include the `health_status` property:
]
```
-WARNING:
+{{< alert type="warning" >}}
+
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
`assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
+{{< /alert >}}
## Delete an issue
@@ -1546,12 +1587,17 @@ Issues created by users on GitLab Ultimate include the `health_status` property:
]
```
-WARNING:
+{{< alert type="warning" >}}
+
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
+{{< /alert >}}
## Clone an issue
@@ -1815,12 +1861,17 @@ Issues created by users on GitLab Ultimate include the `health_status` property:
]
```
-WARNING:
+{{< alert type="warning" >}}
+
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5.
Use `iid` of the `epic` attribute instead.
+{{< /alert >}}
### Unsubscribe from an issue
@@ -2023,14 +2074,20 @@ Example response:
}
```
-WARNING:
+{{< alert type="warning" >}}
+
The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API.
+{{< /alert >}}
+
## Promote an issue to an epic
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Promotes an issue to an epic by adding a comment with the `/promote`
[quick action](../user/project/quick_actions.md).
diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md
index 864718d274b188d7b0680097fbc588b1e1bd0282..909c1d1a993084a9c9090f065d6d9397ba7ec09f 100644
--- a/doc/api/issues_statistics.md
+++ b/doc/api/issues_statistics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Issues statistics API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every API call to the [issues](../user/project/issues/_index.md) statistics API must be authenticated.
diff --git a/doc/api/iterations.md b/doc/api/iterations.md
index ba86755fabd44e7a1e2a1fc8458d364dba826edb..b037a3f82ad018ca885689f08fe4709e71a2bf16 100644
--- a/doc/api/iterations.md
+++ b/doc/api/iterations.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project iterations API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page describes the project iterations API.
There's a separate [group iterations API](group_iterations.md) page.
diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md
index f2a97fc0f8e24f8104eabaa6b5a1d6a7051c037b..47da211c09f2c03c161bec3cfcef0699437eaaf0 100644
--- a/doc/api/job_artifacts.md
+++ b/doc/api/job_artifacts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Job Artifacts API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the job artifacts API to download or delete job artifacts.
@@ -16,7 +19,11 @@ available in the Premium and Ultimate tier.
## Get job artifacts
-> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5.
+{{< history >}}
+
+- The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5.
+
+{{< /history >}}
Get a zipped archive of a job's artifacts from a project.
@@ -75,7 +82,11 @@ Possible response status codes:
## Download the artifacts archive
-> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5.
+{{< history >}}
+
+- The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5.
+
+{{< /history >}}
Download a zipped archive of a job's artifacts in the latest **successful**
pipeline using the reference name. This endpoint is the same as
@@ -322,9 +333,12 @@ Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts"
```
-NOTE:
+{{< alert type="note" >}}
+
At least Maintainer role is required to delete artifacts.
+{{< /alert >}}
+
If the artifacts were deleted successfully, a response with status `204 No Content` is returned.
## Delete all job artifacts in a project
diff --git a/doc/api/jobs.md b/doc/api/jobs.md
index 4b2c34e96a38077090a462b0b79b7270569c5908..b0c45afaa28f1517076bd4a6e2b3c18ac9f1db71 100644
--- a/doc/api/jobs.md
+++ b/doc/api/jobs.md
@@ -5,22 +5,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Jobs API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## List project jobs
-> - Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362172) in GitLab 15.9.
+{{< history >}}
+
+- Support for keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362172) in GitLab 15.9.
+
+{{< /history >}}
Get a list of jobs in a project. Jobs are sorted in descending order of their IDs.
By default, this request returns 20 results at a time because the API results [are paginated](rest/_index.md#pagination)
-NOTE:
+{{< alert type="note" >}}
+
This endpoint supports both offset-based and [keyset-based](rest/_index.md#keyset-based-pagination) pagination, but keyset-based
pagination is strongly recommended when requesting consecutive pages of results.
+{{< /alert >}}
+
```plaintext
GET /projects/:id/jobs
```
@@ -845,9 +855,12 @@ Example of response
}
```
-NOTE:
+{{< alert type="note" >}}
+
Prior to GitLab 17.0, this endpoint does not support trigger jobs.
+{{< /alert >}}
+
## Erase a job
Erase a single job of a project (remove job artifacts and a job log)
@@ -909,10 +922,13 @@ Example of response
}
```
-NOTE:
+{{< alert type="note" >}}
+
You can't delete archived jobs with the API, but you can
[delete job artifacts and logs from jobs completed before a specific date](../administration/cicd/job_artifacts_troubleshooting.md#delete-old-builds-and-artifacts)
+{{< /alert >}}
+
## Run a job
For a job in manual status, trigger an action to start the job.
diff --git a/doc/api/keys.md b/doc/api/keys.md
index f66d2bd264e41f40e5d2eccf380bbd3f393d9722..d72a2190865b9d6114b9c6d9e16332f8d0f02c90 100644
--- a/doc/api/keys.md
+++ b/doc/api/keys.md
@@ -1,13 +1,16 @@
---
stage: Create
group: Source Code
-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"
+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
title: Keys API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If using a SHA256 fingerprint in an API call, you should URL-encode the fingerprint.
diff --git a/doc/api/labels.md b/doc/api/labels.md
index e873a52aec9c37759aa90a68b5fef09393758630..4d38580bcef60d2437498a738f7b150e2000890e 100644
--- a/doc/api/labels.md
+++ b/doc/api/labels.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Labels API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Interact with [labels](../user/project/labels.md) using the REST API.
@@ -202,9 +205,12 @@ DELETE /projects/:id/labels/:label_id
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug"
```
-NOTE:
+{{< alert type="note" >}}
+
An older endpoint `DELETE /projects/:id/labels` with `name` in the parameters is still available, but deprecated.
+{{< /alert >}}
+
## Edit an existing label
Updates an existing label with new name or new color. At least one parameter
@@ -247,9 +253,12 @@ Example response:
}
```
-NOTE:
+{{< alert type="note" >}}
+
An older endpoint `PUT /projects/:id/labels` with `name` or `label_id` in the parameters is still available, but deprecated.
+{{< /alert >}}
+
## Promote a project label to a group label
Promotes a project label to a group label. The label keeps its ID.
@@ -283,9 +292,12 @@ Example response:
}
```
-NOTE:
+{{< alert type="note" >}}
+
An older endpoint `PUT /projects/:id/labels/promote` with `name` in the parameters is still available, but deprecated.
+{{< /alert >}}
+
## Subscribe to a label
Subscribes the authenticated user to a label to receive notifications.
diff --git a/doc/api/license.md b/doc/api/license.md
index 73c0cbf0243d193f1da5e7a71713345abc2acce9..0c7242bda7810cf6baf3877da5d7f36f191bb8a9 100644
--- a/doc/api/license.md
+++ b/doc/api/license.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: License
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To interact with license endpoints, you need to authenticate yourself as an
administrator.
diff --git a/doc/api/linked_epics.md b/doc/api/linked_epics.md
index 289c103ad91200d2be668adfa3eae133145e4e30..bbf1d421f6546eed95ba438a10258bd0971a3eb1 100644
--- a/doc/api/linked_epics.md
+++ b/doc/api/linked_epics.md
@@ -5,20 +5,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Linked epics API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352493) in GitLab 14.9 [with a flag](../administration/feature_flags.md) named `related_epics_widget`. Enabled by default.
-> - [Feature flag `related_epics_widget`](https://gitlab.com/gitlab-org/gitlab/-/issues/357089) removed in GitLab 15.0.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352493) in GitLab 14.9 [with a flag](../administration/feature_flags.md) named `related_epics_widget`. Enabled by default.
+- [Feature flag `related_epics_widget`](https://gitlab.com/gitlab-org/gitlab/-/issues/357089) removed in GitLab 15.0.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0
and is planned for removal in v5 of the API.
In GitLab 17.4 or later, if your administrator [enabled the new look for epics](../user/group/epics/epic_work_items.md), use the
[Work Items API](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/) instead. For more information, see the [guide how to migrate your existing APIs](graphql/epic_work_items_api_migration_guide.md).
This change is a breaking change.
+{{< /alert >}}
+
If the Related Epics feature is not available in your GitLab plan, a `403` status code is returned.
## List related epic links from a group
@@ -221,7 +231,11 @@ Example response:
## Create a related epic link
-> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8.
+{{< history >}}
+
+- Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8.
+
+{{< /history >}}
Create a two-way relation between two epics. The user must have at least the Guest role for both groups.
@@ -342,7 +356,11 @@ Example response:
## Delete a related epic link
-> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8.
+{{< history >}}
+
+- Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8.
+
+{{< /history >}}
Delete a two-way relation between two epics. The user must have at least the Guest role for both groups.
diff --git a/doc/api/lint.md b/doc/api/lint.md
index 916455bebc79f9d40ddf9a7e11919052b82d26f2..238284fd2e2c0489d836f54a55f570e1c7195702 100644
--- a/doc/api/lint.md
+++ b/doc/api/lint.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI Lint API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Validate sample CI/CD configuration
@@ -64,8 +67,12 @@ Example responses:
## Validate a project's CI/CD configuration
-> - `sha` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369212) in GitLab 16.5.
-> - `sha` and `ref` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143098) to `content_ref` and `dry_run_ref` in GitLab 16.10.
+{{< history >}}
+
+- `sha` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369212) in GitLab 16.5.
+- `sha` and `ref` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143098) to `content_ref` and `dry_run_ref` in GitLab 16.10.
+
+{{< /history >}}
Checks if a project's `.gitlab-ci.yml` configuration in a given ref (the
`content_ref` parameter, by default `HEAD` of the project's default branch) is valid.
diff --git a/doc/api/markdown.md b/doc/api/markdown.md
index 1b3b47e0efccbc480536af8b67a471cecd3c0f8b..564455f294b8e072b8db87bc92c485b94c315a35 100644
--- a/doc/api/markdown.md
+++ b/doc/api/markdown.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Markdown API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Convert Markdown content to HTML.
@@ -15,13 +18,20 @@ Available only in APIv4.
## Required authentication
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93727) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `authenticate_markdown_api`. Enabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93727) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `authenticate_markdown_api`. Enabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
All API calls to the Markdown API must be [authenticated](rest/authentication.md).
## Render an arbitrary Markdown document
diff --git a/doc/api/member_roles.md b/doc/api/member_roles.md
index b0bb1a3a222f4a567e5be10d2935955aab7be191..c4eabc2b8221d7ab7da86d2988bbb7672af0e08f 100644
--- a/doc/api/member_roles.md
+++ b/doc/api/member_roles.md
@@ -5,34 +5,44 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Member roles API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96996) in GitLab 15.4. [Deployed behind the `customizable_roles` flag](../administration/feature_flags.md), disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9.
-> - [Read vulnerability added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114734) in GitLab 16.0.
-> - [Admin vulnerability added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121534) in GitLab 16.1.
-> - [Read dependency added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126247) in GitLab 16.3.
-> - [Name and description fields added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126423) in GitLab 16.3.
-> - [Admin merge request introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128302) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `admin_merge_request`. Disabled by default.
-> - [Feature flag `admin_merge_request` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132578) in GitLab 16.5.
-> - [Admin group members introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131914) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `admin_group_member`. Disabled by default. The feature flag has been removed in GitLab 16.6.
-> - [Manage project access tokens introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132342) in GitLab 16.5 in [with a flag](../administration/feature_flags.md) named `manage_project_access_tokens`. Disabled by default.
-> - [Archive project introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134998) in GitLab 16.7.
-> - [Delete project introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139696) in GitLab 16.8.
-> - [Manage group access tokens introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140115) in GitLab 16.8.
-> - [Admin terraform state introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140759) in GitLab 16.8.
-> - Allow to create and remove an instance-wide custom role on GitLab Self-Managed [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141562) in GitLab 16.9.
-> - [Admin security testing introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176628) in GitLab 17.9 [with a flag](../administration/feature_flags.md) named `custom_ability_admin_security_testing`. Disabled by default.
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96996) in GitLab 15.4. [Deployed behind the `customizable_roles` flag](../administration/feature_flags.md), disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9.
+- [Read vulnerability added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114734) in GitLab 16.0.
+- [Admin vulnerability added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121534) in GitLab 16.1.
+- [Read dependency added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126247) in GitLab 16.3.
+- [Name and description fields added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126423) in GitLab 16.3.
+- [Admin merge request introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128302) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `admin_merge_request`. Disabled by default.
+- [Feature flag `admin_merge_request` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132578) in GitLab 16.5.
+- [Admin group members introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131914) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `admin_group_member`. Disabled by default. The feature flag has been removed in GitLab 16.6.
+- [Manage project access tokens introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132342) in GitLab 16.5 in [with a flag](../administration/feature_flags.md) named `manage_project_access_tokens`. Disabled by default.
+- [Archive project introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134998) in GitLab 16.7.
+- [Delete project introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139696) in GitLab 16.8.
+- [Manage group access tokens introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140115) in GitLab 16.8.
+- [Admin terraform state introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140759) in GitLab 16.8.
+- Allow to create and remove an instance-wide custom role on GitLab Self-Managed [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141562) in GitLab 16.9.
+- [Admin security testing introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176628) in GitLab 17.9 [with a flag](../administration/feature_flags.md) named `custom_ability_admin_security_testing`. Disabled by default.
+
+{{< /history >}}
Use this API to interact with member roles for your GitLab.com groups or entire GitLab Self-Managed instance.
## Manage instance member roles
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
@@ -186,9 +196,12 @@ curl --request DELETE --header "Content-Type: application/json" --header "Author
## Manage group member roles
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Prerequisites:
@@ -275,7 +288,11 @@ Example response:
### Add a member role to a group
-> - Ability to add a name and description when creating a custom role [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126423) in GitLab 16.3.
+{{< history >}}
+
+- Ability to add a name and description when creating a custom role [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126423) in GitLab 16.3.
+
+{{< /history >}}
Adds a member role to a group. You can only add member roles at the root level of the group.
diff --git a/doc/api/members.md b/doc/api/members.md
index f9e6ddbcb5e9ecf9e14c42deaae2ce6aa583fa31..ffb6ac9b2e09579f2b3178f23fbd3ca266aa9444 100644
--- a/doc/api/members.md
+++ b/doc/api/members.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group and project members API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with group and project members.
@@ -113,9 +116,13 @@ Example response:
## List all members of a group or project including inherited and invited members
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to return members of the invited private group if the current user is a member of the shared group or project in GitLab 16.10 [with a flag](../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
-> - Feature flag `webui_members_inherited_users` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
-> - Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to return members of the invited private group if the current user is a member of the shared group or project in GitLab 16.10 [with a flag](../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
+- Feature flag `webui_members_inherited_users` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
+- Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+
+{{< /history >}}
Gets a list of group or project members viewable by the authenticated user, including inherited members, invited users, and permissions through ancestor groups.
@@ -129,11 +136,14 @@ Members from an invited group are returned if either:
- The requester is also a member of the invited group.
- The requester is a member of the shared group or project.
-NOTE:
+{{< alert type="note" >}}
+
The invited group members have shared membership in the shared group or project.
This means that if the requester is a member of a shared group or project, but not a member of an invited private group,
then using this endpoint the requester can get all the shared group or project members, including the invited private group members.
+{{< /alert >}}
+
This function takes pagination parameters `page` and `per_page` to restrict the list of users.
```plaintext
@@ -277,18 +287,25 @@ Example response:
## Get a member of a group or project, including inherited and invited members
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17744) in GitLab 12.4.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to return members of the invited private group if the current user is a member of the shared group or project in GitLab 16.10 [with a flag](../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
-> - Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17744) in GitLab 12.4.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to return members of the invited private group if the current user is a member of the shared group or project in GitLab 16.10 [with a flag](../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
+- Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+
+{{< /history >}}
Gets a member of a group or project, including members inherited or invited through ancestor groups. See the corresponding [endpoint to list all inherited members](#list-all-members-of-a-group-or-project-including-inherited-and-invited-members) for details.
-NOTE:
+{{< alert type="note" >}}
+
The invited group members have shared membership in the shared group or project.
This means that if the requester is a member of a shared group or project, but not a member of an invited private group,
then using this endpoint the requester can get all the shared group or project members, including the invited private group members.
+{{< /alert >}}
+
```plaintext
GET /groups/:id/members/all/:user_id
GET /projects/:id/members/all/:user_id
@@ -487,10 +504,17 @@ Example response:
## List indirect memberships for a billable member of a group
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386583) in GitLab 16.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386583) in GitLab 16.11.
+
+{{< /history >}}
Gets a list of indirect memberships for a billable member of a group.
@@ -541,7 +565,11 @@ Example response:
## Remove a billable member from a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217851) in GitLab 13.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217851) in GitLab 13.10.
+
+{{< /history >}}
Removes a billable member from a group and its subgroups and projects.
@@ -549,10 +577,13 @@ The user does not need to be a group member to qualify for removal.
For example, if the user was added directly to a project in the group, you can
still use this API to remove them.
-NOTE:
+{{< alert type="note" >}}
+
Member removal is handled asynchronously, so the changes complete within a few minutes.
Asynchronous removal is being rolled out, and may not become available to all groups at the same time.
+{{< /alert >}}
+
```plaintext
DELETE /groups/:id/billable_members/:user_id
```
@@ -569,7 +600,11 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
## Change membership state of a user in a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86705) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86705) in GitLab 15.0.
+
+{{< /history >}}
Changes the membership state of a user in a group.
@@ -652,9 +687,12 @@ Example response:
}
```
-NOTE:
+{{< alert type="note" >}}
+
If [administrator approval for role promotions](../administration/settings/sign_up_restrictions.md#turn-on-administrator-approval-for-role-promotions) is turned on, membership requests that promote existing users into a billable role require administrator approval.
+{{< /alert >}}
+
To enable **Manage Non-Billable Promotions**,
you must first enable the `enable_member_promotion_management` application setting.
@@ -744,9 +782,12 @@ Example response:
}
```
-NOTE:
+{{< alert type="note" >}}
+
If [administrator approval for role promotions](../administration/settings/sign_up_restrictions.md#turn-on-administrator-approval-for-role-promotions) is turned on, membership requests that promote existing users into a billable role require administrator approval.
+{{< /alert >}}
+
To enable **Manage non-billable promotions**,
you must first enable the `enable_member_promotion_management` application setting.
diff --git a/doc/api/merge_request_approval_settings.md b/doc/api/merge_request_approval_settings.md
index ea4e8e97f14699530b2531f90ba9f84b3df50737..8194bf51fafdcde35c7d35a4a01a0f31b3722fce 100644
--- a/doc/api/merge_request_approval_settings.md
+++ b/doc/api/merge_request_approval_settings.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Documentation for the REST API for merge request approval settings in GitLab."
+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
+description: Documentation for the REST API for merge request approval settings in GitLab.
title: Merge request approval settings API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Configuration for
[approval settings on all merge requests](../user/project/merge_requests/approvals/settings.md)
diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md
index 873ccbaaa549c35d83c0c930c0ea73453398b74a..53addb244659b26eb1f293cf1fce91ff71371420 100644
--- a/doc/api/merge_request_approvals.md
+++ b/doc/api/merge_request_approvals.md
@@ -1,16 +1,23 @@
---
stage: Create
group: Code Review
-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"
-description: "Documentation for the REST API for merge request approvals in GitLab."
+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
+description: Documentation for the REST API for merge request approvals in GitLab.
title: Merge request approvals API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Endpoint `/approvals` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Endpoint `/approvals` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0.
+
+{{< /history >}}
Configuration for
[approvals on all merge requests](../user/project/merge_requests/approvals/_index.md)
@@ -18,21 +25,35 @@ in the project. All endpoints require authentication.
## Group approval rules
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428051) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `approval_group_rules`. Disabled by default. This feature is an [experiment](../policy/development_stages_support.md).
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428051) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `approval_group_rules`. Disabled by default. This feature is an [experiment](../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `approval_group_rules`.
On GitLab.com and GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
+{{< /alert >}}
+
Group approval rules apply to all protected branches of projects belonging to the group. This feature is an [experiment](../policy/development_stages_support.md).
### Get group approval rules
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440638) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440638) in GitLab 16.10.
+
+{{< /history >}}
Group admins can request information about a group's approval rules using the following endpoint:
@@ -177,7 +198,11 @@ Example response:
### Update group approval rules
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440639) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440639) in GitLab 16.10.
+
+{{< /history >}}
Group admins can update group approval rules using the following endpoint:
@@ -319,10 +344,14 @@ Supported attributes:
### Get all approval rules for project
-> - Pagination support introduced in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `approval_rules_pagination`. Enabled by default. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/31011`
-> - `applies_to_all_protected_branches` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
-> - Pagination support [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366823) in GitLab 15.7. Feature flag `approval_rules_pagination` removed.
-> - `usernames` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8.
+{{< history >}}
+
+- Pagination support introduced in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `approval_rules_pagination`. Enabled by default. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/31011`
+- `applies_to_all_protected_branches` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
+- Pagination support [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366823) in GitLab 15.7. Feature flag `approval_rules_pagination` removed.
+- `usernames` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8.
+
+{{< /history >}}
You can request information about a project's approval rules using the following endpoint:
@@ -505,8 +534,12 @@ Supported attributes:
### Get single approval rule for project
-> - `applies_to_all_protected_branches` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
-> - `usernames` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8.
+{{< history >}}
+
+- `applies_to_all_protected_branches` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
+- `usernames` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8.
+
+{{< /history >}}
You can request information about a single project's approval rule using the following endpoint:
@@ -606,9 +639,13 @@ Supported attributes:
### Create project approval rule
-> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0.
-> - `applies_to_all_protected_branches` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
-> - `usernames` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8.
+{{< history >}}
+
+- [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0.
+- `applies_to_all_protected_branches` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
+- `usernames` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8.
+
+{{< /history >}}
You can create project approval rules using the following endpoint:
@@ -735,9 +772,13 @@ curl --request POST \
### Update project approval rule
-> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0.
-> - `applies_to_all_protected_branches` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
-> - `usernames` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8.
+{{< history >}}
+
+- [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0.
+- `applies_to_all_protected_branches` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3.
+- `usernames` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102446) in GitLab 15.8.
+
+{{< /history >}}
You can update project approval rules using the following endpoint:
@@ -745,13 +786,16 @@ You can update project approval rules using the following endpoint:
PUT /projects/:id/approval_rules/:approval_rule_id
```
-NOTE:
+{{< alert type="note" >}}
+
Approvers and groups (except hidden groups not in the `users` or `groups`
parameters) are **removed**. Hidden groups are private groups the user doesn't
have permission to view. Hidden groups are not removed by default unless the
`remove_hidden_groups` parameter is `true`. This ensures hidden groups are
not removed unintentionally when a user updates an approval rule.
+{{< /alert >}}
+
Supported attributes:
| Attribute | Type | Required | Description |
@@ -982,8 +1026,12 @@ Supported attributes:
### Get merge request approval rules
-> - Pagination support introduced in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `approval_rules_pagination`. Enabled by default. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/31011`
-> - Pagination support [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366823) in GitLab 15.7. Feature flag `approval_rules_pagination` removed.
+{{< history >}}
+
+- Pagination support introduced in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `approval_rules_pagination`. Enabled by default. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/31011`
+- Pagination support [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366823) in GitLab 15.7. Feature flag `approval_rules_pagination` removed.
+
+{{< /history >}}
You can request information about a merge request's approval rules using the following endpoint:
@@ -1213,10 +1261,13 @@ Supported attributes:
| `user_ids` | Array | No | The IDs of users as approvers. If you provide both `user_ids` and `usernames`, it adds both lists of users. |
| `usernames` | string array | No | The usernames of approvers for this rule (same as `user_ids` but requires a list of usernames). If you provide both `user_ids` and `usernames`, it adds both lists of users. |
-NOTE:
+{{< alert type="note" >}}
+
Setting `approval_project_rule_id` copies the `name`, `users` and
`groups` of the project's rule. It uses the `approvals_required` you specify.
+{{< /alert >}}
+
```json
{
"id": 1,
diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md
index 17e654e4d7eb3cd31f6af2b1382300449cadeb0a..90239ebf0b2a1343b52bc5da83049c9c1d437ed8 100644
--- a/doc/api/merge_request_context_commits.md
+++ b/doc/api/merge_request_context_commits.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Code Review
-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"
-description: "Documentation for the REST API for merge request context commits in GitLab."
+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
+description: Documentation for the REST API for merge request context commits in GitLab.
title: Merge request context commits API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If your merge request builds upon a previous merge request, you might
need to [include previously-merged commits for context](../user/project/merge_requests/commits.md#show-commits-from-previous-merge-requests).
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index c6d518df17eb5bf8be055ca1b7f7e9939089ccb0..caba7255fab6726409a518ad6eff6714a22761f1 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -2,21 +2,28 @@
stage: Create
group: Code Review
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
-description: "Documentation for the REST API for merge requests in GitLab."
+description: Documentation for the REST API for merge requests in GitLab.
title: Merge requests API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - `reference` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.7.
-> - `merged_by` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350534) in GitLab 14.7.
-> - `merge_status` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in favor of `detailed_merge_status` in GitLab 15.6.
-> - `with_merge_status_recheck` [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115948) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `restrict_merge_status_recheck` to be ignored for requests from users insufficient permissions. Disabled by default.
-> - `approvals_before_merge` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119503) in GitLab 16.0.
-> - `prepared_at` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122001) in GitLab 16.1.
-> - `merge_after` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165092) in GitLab 17.5.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- `reference` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.7.
+- `merged_by` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350534) in GitLab 14.7.
+- `merge_status` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in favor of `detailed_merge_status` in GitLab 15.6.
+- `with_merge_status_recheck` [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115948) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `restrict_merge_status_recheck` to be ignored for requests from users insufficient permissions. Disabled by default.
+- `approvals_before_merge` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119503) in GitLab 16.0.
+- `prepared_at` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122001) in GitLab 16.1.
+- `merge_after` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165092) in GitLab 17.5.
+
+{{< /history >}}
All API calls to non-public information require authentication.
@@ -890,8 +897,12 @@ to get the updated status. This affects the `has_conflicts` property, as it depe
### Merge status
-> - `merge_status` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in GitLab 15.6.
-> - `detailed_merge_status` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101724) in GitLab 15.6.
+{{< history >}}
+
+- `merge_status` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in GitLab 15.6.
+- `detailed_merge_status` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101724) in GitLab 15.6.
+
+{{< /history >}}
Use `detailed_merge_status` instead of `merge_status` to account for all potential statuses.
@@ -1104,10 +1115,13 @@ Example response:
Shows information about the merge request dependencies that must be resolved before merging.
-NOTE:
+{{< alert type="note" >}}
+
If the user does not have access to the blocking merge request, no `blocking_merge_request`
attribute is returned.
+{{< /alert >}}
+
```plaintext
GET /projects/:id/merge_requests/:merge_request_iid/blocks
```
@@ -1737,11 +1751,14 @@ Example response:
## Get single merge request changes
-WARNING:
+{{< alert type="warning" >}}
+
This endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/322117) in GitLab 15.7
and [is scheduled for removal](rest/deprecations.md) in API v5. Use the
[List merge request diffs](#list-merge-request-diffs) endpoint instead.
+{{< /alert >}}
+
Shows information about the merge request including its files and changes.
```plaintext
@@ -1876,9 +1893,13 @@ Example response:
## List merge request diffs
-> - `generated_file` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141576) in GitLab 16.9 [with a flag](../administration/feature_flags.md) named `collapse_generated_diff_files`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/432670) in GitLab 16.10.
-> - `generated_file` [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148478) in GitLab 16.11. Feature flag `collapse_generated_diff_files` removed.
+{{< history >}}
+
+- `generated_file` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141576) in GitLab 16.9 [with a flag](../administration/feature_flags.md) named `collapse_generated_diff_files`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/432670) in GitLab 16.10.
+- `generated_file` [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148478) in GitLab 16.11. Feature flag `collapse_generated_diff_files` removed.
+
+{{< /history >}}
List diffs of the files changed in a merge request.
@@ -1947,10 +1968,13 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
This endpoint is subject to [Merge requests diff limits](../administration/instance_limits.md#diff-limits).
Merge requests that exceed the diff limits return limited results.
+{{< /alert >}}
+
## Show merge request raw diffs
Show raw diffs of the files changed in a merge request.
@@ -2008,10 +2032,13 @@ index e02d9eea1852f19fe5311acda6aa17465eeb422e..f32b38585398a18fea75c11d7b8ebb73
before { authenticate_non_get! }
```
-NOTE:
+{{< alert type="note" >}}
+
This endpoint is subject to [Merge requests diff limits](../administration/instance_limits.md#diff-limits).
Merge requests that exceed the diff limits return limited results.
+{{< /alert >}}
+
## List merge request pipelines
Get a list of merge request pipelines.
diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md
index 9314447f78ee326cfd7cf9e3fcbc9bc1a5d29f6c..d24ab144778fd0db2798be67dccb8e80c18c8d5a 100644
--- a/doc/api/merge_trains.md
+++ b/doc/api/merge_trains.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Merge Trains API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every API call for [merge train](../ci/pipelines/merge_trains.md) must be authenticated with at least the Developer [role](../user/permissions.md).
diff --git a/doc/api/metadata.md b/doc/api/metadata.md
index 558263b04f94dc311d92248702db29b16bc98af5..21005912b0669cfd205c0a7ecb56afce9be48be2 100644
--- a/doc/api/metadata.md
+++ b/doc/api/metadata.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Metadata API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357032) in GitLab 15.2.
-> - `enterprise` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103969) in GitLab 15.6.
-> - `kas.externalK8sProxyUrl` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172373) in GitLab 17.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357032) in GitLab 15.2.
+- `enterprise` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103969) in GitLab 15.6.
+- `kas.externalK8sProxyUrl` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172373) in GitLab 17.6.
+
+{{< /history >}}
Retrieve metadata information for this GitLab instance.
diff --git a/doc/api/milestones.md b/doc/api/milestones.md
index 7c45934030853d88032b3e23c2522c89d43ca042..fc444e2262918bfa83624ae1ce099a68b4b6e50d 100644
--- a/doc/api/milestones.md
+++ b/doc/api/milestones.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project milestones API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use project [milestones](../user/project/milestones/_index.md) with the REST API.
There's a separate [group milestones API](group_milestones.md) page.
@@ -121,8 +124,12 @@ Parameters:
## Delete project milestone
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Only for users with at least the Planner role for the project.
@@ -169,8 +176,12 @@ Parameters:
## Promote project milestone to a group milestone
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Only for users with at least the Planner role for the group.
@@ -187,9 +198,12 @@ Parameters:
## Get all burndown chart events for a single milestone
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Gets all burndown chart events for a single milestone.
diff --git a/doc/api/model_registry.md b/doc/api/model_registry.md
index cef0a0cf824ede8fc2988ff28cee725371cdc12e..8855b83ebefbb9c2cffe04e3ed50e14352871806 100644
--- a/doc/api/model_registry.md
+++ b/doc/api/model_registry.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Model registry API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Download a machine learning model package
diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md
index ae3a11e59a097c5f148647dd8906176c21a7b7a8..4428476561a5a218613b43448a87a56878ac50af 100644
--- a/doc/api/namespaces.md
+++ b/doc/api/namespaces.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Namespaces API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with namespaces, a special resource category used to organize users and groups. For more information, see [Namespaces](../user/namespace/_index.md).
@@ -15,7 +18,11 @@ This API uses [Pagination](rest/_index.md#pagination) to filter results.
## List all namespaces
-> - `top_level_only` [introduced](https://gitlab.com/gitlab-org/customers-gitlab-com/-/issues/7600) in GitLab 16.8.
+{{< history >}}
+
+- `top_level_only` [introduced](https://gitlab.com/gitlab-org/customers-gitlab-com/-/issues/7600) in GitLab 16.8.
+
+{{< /history >}}
Lists all namespaces available to the current user. If the user is an
administrator, this endpoint returns all namespaces in the instance.
diff --git a/doc/api/notes.md b/doc/api/notes.md
index 57c8febac03c57ea7362571b3f48005c87bb731e..cabc034d6eda3386dd2612aa5b53ddc63d726c56 100644
--- a/doc/api/notes.md
+++ b/doc/api/notes.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Notes API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Notes are comments on:
@@ -495,26 +498,35 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
## Epics
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0
and is planned for removal in v5 of the API.
In GitLab 17.4 or later, if your administrator [enabled the new look for epics](../user/group/epics/epic_work_items.md), use the
[Work Items API](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/) instead. For more information, see the [guide how to migrate your existing APIs](graphql/epic_work_items_api_migration_guide.md).
This change is a breaking change.
+{{< /alert >}}
+
### List all epic notes
Gets a list of all notes for a single epic. Epic notes are comments users can post to an epic.
-NOTE:
+{{< alert type="note" >}}
+
The epics notes API uses the epic ID instead of epic IID. If you use the epic's IID, GitLab returns either a 404
error or notes for the wrong epic. It's different from the [issue notes API](#issues) and
[merge requests notes API](#merge-requests).
+{{< /alert >}}
+
```plaintext
GET /groups/:id/epics/:epic_id/notes
GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at
diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md
index a28e1258862ededb36138ce38aa26944a13e2e3e..5fbd4382ebc5158cf11e81ffc9914ee6dd2c862b 100644
--- a/doc/api/notification_settings.md
+++ b/doc/api/notification_settings.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Notification settings API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Change [notification settings](../user/profile/notifications.md) using the REST API.
diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md
index e88fffe21a4b1c3421f17c3a8c0fc0b4a3f31dd0..87390b39be6b7018fc7e96785f4ae8c579c1379c 100644
--- a/doc/api/oauth2.md
+++ b/doc/api/oauth2.md
@@ -1,14 +1,17 @@
---
stage: Software Supply Chain Security
group: Authentication
-description: Third-party authorization to GitLab.
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
+description: Third-party authorization to GitLab.
title: OAuth 2.0 identity provider API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to allow third-party services to access GitLab resources for a user
with the [OAuth 2.0](https://oauth.net/2/) protocol.
@@ -18,7 +21,11 @@ This functionality is based on the [doorkeeper Ruby gem](https://github.com/door
## Cross-origin resource sharing
-> - CORS preflight request support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364680) in GitLab 15.1.
+{{< history >}}
+
+- CORS preflight request support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364680) in GitLab 15.1.
+
+{{< /history >}}
Many `/oauth` endpoints support cross-origin resource sharing (CORS). From GitLab 15.1, the following endpoints also
support [CORS preflight requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS):
@@ -170,18 +177,24 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD
}
```
-NOTE:
+{{< alert type="note" >}}
+
The `redirect_uri` must match the `redirect_uri` used in the original
authorization request.
+{{< /alert >}}
+
You can now make requests to the API with the access token.
### Authorization code flow
-NOTE:
+{{< alert type="note" >}}
+
Check the [RFC spec](https://www.rfc-editor.org/rfc/rfc6749#section-4.1) for a
detailed flow description.
+{{< /alert >}}
+
The authorization code flow is essentially the same as
[authorization code flow with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce),
@@ -250,22 +263,32 @@ be used as a CSRF token.
}
```
-NOTE:
+{{< alert type="note" >}}
+
The `redirect_uri` must match the `redirect_uri` used in the original
authorization request.
+{{< /alert >}}
+
You can now make requests to the API with the access token returned.
### Device authorization grant flow
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332682) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `oauth2_device_grant_flow`.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/468479) by default in 17.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/505557) in GitLab 17.9. Feature flag `oauth2_device_grant_flow` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332682) in GitLab 17.2 [with a flag](../administration/feature_flags.md) named `oauth2_device_grant_flow`.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/468479) by default in 17.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/505557) in GitLab 17.9. Feature flag `oauth2_device_grant_flow` removed.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
Check the [RFC spec](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1) for a detailed
description of the device authorization grant flow, from device authorization request to token response from the browser login.
+{{< /alert >}}
+
The device authorization grant flow makes it possible to securely authenticate your GitLab identity from input constrained devices where browser interactions are not an option.
This makes the device authorization grant flow ideal for users attempting to use GitLab services from headless servers or other devices with no, or limited, UI.
@@ -379,19 +402,26 @@ A sample application that implements the client side device flow can be found at
### Resource owner password credentials flow
-NOTE:
+{{< alert type="note" >}}
+
Check the [RFC spec](https://www.rfc-editor.org/rfc/rfc6749#section-4.3) for a
detailed flow description.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The Resource Owner Password Credentials is disabled for users with
[two-factor authentication](../user/profile/account/two_factor_authentication.md) turned on.
These users can access the API using [personal access tokens](../user/profile/personal_access_tokens.md)
instead.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
Ensure the [**Allow password authentication for Git over HTTP(S)**](../administration/settings/sign_in_restrictions.md#password-authentication-enabled)
checkbox is selected for the GitLab instance to support the password credentials flow.
+{{< /alert >}}
In this flow, a token is requested in exchange for the resource owner credentials
(username and password).
@@ -403,12 +433,15 @@ The credentials should only be used when:
privileged application.
- Other authorization grant types are not available (such as an authorization code).
-WARNING:
+{{< alert type="warning" >}}
+
Never store the user's credentials and only use this grant type when your client
is deployed to a trusted environment, in 99% of cases
[personal access tokens](../user/profile/personal_access_tokens.md) are a better
choice.
+{{< /alert >}}
+
Even though this grant type requires direct client access to the resource owner
credentials, the resource owner credentials are used for a single request and
are exchanged for an access token. This grant type can eliminate the need for
diff --git a/doc/api/organizations.md b/doc/api/organizations.md
index a0118a83a1e2e2cbba5b8347b51ddd2cbfc74a10..97ca433906ec31866d27429721c2fb7ce282bc40 100644
--- a/doc/api/organizations.md
+++ b/doc/api/organizations.md
@@ -5,19 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Organizations API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
## Create organization
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/470613) in GitLab 17.5 with a [flag](../administration/feature_flags.md) named `allow_organization_creation`. Disabled by default. This feature is an [experiment](../policy/development_stages_support.md).
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/470613) in GitLab 17.5 with a [flag](../administration/feature_flags.md) named `allow_organization_creation`. Disabled by default. This feature is an [experiment](../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Creates a new organization.
This endpoint is an [experiment](../policy/development_stages_support.md) and might be changed or removed without notice.
diff --git a/doc/api/packages.md b/doc/api/packages.md
index eaa2da09bfbd9510dd6179020320d851cd1e78bf..dcbca62da2f792b8524229d1e77501d74b6224e6 100644
--- a/doc/api/packages.md
+++ b/doc/api/packages.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Packages API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349418) support for [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) authentication for the project-level API in GitLab 15.3.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349418) support for [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) authentication for the project-level API in GitLab 15.3.
+
+{{< /history >}}
The API documentation of [GitLab Packages](../administration/packages/_index.md).
@@ -337,7 +344,11 @@ By default, the `GET` request returns 20 results, because the API is [paginated]
## List package pipelines
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341950) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341950) in GitLab 16.1.
+
+{{< /history >}}
Get a list of pipelines for a single package. The results are sorted by `id` in descending order.
@@ -430,10 +441,13 @@ deleting a package can introduce a [dependency confusion risk](../user/packages/
## Delete a package file
-WARNING:
+{{< alert type="warning" >}}
+
Deleting a package file may corrupt your package making it unusable or unpullable from your package
manager client. When deleting a package file, be sure that you understand what you're doing.
+{{< /alert >}}
+
Delete a package file:
```plaintext
diff --git a/doc/api/packages/composer.md b/doc/api/packages/composer.md
index 349c6d133b9af492abfa35691ccf2067a8e84ce6..528c4527c28431c2ccfbf7babc7a94ef1b965446 100644
--- a/doc/api/packages/composer.md
+++ b/doc/api/packages/composer.md
@@ -5,24 +5,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Composer API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for [Composer Packages](../../user/packages/composer_repository/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the [Composer package manager client](https://getcomposer.org/)
and is generally not meant for manual consumption.
+{{< /alert >}}
+
For instructions on how to upload and install Composer packages from the GitLab
package registry, see the [Composer package registry documentation](../../user/packages/composer_repository/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See the [Composer Package Registry documentation](../../user/packages/composer_repository/_index.md)
for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.
+{{< /alert >}}
+
## Base repository request
Returns the repository URL templates for requesting individual packages:
diff --git a/doc/api/packages/conan.md b/doc/api/packages/conan.md
index 7a68698fe0ccf2717c31ba9e03acbf71002cf489..78a69188ef53ab50c5789822e477e732e710f7de 100644
--- a/doc/api/packages/conan.md
+++ b/doc/api/packages/conan.md
@@ -5,26 +5,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Conan API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for [Conan Packages](../../user/packages/conan_repository/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the [Conan package manager client](https://docs.conan.io/en/latest/)
and is generally not meant for manual consumption.
+{{< /alert >}}
+
For instructions on how to upload and install Conan packages from the GitLab
package registry, see the [Conan package registry documentation](../../user/packages/conan_repository/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See each route for details on how credentials are expected to be passed. Undocumented authentication methods might be removed in the future.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The Conan registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_gitlab.md) is enabled.
These endpoints will all return 404 Not Found.
+{{< /alert >}}
## Route prefix
diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md
index bdba2cf00fb90f56ee3818af20e914cf76f04bde..df682f5df162ac21538c786c2f82bff1b1e9b348 100644
--- a/doc/api/packages/debian.md
+++ b/doc/api/packages/debian.md
@@ -5,28 +5,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Debian API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
This is the API documentation for [Debian](../../user/packages/debian_repository/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the Debian related package clients such as [dput](https://manpages.debian.org/stable/dput-ng/dput.1.en.html)
and [apt-get](https://manpages.debian.org/stable/apt/apt-get.8.en.html),
and is generally not meant for manual consumption. This API is under development and is not ready
for production use due to limited functionality.
+{{< /alert >}}
+
For instructions on how to upload and install Debian packages from the GitLab
package registry, see the [Debian registry documentation](../../user/packages/debian_repository/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See the [Debian registry documentation](../../user/packages/debian_repository/_index.md)
for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.
+{{< /alert >}}
+
## Enable the Debian API
The Debian API is behind a feature flag that is disabled by default.
@@ -47,7 +56,11 @@ See [Authenticate to the Debian Package Repositories](../../user/packages/debian
## Upload a package file
-> - Upload with explicit distribution and component [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101838) in GitLab 15.9.
+{{< history >}}
+
+- Upload with explicit distribution and component [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101838) in GitLab 15.9.
+
+{{< /history >}}
Upload a Debian package file:
@@ -246,7 +259,11 @@ This writes the downloaded file using the remote filename in the current directo
## Download a packages index by hash
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96947) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96947) in GitLab 15.4.
+
+{{< /history >}}
Download a packages index by hash.
@@ -277,7 +294,11 @@ This writes the downloaded file using the remote filename in the current directo
## Download a Debian Installer packages index
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71918) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71918) in GitLab 15.4.
+
+{{< /history >}}
Download a Debian Installer packages index.
@@ -307,7 +328,11 @@ This writes the downloaded file using the remote filename in the current directo
## Download a Debian Installer packages index by hash
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96947) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96947) in GitLab 15.4.
+
+{{< /history >}}
Download a Debian Installer packages index by hash.
@@ -337,7 +362,11 @@ This writes the downloaded file using the remote filename in the current directo
## Download a source packages index
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71918) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71918) in GitLab 15.4.
+
+{{< /history >}}
Download a source packages index.
@@ -366,7 +395,11 @@ This writes the downloaded file using the remote filename in the current directo
## Download a source packages index by hash
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96947) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96947) in GitLab 15.4.
+
+{{< /history >}}
Download a source packages index by hash.
diff --git a/doc/api/packages/debian_group_distributions.md b/doc/api/packages/debian_group_distributions.md
index 1ef4b8d6376a20e42be7595ad27ade68dd5a0da6..24d38f75e53b795889b787b7b149f457bb906871 100644
--- a/doc/api/packages/debian_group_distributions.md
+++ b/doc/api/packages/debian_group_distributions.md
@@ -5,18 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Debian group distributions API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
This is the reference documentation for the Debian group distributions API. This API is behind a
feature flag that is disabled by default. To use this API, you must [enable it](#enable-the-debian-group-api).
-WARNING:
+{{< alert type="warning" >}}
+
This API is under development and is not meant for production use.
+{{< /alert >}}
+
For more information about working with Debian packages, see the
[Debian package registry documentation](../../user/packages/debian_repository/_index.md).
diff --git a/doc/api/packages/debian_project_distributions.md b/doc/api/packages/debian_project_distributions.md
index 8ad6338a9c361dc1296c51f13d3c57fd4b9b43c6..b29fa4a0ede8bdae29150d3d51f555f4c6d9402e 100644
--- a/doc/api/packages/debian_project_distributions.md
+++ b/doc/api/packages/debian_project_distributions.md
@@ -5,18 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Debian project distributions API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
This is the reference documentation for the Debian project distributions API. This API is behind a
feature flag that is disabled by default. To use this API, you must [enable the Debian API](#enable-the-debian-api).
-WARNING:
+{{< alert type="warning" >}}
+
This API is under development and is not meant for production use.
+{{< /alert >}}
+
For more information about working with Debian packages, see the
[Debian package registry documentation](../../user/packages/debian_repository/_index.md).
diff --git a/doc/api/packages/go_proxy.md b/doc/api/packages/go_proxy.md
index 2208849f6465b1f839129432f9dc1ac9d10a967b..64332827c504cdbd8ca02fb2e74aa18d77ad2dd1 100644
--- a/doc/api/packages/go_proxy.md
+++ b/doc/api/packages/go_proxy.md
@@ -5,26 +5,35 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Go Proxy API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for [Go Packages](../../user/packages/go_proxy/_index.md).
This API is behind a feature flag that is disabled by default. GitLab administrators with access to
the GitLab Rails console can [enable](../../administration/feature_flags.md)
this API for your GitLab instance.
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the [Go client](https://maven.apache.org/)
and is generally not meant for manual consumption.
+{{< /alert >}}
+
For instructions on how to work with the Go Proxy, see the [Go Proxy package documentation](../../user/packages/go_proxy/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See the [Go Proxy package documentation](../../user/packages/go_proxy/_index.md)
for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.
+{{< /alert >}}
+
## List
Get all tagged versions for a given Go module:
diff --git a/doc/api/packages/helm.md b/doc/api/packages/helm.md
index 106615648cac36ebcc74c1f7ca7fa95b27a07071..f04af8fc2547e4d347f1c03745e9d1a6f0c44438 100644
--- a/doc/api/packages/helm.md
+++ b/doc/api/packages/helm.md
@@ -5,25 +5,34 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Helm API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for [Helm](../../user/packages/helm_repository/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the Helm-related package clients such as [Helm](https://helm.sh/)
and [`helm-push`](https://github.com/chartmuseum/helm-push/#readme),
and is generally not meant for manual consumption.
+{{< /alert >}}
+
For instructions on how to upload and install Helm packages from the GitLab
Package Registry, see the [Helm registry documentation](../../user/packages/helm_repository/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See the [Helm registry documentation](../../user/packages/helm_repository/_index.md)
for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.
+{{< /alert >}}
+
## Download a chart index
Download a chart index:
diff --git a/doc/api/packages/maven.md b/doc/api/packages/maven.md
index 23cd54f3fa3b81401ffa850d4e294f776a1f4530..890eb03a544cede637655ddec2bce2c850203cea 100644
--- a/doc/api/packages/maven.md
+++ b/doc/api/packages/maven.md
@@ -5,24 +5,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Maven API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for [Maven Packages](../../user/packages/maven_repository/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the [Maven package manager client](https://maven.apache.org/)
and is generally not meant for manual consumption.
+{{< /alert >}}
+
For instructions on how to upload and install Maven packages from the GitLab
package registry, see the [Maven package registry documentation](../../user/packages/maven_repository/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See [Maven package registry documentation](../../user/packages/maven_repository/_index.md)
for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.
+{{< /alert >}}
+
## Download a package file at the instance-level
Download a Maven package file:
diff --git a/doc/api/packages/npm.md b/doc/api/packages/npm.md
index 588de76515fa337a30086894958c05a836ca0492..40cd68c96583c14a3671f63d9c93a30339ace000 100644
--- a/doc/api/packages/npm.md
+++ b/doc/api/packages/npm.md
@@ -5,24 +5,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: npm API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for [npm Packages](../../user/packages/npm_registry/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the [npm package manager client](https://docs.npmjs.com/)
and is not meant for manual consumption.
+{{< /alert >}}
+
For instructions on how to upload and install npm packages from the GitLab
Package Registry, see the [npm package registry documentation](../../user/packages/npm_registry/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See the [npm package registry documentation](../../user/packages/npm_registry/_index.md)
for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.
+{{< /alert >}}
+
## Download a package
Downloads the npm package. This URL is provided by the [metadata endpoint](#metadata).
@@ -153,8 +162,12 @@ The examples in this document all use the project-level prefix.
### Group-level
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299834) in GitLab 16.0 [with a flag](../../administration/feature_flags.md) named `npm_group_level_endpoints`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121837) in GitLab 16.1. Feature flag `npm_group_level_endpoints` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299834) in GitLab 16.0 [with a flag](../../administration/feature_flags.md) named `npm_group_level_endpoints`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121837) in GitLab 16.1. Feature flag `npm_group_level_endpoints` removed.
+
+{{< /history >}}
```plaintext
/groups/:id/-/packages/npm
diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md
index 4342f7590fc072fa0a583ec80ab9635a1e7ba24e..c7be3d4852d4c6de4439e2daa0ec8d90cb1c12a1 100644
--- a/doc/api/packages/nuget.md
+++ b/doc/api/packages/nuget.md
@@ -5,24 +5,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: NuGet API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for [NuGet Packages](../../user/packages/nuget_repository/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the [NuGet package manager client](https://www.nuget.org/)
and is generally not meant for manual consumption.
+{{< /alert >}}
+
For instructions on how to upload and install NuGet packages from the GitLab
Package Registry, see the [NuGet package registry documentation](../../user/packages/nuget_repository/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See the [NuGet package registry documentation](../../user/packages/nuget_repository/_index.md)
for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.
+{{< /alert >}}
+
## Package index
Returns the index for a given package, which includes a list of available versions:
@@ -79,7 +88,11 @@ This writes the downloaded file to `MyNuGetPkg.1.3.0.17.nupkg` in the current di
## Upload a package file
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416404) in GitLab 16.2 for NuGet v2 feed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416404) in GitLab 16.2 for NuGet v2 feed.
+
+{{< /history >}}
Upload a NuGet package file:
@@ -205,7 +218,11 @@ Example response:
### V3 source feed/protocol
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/214674) to be public in GitLab 16.1.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/214674) to be public in GitLab 16.1.
+
+{{< /history >}}
Returns a list of available API resources.
Authentication is not required:
@@ -416,7 +433,11 @@ Example response:
## Delete service
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38275) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38275) in GitLab 16.5.
+
+{{< /history >}}
Delete a NuGet package:
@@ -447,7 +468,11 @@ Possible request responses:
## Download a debugging symbol file `.pdb`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416178) in GitLab 16.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416178) in GitLab 16.7.
+
+{{< /history >}}
Download a debugging symbol file (`.pdb`):
@@ -482,7 +507,11 @@ Possible request responses:
## V2 Feed Metadata Endpoints
-> - Introduced in GitLab 16.3.
+{{< history >}}
+
+- Introduced in GitLab 16.3.
+
+{{< /history >}}
### $metadata endpoint
@@ -535,7 +564,11 @@ Example response:
### OData package entry endpoints
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127667) in GitLab 16.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127667) in GitLab 16.4.
+
+{{< /history >}}
| Endpoint | Description |
| -------- | ----------- |
@@ -561,12 +594,15 @@ Example response:
</entry>
```
-NOTE:
+{{< alert type="note" >}}
+
GitLab doesn't receive an authentication token for the `Packages()` and
`FindPackagesByID()` endpoints, so the latest version of the package
cannot be returned. You must provide the version when you install
or upgrade a package with the NuGet v2 feed.
+{{< /alert >}}
+
```shell
curl "https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2/Packages()?$filter=(tolower(Id) eq 'mynugetpkg')"
```
diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md
index 33a3ae0e238f0f658ad0006f7442732525a7b1c9..d07d329dac63f3ae08e096bc53ef153b9cd89c90 100644
--- a/doc/api/packages/pypi.md
+++ b/doc/api/packages/pypi.md
@@ -5,27 +5,38 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: PyPI API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for [PyPI Packages](../../user/packages/pypi_repository/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the [PyPI package manager client](https://pypi.org/)
and is generally not meant for manual consumption.
+{{< /alert >}}
+
For instructions on how to upload and install PyPI packages from the GitLab
Package Registry, see the [PyPI package registry documentation](../../user/packages/pypi_repository/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See the [PyPI package registry documentation](../../user/packages/pypi_repository/_index.md)
for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
[Twine 3.4.2](https://twine.readthedocs.io/en/stable/changelog.html?highlight=FIPS#id28) or greater
is recommended when [FIPS mode](../../development/fips_gitlab.md) is enabled.
+{{< /alert >}}
## Download a package file from a group
@@ -57,7 +68,11 @@ directory.
## Group-level simple API index
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327595) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327595) in GitLab 15.1.
+
+{{< /history >}}
Returns a list of packages in the group as an HTML file:
@@ -166,7 +181,11 @@ directory.
## Project-level simple API index
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327595) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327595) in GitLab 15.1.
+
+{{< /history >}}
Returns a list of packages in the project as an HTML file:
diff --git a/doc/api/packages/rubygems.md b/doc/api/packages/rubygems.md
index 4eee7db705240b3ae4c96339d9f60d76d3781d92..83224d43333eff68b31455fb3e45100303a8f705 100644
--- a/doc/api/packages/rubygems.md
+++ b/doc/api/packages/rubygems.md
@@ -5,25 +5,34 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Ruby gems API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for [Ruby gems](../../user/packages/rubygems_registry/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the [Ruby gems and Bundler package manager clients](https://maven.apache.org/)
and is generally not meant for manual consumption. This API is under development and is not ready
for production use due to limited functionality.
+{{< /alert >}}
+
For instructions on how to upload and install gems from the GitLab
package registry, see the [Ruby gems registry documentation](../../user/packages/rubygems_registry/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
These endpoints do not adhere to the standard API authentication methods.
See the [Ruby gems registry documentation](../../user/packages/rubygems_registry/_index.md)
for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.
+{{< /alert >}}
+
## Enable the Ruby gems API
The Ruby gems API for GitLab is behind a feature flag that is disabled by default. GitLab
diff --git a/doc/api/packages/terraform-modules.md b/doc/api/packages/terraform-modules.md
index b99da82ff493f2921aeef9fe22b82a19502d514a..7cb87b9529285614829c006021ac85726070c5a1 100644
--- a/doc/api/packages/terraform-modules.md
+++ b/doc/api/packages/terraform-modules.md
@@ -5,16 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Terraform Module Registry API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This is the API documentation for the [Terraform Module Registry](../../user/packages/terraform_module_registry/_index.md).
-WARNING:
+{{< alert type="warning" >}}
+
This API is used by the [Terraform CLI](https://www.terraform.io/)
and is generally not meant for manual consumption. Undocumented authentication methods might be removed in the future.
+{{< /alert >}}
+
For instructions on how to upload and install Terraform modules from the GitLab
Terraform Module Registry, see the [Terraform Module Registry documentation](../../user/packages/terraform_module_registry/_index.md).
diff --git a/doc/api/pages.md b/doc/api/pages.md
index efd7e593dd26b63e201d2eeec70ebac7a9483bc0..cb768e9fa9856a9e19ebce10d4007f3e86960a03 100644
--- a/doc/api/pages.md
+++ b/doc/api/pages.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pages API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Endpoints for managing [GitLab Pages](../user/project/pages/_index.md).
@@ -15,7 +18,11 @@ The GitLab Pages feature must be enabled to use these endpoints. Find out more a
## Unpublish Pages
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/498658) the minimum required role from administrator access to the Maintainer role in GitLab 17.9
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/498658) the minimum required role from administrator access to the Maintainer role in GitLab 17.9
+
+{{< /history >}}
Prerequisites:
@@ -37,7 +44,11 @@ curl --request 'DELETE' --header "PRIVATE-TOKEN: <your_access_token>" "https://g
## Get Pages settings for a project
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436932) in GitLab 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436932) in GitLab 16.8.
+
+{{< /history >}}
Prerequisites:
@@ -106,8 +117,12 @@ Example response:
## Update Pages settings for a project
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147227) in GitLab 17.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/498658) the minimum required role from administrator access to the Maintainer role in GitLab 17.9
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147227) in GitLab 17.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/498658) the minimum required role from administrator access to the Maintainer role in GitLab 17.9
+
+{{< /history >}}
Prerequisites:
diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md
index 31c5a79577300c775ab32c578a7a8aaa1253fb39..9a68456efc9c98574a3b5ea7bec5790b2fdd2964 100644
--- a/doc/api/pages_domains.md
+++ b/doc/api/pages_domains.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pages domains API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
Endpoints for connecting custom domains and TLS certificates in [GitLab Pages](../user/project/pages/_index.md).
@@ -371,7 +374,11 @@ Example response:
## Verify Pages domain
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21261) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21261) in GitLab 17.7.
+
+{{< /history >}}
Verifies an existing project Pages domain.
The user must have permissions to update Pages domains.
diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md
index 6690ae04bacf1d1fec9e41ffdc71383ee19af029..77eb00c8059de02fc24a8f0052ed815a06d6bf36 100644
--- a/doc/api/personal_access_tokens.md
+++ b/doc/api/personal_access_tokens.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Personal access tokens API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with personal access tokens. For more information, see [Personal access tokens](../user/profile/personal_access_tokens.md).
## List all personal access tokens
-> - `created_after`, `created_before`, `last_used_after`, `last_used_before`, `revoked`, `search` and `state` filters were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362248) in GitLab 15.5.
+{{< history >}}
+
+- `created_after`, `created_before`, `last_used_after`, `last_used_before`, `revoked`, `search` and `state` filters were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362248) in GitLab 15.5.
+
+{{< /history >}}
Lists all personal access tokens accessible by the authenticating user. For administrators, returns
a list of all personal access tokens in the instance. For non-administrators, returns a list of the
@@ -81,8 +88,12 @@ Other possible response:
## Get details on a personal access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362239) in GitLab 15.1.
-> - `404` HTTP status code [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93650) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362239) in GitLab 15.1.
+- `404` HTTP status code [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93650) in GitLab 15.3.
+
+{{< /history >}}
Gets details on a specified personal access token. Administrators can get details on any token.
Non-administrators can only get details on own tokens.
@@ -112,7 +123,11 @@ Other possible responses:
### Self-inform
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373999) in GitLab 15.5
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373999) in GitLab 15.5
+
+{{< /history >}}
Instead of getting details on a specific personal access token, you can also return details on
the personal access token you used to authenticate the request. To return these details, you must
@@ -126,8 +141,11 @@ curl --request GET \
## Create a personal access token
-DETAILS:
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can create personal access tokens with the user tokens API. For more information, see the following endpoints:
@@ -136,8 +154,12 @@ You can create personal access tokens with the user tokens API. For more informa
## Rotate a personal access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403042) in GitLab 16.0
-> - `expires_at` attribute [added](https://gitlab.com/gitlab-org/gitlab/-/issues/416795) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403042) in GitLab 16.0
+- `expires_at` attribute [added](https://gitlab.com/gitlab-org/gitlab/-/issues/416795) in GitLab 16.6.
+
+{{< /history >}}
Rotates a specified personal access token. This revokes the previous token and creates a new token
that expires after one week. Administrators can revoke tokens for any user. Non-administrators can
@@ -192,7 +214,11 @@ Other possible responses:
### Self-rotate
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/426779) in GitLab 16.10
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/426779) in GitLab 16.10
+
+{{< /history >}}
Instead of rotating a specific personal access token, you can also rotate the same personal access
token you used to authenticate the request. To self-rotate a personal access token, you must:
@@ -208,7 +234,11 @@ curl --request POST \
### Automatic reuse detection
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/395352) in GitLab 16.3
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/395352) in GitLab 16.3
+
+{{< /history >}}
When you rotate or revoke a token, GitLab automatically tracks the relationship between the old and
new tokens. Each time a new token is generated, a connection is made to the previous token. These
@@ -250,8 +280,12 @@ Other possible responses:
### Self-revoke
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350240) in GitLab 15.0. Limited to tokens with `api` scope.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369103) in GitLab 15.4, any token can use this endpoint.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350240) in GitLab 15.0. Limited to tokens with `api` scope.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369103) in GitLab 15.4, any token can use this endpoint.
+
+{{< /history >}}
Instead of revoking a specific personal access token, you can also revoke the same personal access
token you used to authenticate the request. To self-revoke a personal access token, you must use
@@ -265,7 +299,11 @@ curl --request DELETE \
## List all token associations
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/466046) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/466046) in GitLab 17.4.
+
+{{< /history >}}
Lists all groups, subgroups, and projects associated with the personal access token used to authenticate the request.
diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md
index 84c97aadbaca58bb9edab738822632efe0e45b44..2fb22f72dde757347a550b46738d2c6fb73d9f56 100644
--- a/doc/api/pipeline_schedules.md
+++ b/doc/api/pipeline_schedules.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pipeline schedules API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can read more about [pipeline schedules](../ci/pipelines/schedules.md).
@@ -107,7 +110,11 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
## Get all pipelines triggered by a pipeline schedule
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368566) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368566) in GitLab 15.3.
+
+{{< /history >}}
Get all pipelines triggered by a pipeline schedule in a project.
diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md
index 22995e57d602300676661e0802bcd2adc52789fa..699a415f26b5d8cd4ccf047b2c94eda46da951c7 100644
--- a/doc/api/pipeline_triggers.md
+++ b/doc/api/pipeline_triggers.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pipeline trigger tokens API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can read more about [triggering pipelines through the API](../ci/triggers/_index.md).
diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md
index ef5877c29abd4367f38fd2f24bb65b7a80fee2fa..6db90fa294ca682341c620c5d7942ec585a27457 100644
--- a/doc/api/pipelines.md
+++ b/doc/api/pipelines.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pipelines API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Pipelines pagination
@@ -18,12 +21,16 @@ Read more on [pagination](rest/_index.md#pagination).
## List project pipelines
-> - `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
-> - `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default.
-> - `name` in request [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_search`. Disabled by default.
-> - `name` in response [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/398131) in GitLab 16.3. Feature flag `pipeline_name_in_api` removed.
-> - `name` in request [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385864) in GitLab 16.9. Feature flag `pipeline_name_search` removed.
-> - Support for returning child pipelines with `source` set to `parent_pipeline` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39503) in GitLab 17.0.
+{{< history >}}
+
+- `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
+- `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default.
+- `name` in request [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_search`. Disabled by default.
+- `name` in response [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/398131) in GitLab 16.3. Feature flag `pipeline_name_in_api` removed.
+- `name` in request [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385864) in GitLab 16.9. Feature flag `pipeline_name_search` removed.
+- Support for returning child pipelines with `source` set to `parent_pipeline` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39503) in GitLab 17.0.
+
+{{< /history >}}
List pipelines in a project.
@@ -89,9 +96,13 @@ Example of response
## Get a single pipeline
-> - `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
-> - `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default.
-> - `name` in response [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/398131) in GitLab 16.3. Feature flag `pipeline_name_in_api` removed.
+{{< history >}}
+
+- `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
+- `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default.
+- `name` in response [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/398131) in GitLab 16.3. Feature flag `pipeline_name_in_api` removed.
+
+{{< /history >}}
Get one pipeline from a project.
@@ -158,8 +169,12 @@ Example of response
### Get the latest pipeline
-> - `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default.
-> - `name` in response [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/398131) in GitLab 16.3. Feature flag `pipeline_name_in_api` removed.
+{{< history >}}
+
+- `name` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115310) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `pipeline_name_in_api`. Disabled by default.
+- `name` in response [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/398131) in GitLab 16.3. Feature flag `pipeline_name_in_api` removed.
+
+{{< /history >}}
Get the latest pipeline for the most recent commit on a specific ref in a project. If no pipeline exists for the commit, a `403` status code is returned.
@@ -257,9 +272,12 @@ Example of response
### Get a pipeline's test report
-NOTE:
+{{< alert type="note" >}}
+
This API route is part of the [Unit test report](../ci/testing/unit_test_reports.md) feature.
+{{< /alert >}}
+
```plaintext
GET /projects/:id/pipelines/:pipeline_id/test_report
```
@@ -311,9 +329,12 @@ Sample response:
### Get a pipeline's test report summary
-NOTE:
+{{< alert type="note" >}}
+
This API route is part of the [Unit test report](../ci/testing/unit_test_reports.md) feature.
+{{< /alert >}}
+
```plaintext
GET /projects/:id/pipelines/:pipeline_id/test_report_summary
```
@@ -362,7 +383,11 @@ Sample response:
## Create a new pipeline
-> - `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
+{{< history >}}
+
+- `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
+
+{{< /history >}}
```plaintext
POST /projects/:id/pipeline
@@ -413,7 +438,11 @@ Example of response
## Retry jobs in a pipeline
-> - `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
+{{< history >}}
+
+- `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
+
+{{< /history >}}
Retry failed or canceled jobs in a pipeline. If there are no failed or canceled jobs in the pipeline, calling this endpoint has no effect.
@@ -469,10 +498,13 @@ Response:
POST /projects/:id/pipelines/:pipeline_id/cancel
```
-NOTE:
+{{< alert type="note" >}}
+
This endpoint returns a success response `200` regardless of the pipeline's state.
For more information, see [issue 414963](https://gitlab.com/gitlab-org/gitlab/-/issues/414963).
+{{< /alert >}}
+
| Attribute | Type | Required | Description |
|---------------|----------------|----------|-------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths) |
diff --git a/doc/api/plan_limits.md b/doc/api/plan_limits.md
index ec5204e1e49a199923b71b879479ba53a060dc2e..225ab3564bcc1d95221d7513b748da700905dfb9 100644
--- a/doc/api/plan_limits.md
+++ b/doc/api/plan_limits.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Plan limits API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Use this API to interact with the application limits for your existing subscription plan.
diff --git a/doc/api/product_analytics.md b/doc/api/product_analytics.md
index 54499cdecca58d5b16bbc0ed7169ebc345f2464c..d1bf2c8f9b6a8fcda9f22eff413648e401572596 100644
--- a/doc/api/product_analytics.md
+++ b/doc/api/product_analytics.md
@@ -5,26 +5,39 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Product analytics API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
-
-> - Introduced in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default.
-> - `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10.
-> - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11.
-> - `product_analytics_dashboards` [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/398653) by default in GitLab 16.11.
-> - Feature flag `product_analytics_dashboards` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454059) in GitLab 17.1.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167296) to beta in GitLab 17.5 [with a flag](../administration/feature_flags.md) named `product_analytics_features`.
-
-FLAG:
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default.
+- `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10.
+- `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11.
+- `product_analytics_dashboards` [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/398653) by default in GitLab 16.11.
+- Feature flag `product_analytics_dashboards` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454059) in GitLab 17.1.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167296) to beta in GitLab 17.5 [with a flag](../administration/feature_flags.md) named `product_analytics_features`.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
+
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is not ready for production use.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Make sure to define the `cube_api_base_url` and `cube_api_key` application settings first using [the API](settings.md).
+{{< /alert >}}
+
## Send query request to Cube
Generate an access token that can be used to query the Cube API. For example:
@@ -43,9 +56,12 @@ POST /projects/:id/product_analytics/request/dry-run
The body of the load request must be a valid Cube query.
-NOTE:
+{{< alert type="note" >}}
+
When measuring `TrackedEvents`, you must use `TrackedEvents.*` for `dimensions` and `timeDimensions`. The same rule applies when measuring `Sessions`.
+{{< /alert >}}
+
#### Tracked events example
```json
diff --git a/doc/api/project_access_tokens.md b/doc/api/project_access_tokens.md
index 3eb2f7b3e7a6e294029fb516d00556fe72295654..364e9c65dcb9c87a7a63609380e1764a2b6702ff 100644
--- a/doc/api/project_access_tokens.md
+++ b/doc/api/project_access_tokens.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project access tokens API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with project access tokens. For more information, see [Project access tokens](../user/project/settings/project_access_tokens.md).
## List all project access tokens
-> - `state` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.2.
+{{< history >}}
+
+- `state` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.2.
+
+{{< /history >}}
Lists all project access tokens for a specified project.
@@ -110,7 +117,11 @@ curl --request GET \
## Create a project access token
-> - The `expires_at` attribute default was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120213) in GitLab 16.0.
+{{< history >}}
+
+- The `expires_at` attribute default was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120213) in GitLab 16.0.
+
+{{< /history >}}
Creates a project access token for a specified project. You cannot create a token with an access level greater than your account. For example, a user with the Maintainer role cannot create a project access token with the Owner role.
@@ -154,8 +165,12 @@ curl --request POST \
## Rotate a project access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403042) in GitLab 16.0
-> - `expires_at` attribute [added](https://gitlab.com/gitlab-org/gitlab/-/issues/416795) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403042) in GitLab 16.0
+- `expires_at` attribute [added](https://gitlab.com/gitlab-org/gitlab/-/issues/416795) in GitLab 16.6.
+
+{{< /history >}}
Rotates a project access token. This immediately revokes the previous token and creates a new token. Generally, this endpoint rotates a specific project access token by authenticating with a personal access token. You can also use a project access token to rotate itself. For more information, see [Self-rotate](#self-rotate).
diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md
index 79d35597e49049e719418dba73f297c723945c48..aff22e5e7d1c0c250adb9036aed13e5e954aaacb 100644
--- a/doc/api/project_aliases.md
+++ b/doc/api/project_aliases.md
@@ -1,13 +1,16 @@
---
stage: Create
group: Source Code
-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"
+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
title: Project Aliases API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
All methods require administrator authorization.
diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md
index 4626e720bd666464eed71aaa806f8de05fb3e89f..93faad38fc7f73af86f6341051dec450bb857a85 100644
--- a/doc/api/project_badges.md
+++ b/doc/api/project_badges.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project badges API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Placeholder tokens
diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md
index 9ef652fa6ed9446e498de448d072193a95f373b5..ea67287829a932deee40b5a438c599a5a67e9dd1 100644
--- a/doc/api/project_clusters.md
+++ b/doc/api/project_clusters.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project clusters API (certificate-based) (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< /alert >}}
+
Users need at least the Maintainer role to use these endpoints.
## List project clusters
@@ -300,11 +306,14 @@ Parameters:
| `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project |
| `environment_scope` | string | no | The associated environment to the cluster |
-NOTE:
+{{< alert type="note" >}}
+
`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added
through the ["Add existing Kubernetes cluster"](../user/project/clusters/add_existing_cluster.md) option or
through the ["Add existing cluster to project"](#add-existing-cluster-to-project) endpoint.
+{{< /alert >}}
+
Example request:
```shell
diff --git a/doc/api/project_container_registry_protection_rules.md b/doc/api/project_container_registry_protection_rules.md
index f4203e68260a5287603517250ecfec7e0d948e9c..f91afa25e17f706b2f4ce377f752b8e2191f8855 100644
--- a/doc/api/project_container_registry_protection_rules.md
+++ b/doc/api/project_container_registry_protection_rules.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'container_repository_protection_rules.md'
-remove_date: '2025-03-02'
+redirect_to: container_repository_protection_rules.md
+remove_date: "2025-03-02"
---
<!-- markdownlint-disable -->
diff --git a/doc/api/project_forks.md b/doc/api/project_forks.md
index 65d44d30ba31200a2ca6a303b6c94a239a25fb2f..711ff5cfc2d7ac0d6769e5f44d075a5b1089e8bb 100644
--- a/doc/api/project_forks.md
+++ b/doc/api/project_forks.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project forks API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can manage [project forks](../user/project/repository/forking_workflow.md) by using the REST API.
diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md
index 7add2a362ee96eae845e03e2e322ce4d0310dbe0..eae578cd293cc77791856edd81e7ade925f40e3a 100644
--- a/doc/api/project_import_export.md
+++ b/doc/api/project_import_export.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project import and export API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the project import and export API to import and export projects using file transfers.
@@ -150,7 +153,11 @@ ls *export.tar.gz
## Import a file
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
```plaintext
POST /projects/import
@@ -211,19 +218,28 @@ requests.post(url, headers=headers, data=data, files=files)
}
```
-NOTE:
+{{< alert type="note" >}}
+
The maximum import file size can be set by the Administrator. It defaults to `0` (unlimited).
As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](settings.md#update-application-settings) or the [**Admin** area](../administration/settings/account_and_limit_settings.md).
+{{< /alert >}}
+
## Import a file from a remote object storage
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `import_project_from_remote_file`.
On GitLab.com and GitLab Dedicated, this feature is available.
+{{< /alert >}}
+
```plaintext
POST /projects/remote-import
```
@@ -268,8 +284,12 @@ The `Content-Type` header must be `application/gzip`.
## Import a single relation
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425798) as a [beta](../policy/development_stages_support.md#beta) in GitLab 16.11 [with a flag](../administration/feature_flags.md) named `single_relation_import`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/455889) in GitLab 17.1. Feature flag `single_relation_import` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425798) as a [beta](../policy/development_stages_support.md#beta) in GitLab 16.11 [with a flag](../administration/feature_flags.md) named `single_relation_import`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/455889) in GitLab 17.1. Feature flag `single_relation_import` removed.
+
+{{< /history >}}
This endpoint accepts a project export archive and a named relation (issues,
merge requests, pipelines, or milestones) and re-imports that relation, skipping
@@ -315,7 +335,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
## Check relation import statuses
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425798) in GitLab 16.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425798) in GitLab 16.11.
+
+{{< /history >}}
This endpoint fetches the status of any relation imports associated with a project. Because
only one relation import can be scheduled at a time, you can use this endpoint to check whether
@@ -356,7 +380,11 @@ Status can be one of:
## Import a file from AWS S3
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350571) in GitLab 15.11. Feature flag `import_project_from_remote_file_s3` removed.
+{{< history >}}
+
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350571) in GitLab 15.11. Feature flag `import_project_from_remote_file_s3` removed.
+
+{{< /history >}}
```plaintext
POST /projects/remote-import-s3
@@ -460,11 +488,16 @@ be populated with any occurrences of relations that failed to import due to eith
- Unrecoverable errors.
- Retries were exhausted. A typical example: query timeouts.
-NOTE:
+{{< alert type="note" >}}
+
An element's `id` field in `failed_relations` references the failure record, not the relation.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The `failed_relations` array is capped to 100 items.
+{{< /alert >}}
```json
{
diff --git a/doc/api/project_job_token_scopes.md b/doc/api/project_job_token_scopes.md
index 5e9cd6a49597902e1280304246e66db60cc9d1ad..99535743bb183c9f327e2858c467201e27544d91 100644
--- a/doc/api/project_job_token_scopes.md
+++ b/doc/api/project_job_token_scopes.md
@@ -1,20 +1,26 @@
---
stage: Software Supply Chain Security
group: Pipeline Security
-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"
+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
title: Project CI/CD job token scope API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can read more about the [CI/CD job token](../ci/jobs/ci_job_token.md).
-NOTE:
+{{< alert type="note" >}}
+
All requests to the CI/CD job token scope API endpoint must be [authenticated](rest/authentication.md).
The authenticated user must have at least the Maintainer role for the project.
+{{< /alert >}}
+
## Get a project's CI/CD job token access settings
Fetch the [CI/CD job token access settings](../ci/jobs/ci_job_token.md#control-job-token-access-to-your-project) (job token scope) of a project.
@@ -53,7 +59,11 @@ Example response:
## Patch a project's CI/CD job token access settings
-> - **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
+{{< history >}}
+
+- **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
+
+{{< /history >}}
Patch the [**Limit access _to_ this project** setting](../ci/jobs/ci_job_token.md#add-a-group-or-project-to-the-job-token-allowlist) (job token scope) of a project.
diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md
index ea4e0876f7c76a77d31c9619dc73ecfd27b7c4aa..9ef7fd495ce6b6a79032e895948dcab424d62907 100644
--- a/doc/api/project_level_variables.md
+++ b/doc/api/project_level_variables.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project-level CI/CD variables API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## List project variables
@@ -95,7 +98,11 @@ Example response:
## Create a variable
-> - `masked_and_hidden` and `hidden` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29674) in GitLab 17.4.
+{{< history >}}
+
+- `masked_and_hidden` and `hidden` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29674) in GitLab 17.4.
+
+{{< /history >}}
Create a new variable. If a variable with the same `key` already exists, the new variable
must have a different `environment_scope`. Otherwise, GitLab returns a message similar to:
diff --git a/doc/api/project_markdown_uploads.md b/doc/api/project_markdown_uploads.md
index dc9d0d43979e3a64bebc4424d162acdb3d1f2d5a..736c5d6d552a24ca83bb43253af35667b48a8255 100644
--- a/doc/api/project_markdown_uploads.md
+++ b/doc/api/project_markdown_uploads.md
@@ -5,18 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Markdown uploads API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Markdown uploads are [files uploaded to a project](../security/user_file_uploads.md) that can be referenced in Markdown
text in an issue, merge request, snippet, or wiki page.
## Upload a file
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112450) in GitLab 15.10. Feature flag `enforce_max_attachment_size_upload_api` removed.
-> - `full_path` response attribute pattern [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150939) in GitLab 17.1.
-> - `id` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161160) in GitLab 17.3.
+{{< history >}}
+
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112450) in GitLab 15.10. Feature flag `enforce_max_attachment_size_upload_api` removed.
+- `full_path` response attribute pattern [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150939) in GitLab 17.1.
+- `id` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161160) in GitLab 17.3.
+
+{{< /history >}}
Uploads a file to the specified project to be used in an issue or merge request description, or a comment.
@@ -61,7 +68,11 @@ In the response, the:
## List uploads
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+
+{{< /history >}}
Get all uploads of the project sorted by `created_at` in descending order.
@@ -112,7 +123,11 @@ Example response:
## Download an uploaded file by ID
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+
+{{< /history >}}
Download an uploaded file by ID.
@@ -141,7 +156,11 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
## Download an uploaded file by secret and filename
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164441) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164441) in GitLab 17.4.
+
+{{< /history >}}
Download an uploaded file by secret and filename.
@@ -171,7 +190,11 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
## Delete an uploaded file by ID
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) in GitLab 17.2.
+
+{{< /history >}}
Delete an uploaded file by ID.
@@ -200,7 +223,11 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git
## Delete an uploaded file by secret and filename
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164441) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164441) in GitLab 17.4.
+
+{{< /history >}}
Delete an uploaded file by secret and filename.
diff --git a/doc/api/project_packages_protection_rules.md b/doc/api/project_packages_protection_rules.md
index 275caeb94b297d4f73fdf17a162b0e800ad482ae..dbd60366d2379f0c18ce4c30ea18c4233c610321 100644
--- a/doc/api/project_packages_protection_rules.md
+++ b/doc/api/project_packages_protection_rules.md
@@ -1,18 +1,25 @@
---
stage: Package
group: Package Registry
-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"
-description: "Documentation for the REST API for Package Protection Rules in GitLab."
+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
+description: Documentation for the REST API for Package Protection Rules in GitLab.
title: Protected packages API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151741) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `packages_protected_packages`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/472655) in GitLab 17.5.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472655) in GitLab 17.6. Feature flag `packages_protected_packages` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151741) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `packages_protected_packages`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/472655) in GitLab 17.5.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472655) in GitLab 17.6. Feature flag `packages_protected_packages` removed.
+
+{{< /history >}}
This API manages the protection rules for packages.
diff --git a/doc/api/project_pull_mirroring.md b/doc/api/project_pull_mirroring.md
index 87fdd96116063b45511fd0928545636f873e65ae..e0e73bf3526ec17084ccfec90a9a230c054ecf56 100644
--- a/doc/api/project_pull_mirroring.md
+++ b/doc/api/project_pull_mirroring.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pull mirroring API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can manage project [pull mirroring](../user/project/repository/mirror/pull.md) by using the REST API.
## Get a project's pull mirror details
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354506) in GitLab 15.6.
-> - [Extended response](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/168377) to include mirror configuration information in GitLab 17.5. The following configuration settings are included: `enabled`, `mirror_trigger_builds`, `only_mirror_protected_branches`, `mirror_overwrites_diverged_branches`, and `mirror_branch_regex`.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354506) in GitLab 15.6.
+- [Extended response](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/168377) to include mirror configuration information in GitLab 17.5. The following configuration settings are included: `enabled`, `mirror_trigger_builds`, `only_mirror_protected_branches`, `mirror_overwrites_diverged_branches`, and `mirror_branch_regex`.
+
+{{< /history >}}
Return the details of a project's [pull mirror](../user/project/repository/mirror/_index.md).
@@ -75,7 +82,11 @@ Example response:
## Configure pull mirroring for a project
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/494294) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/494294) in GitLab 17.6.
+
+{{< /history >}}
Configure pull mirroring settings.
@@ -118,16 +129,23 @@ curl --request PUT \
## Configure pull mirroring for a project (deprecated)
-> - Field `mirror_branch_regex` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/410354) in GitLab 16.2. Feature flag `mirror_only_branches_match_regex` removed.
-> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/494294) in GitLab 17.6.
+{{< history >}}
+
+- Field `mirror_branch_regex` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/410354) in GitLab 16.2. Feature flag `mirror_only_branches_match_regex` removed.
+- [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/494294) in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This configuration option was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/494294) in GitLab 17.6
and is planned for removal in v5 of the API. Use the [new configuration and endpoint](project_pull_mirroring.md#configure-pull-mirroring-for-a-project) instead.
This change is a breaking change.
+{{< /alert >}}
+
Configure pull mirroring while [creating a new project](projects.md#create-a-project) or
[updating an existing project](projects.md#edit-a-project) by using the API if the remote repository is accessible publicly or by
using `username:token` authentication.
diff --git a/doc/api/project_push_rules.md b/doc/api/project_push_rules.md
index 0630a5187fc62a25d8983161937375018c3b62ba..13792c45661399b7206a882939a05d5d96e9635a 100644
--- a/doc/api/project_push_rules.md
+++ b/doc/api/project_push_rules.md
@@ -1,13 +1,16 @@
---
stage: Create
group: Source Code
-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"
+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
title: Project push rules API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can manage [push rules](../user/project/repository/push_rules.md) for projects by using the REST API.
diff --git a/doc/api/project_relations_export.md b/doc/api/project_relations_export.md
index 369a7bcd31faaab2115ce06a70848566b48d750a..4cf9c9801f7261e903a45baf94e6f421adb67055 100644
--- a/doc/api/project_relations_export.md
+++ b/doc/api/project_relations_export.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project relations export API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - New application setting `bulk_import_enabled` introduced in GitLab 15.8. `bulk_import` feature flag removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- New application setting `bulk_import_enabled` introduced in GitLab 15.8. `bulk_import` feature flag removed.
+
+{{< /history >}}
The project relations export API partially exports a project's structure as separate files for each
top-level
diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md
index fc5093b9c0be5584de585492d39b6cec50bd16c2..284e2fd4e0183f1708deb587aa0a320ec12a190d 100644
--- a/doc/api/project_repository_storage_moves.md
+++ b/doc/api/project_repository_storage_moves.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project repository storage moves API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Project repositories including wiki and design repositories can be moved between storages. This API can help you when
[migrating to Gitaly Cluster](../administration/gitaly/_index.md#migrate-to-gitaly-cluster), for example.
diff --git a/doc/api/project_security_settings.md b/doc/api/project_security_settings.md
index dbc8383bcdf9da5f313526cfc817aa14aa3b32e7..45309aff1f12b4fdc5cccbecbed280189eed7280 100644
--- a/doc/api/project_security_settings.md
+++ b/doc/api/project_security_settings.md
@@ -1,13 +1,16 @@
---
stage: Application Security Testing
group: Secret Detection
-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"
+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
title: Project security settings API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every API call to project security settings must be [authenticated](rest/authentication.md).
diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md
index 2bee54b03c89c207083e3de9be044914b17be0fd..f84316e24376701aa8c6a2de6ce01632279cd7d1 100644
--- a/doc/api/project_snippets.md
+++ b/doc/api/project_snippets.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project snippets
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Snippet visibility level
@@ -20,12 +23,15 @@ Constants for snippet visibility levels are:
- **Internal**: The snippet is visible for any authenticated user except [external users](../administration/external_users.md).
- **Public**: The snippet can be accessed without any authentication.
-NOTE:
+{{< alert type="note" >}}
+
From July 2019, the `Internal` visibility setting is disabled for new projects, groups,
and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal`
visibility setting keep this setting. You can read more about the change in the
[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/12388).
+{{< /alert >}}
+
## List snippets
Get a list of project snippets.
diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md
index c8d98ef3b63fd63c2f27b11a8e2808e21d4f5e7c..588330481dcded4d9dd2fa5b1e74375d7e001b05 100644
--- a/doc/api/project_statistics.md
+++ b/doc/api/project_statistics.md
@@ -1,13 +1,16 @@
---
stage: Create
group: Source Code
-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"
+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
title: Project statistics API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every API call to [project](../user/project/_index.md) statistics must be authenticated.
Retrieving these statistics requires read access to the repository.
diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md
index 2620029904045014767162c22119893afd62f578..1b783cdfca405b34f3c1ca31e907cb35da88dd2a 100644
--- a/doc/api/project_templates.md
+++ b/doc/api/project_templates.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project templates API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This API is a project-specific version of these endpoints:
diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md
index 3c3535aabd780e29e2555b04cfa368299a0f2cf8..f9f4ddc5fd34fdb96a7342596a8400ee6ec0e332 100644
--- a/doc/api/project_vulnerabilities.md
+++ b/doc/api/project_vulnerabilities.md
@@ -1,27 +1,37 @@
---
stage: Security Risk Management
group: Security Insights
-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"
+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
title: Project vulnerabilities API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - `last_edited_at` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
-> - `start_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
-> - `updated_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
-> - `last_edited_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
-> - `due_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- `last_edited_at` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- `start_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- `updated_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- `last_edited_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- `due_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This API is in the process of being deprecated and considered unstable.
The response payload may be subject to change or breakage
across GitLab releases. Use the
[GraphQL API](graphql/reference/_index.md#queryvulnerabilities)
instead.
+{{< /alert >}}
+
Every API call to vulnerabilities must be [authenticated](rest/authentication.md).
Vulnerability permissions inherit permissions from their project. If a project is
diff --git a/doc/api/project_webhooks.md b/doc/api/project_webhooks.md
index 143d85ef9ff812c8af7fd1ff1f521bc3f873d9b7..1e5b2d49bfffd4e6bda88d517a20d7cb7d9189e8 100644
--- a/doc/api/project_webhooks.md
+++ b/doc/api/project_webhooks.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project webhooks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Manage [project webhooks](../user/project/integrations/webhooks.md) by using the REST API. Project webhooks are different
to [system hooks](system_hooks.md), which are system-wide, and [group webhooks](group_webhooks.md).
@@ -86,7 +89,11 @@ Example response:
## Get a list of project webhook events
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151048) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151048) in GitLab 17.3.
+
+{{< /history >}}
Get a list of events for a specific project webhook in the past 7 days from start date.
@@ -357,7 +364,11 @@ Example response:
## Resend a project webhook event
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151130) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151130) in GitLab 17.4.
+
+{{< /history >}}
Resend a specific project webhook event.
@@ -386,7 +397,11 @@ Example response:
## Add a webhook to a project
-> - `name` and `description` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460887) in GitLab 17.1.
+{{< history >}}
+
+- `name` and `description` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460887) in GitLab 17.1.
+
+{{< /history >}}
Add a webhook to a specified project.
@@ -425,7 +440,11 @@ Supported attributes:
## Edit a project webhook
-> - `name` and `description` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460887) in GitLab 17.1.
+{{< history >}}
+
+- `name` and `description` attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460887) in GitLab 17.1.
+
+{{< /history >}}
Edit a project webhook for a specified project.
@@ -485,8 +504,12 @@ is returned.
## Trigger a test project webhook
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147656) in GitLab 16.11.
-> - Special rate limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150066) in GitLab 17.0 [with a flag](../administration/feature_flags.md) named `web_hook_test_api_endpoint_rate_limit`. Enabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147656) in GitLab 16.11.
+- Special rate limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150066) in GitLab 17.0 [with a flag](../administration/feature_flags.md) named `web_hook_test_api_endpoint_rate_limit`. Enabled by default.
+
+{{< /history >}}
Trigger a test project webhook for a specified project.
@@ -518,7 +541,11 @@ Example response:
## Set a custom header
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153768) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153768) in GitLab 17.1.
+
+{{< /history >}}
```plaintext
PUT /projects/:id/hooks/:hook_id/custom_headers/:key
@@ -537,7 +564,11 @@ On success, this endpoint returns the response code `204 No Content`.
## Delete a custom header
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153768) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153768) in GitLab 17.1.
+
+{{< /history >}}
```plaintext
DELETE /projects/:id/hooks/:hook_id/custom_headers/:key
@@ -555,7 +586,11 @@ On success, this endpoint returns the response code `204 No Content`.
## Set a URL variable
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+
+{{< /history >}}
```plaintext
PUT /projects/:id/hooks/:hook_id/url_variables/:key
@@ -574,7 +609,11 @@ On success, this endpoint returns the response code `204 No Content`.
## Delete a URL variable
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+
+{{< /history >}}
```plaintext
DELETE /projects/:id/hooks/:hook_id/url_variables/:key
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 510619e705b69019456b3f366c48b9f3471cf6ca..db7a135f0b56d48a35a6a8ecae712b387dbd01ba 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Projects API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Projects API provides programmatic access to manage GitLab projects and configure their key settings. A project is a central hub for collaboration where you store code, track issues, and organize team activities.
@@ -319,9 +322,12 @@ target the upstream project by default.
### Templates for issues and merge requests
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/)
can also see the `issues_template` and `merge_requests_template` parameters for managing
@@ -342,7 +348,11 @@ List projects.
### List all projects
-> - The `_links.cluster_agents` attribute in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) in GitLab 15.0.
+{{< history >}}
+
+- The `_links.cluster_agents` attribute in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) in GitLab 15.0.
+
+{{< /history >}}
Get a list of all visible projects across GitLab for the authenticated user.
When accessed without authentication, only public projects with _simple_ fields
@@ -589,10 +599,13 @@ When the user is authenticated and `simple` is not set, this endpoint returns so
]
```
-NOTE:
+{{< alert type="note" >}}
+
`last_activity_at` is updated based on [project activity](../user/project/working_with_projects.md#view-project-activity)
and [project events](events.md). `updated_at` is updated whenever the project record is changed in the database.
+{{< /alert >}}
+
You can filter by [custom attributes](custom_attributes.md) with:
```plaintext
@@ -622,9 +635,12 @@ Prerequisites:
- To view [certain attributes](https://gitlab.com/gitlab-org/gitlab/-/blob/520776fa8e5a11b8275b7c597d75246fcfc74c89/lib/api/entities/project.rb#L109-130), you must be an administrator or have the Owner role for the project.
-NOTE:
+{{< alert type="note" >}}
+
Only the projects in the user's (specified in `user_id`) namespace are returned. Projects owned by the user in any group or subgroups are not returned. An empty list is returned if a profile is set to private.
+{{< /alert >}}
+
This endpoint supports [keyset pagination](rest/_index.md#keyset-based-pagination)
for selected `order_by` options.
@@ -1388,8 +1404,12 @@ Manage a project, including creation, deletion, and archival.
### Create a project
-> - `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0.
-> - `model_registry_access_level` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) in GitLab 16.7.
+{{< history >}}
+
+- `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0.
+- `model_registry_access_level` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) in GitLab 16.7.
+
+{{< /history >}}
Creates a new project owned by the authenticated user.
@@ -1506,8 +1526,12 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \
### Create a project for a user
-> - `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0.
-> - `model_registry_access_level` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) in GitLab 16.7.
+{{< history >}}
+
+- `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0.
+- `model_registry_access_level` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) in GitLab 16.7.
+
+{{< /history >}}
Create a project for a user.
@@ -1619,8 +1643,12 @@ settings with access control options can be one of:
### Edit a project
-> - `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0.
-> - `model_registry_access_level` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) in GitLab 16.7.
+{{< history >}}
+
+- `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0.
+- `model_registry_access_level` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) in GitLab 16.7.
+
+{{< /history >}}
Update an existing project.
@@ -2119,10 +2147,13 @@ Delete a project. This endpoint:
The deletion happens after the number of days specified in the
[default deletion delay](../administration/settings/visibility_and_access_controls.md#deletion-protection).
-WARNING:
+{{< alert type="warning" >}}
+
The option to delete projects immediately from deletion protection settings in the **Admin** area was
[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 15.9 and removed in GitLab 16.0.
+{{< /alert >}}
+
```plaintext
DELETE /projects/:id
```
@@ -2137,9 +2168,12 @@ Supported attributes:
### Restore a project marked for deletion
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Restore a project that is marked for deletion.
@@ -2294,7 +2328,11 @@ Example response:
#### List groups available for project transfer
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371006) in GitLab 15.4
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371006) in GitLab 15.4
+
+{{< /history >}}
Retrieve a list of groups to which the user can transfer a project.
@@ -2375,7 +2413,11 @@ Example response:
### Download a project avatar
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144039) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144039) in GitLab 16.9.
+
+{{< /history >}}
Download a project avatar. You can access this endpoint without authentication if the project is publicly accessible.
@@ -2397,7 +2439,11 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
### Remove a project avatar
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92604) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92604) in GitLab 15.4.
+
+{{< /history >}}
To remove a project avatar, use a blank value for the `avatar` attribute.
@@ -2467,12 +2513,19 @@ Supported attributes:
## Real-time security scan
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/479210) in GitLab 17.6. This feature is an [experiment](../policy/development_stages_support.md).
+- Tier: Ultimate
+- Offering: GitLab.com
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/479210) in GitLab 17.6. This feature is an [experiment](../policy/development_stages_support.md).
+
+{{< /history >}}
Returns SAST scan results for a single file in real-time.
@@ -2571,10 +2624,17 @@ Supported attributes:
## Secret push protection status
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/160960) in GitLab 17.3.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/160960) in GitLab 17.3.
+{{< /history >}}
If you have at least the Developer role, the following requests could also return the `secret_push_protection_enabled` value.
Note that some of these requests have stricter requirements about roles. Refer to the endpoints above for clarification.
diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md
index 8a36f53f59df15f737dfca6efc0f99bf675a4554..4cec42d6629e6ea9cd21f08869930ae943f9aea1 100644
--- a/doc/api/protected_branches.md
+++ b/doc/api/protected_branches.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Protected branches API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Valid access levels
@@ -22,7 +25,11 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels`
## List protected branches
-> - Deploy key information [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116846) in GitLab 16.0.
+{{< history >}}
+
+- Deploy key information [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116846) in GitLab 16.0.
+
+{{< /history >}}
Gets a list of [protected branches](../user/project/repository/branches/protected.md) from a project
as they are defined in the UI. If a wildcard is set, it is returned instead of the exact name
@@ -230,7 +237,11 @@ Example response:
## Protect repository branches
-> - `deploy_key_id` configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166598) in GitLab 17.5.
+{{< history >}}
+
+- `deploy_key_id` configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166598) in GitLab 17.5.
+
+{{< /history >}}
Protects a single repository branch or several project repository
branches using a wildcard protected branch.
@@ -345,9 +356,12 @@ The following example response includes:
### Example with user push access and group merge access
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the
form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`.
@@ -409,11 +423,18 @@ The following example response includes:
### Example with deploy key access
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166598) in GitLab 17.5.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166598) in GitLab 17.5.
+
+{{< /history >}}
Elements in the `allowed_to_push` array should take the form `{user_id: integer}`, `{group_id: integer}`,
`{deploy_key_id: integer}`, or `{access_level: integer}`.
@@ -472,11 +493,18 @@ The following example response includes:
### Example with allow to push and allow to merge access
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - Moved to GitLab Premium in 13.9.
+{{< history >}}
+
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
Example request:
@@ -570,8 +598,12 @@ curl --request DELETE \
## Update a protected branch
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101903) in GitLab 15.6.
-> - `deploy_key_id` configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166598) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101903) in GitLab 15.6.
+- `deploy_key_id` configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166598) in GitLab 17.5.
+
+{{< /history >}}
Updates a protected branch.
diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md
index 8f1af5adcc55d6541ce9a460d32d1f6a4a48bf01..5903984382857f6276ac455aa3747e54e65358b5 100644
--- a/doc/api/protected_environments.md
+++ b/doc/api/protected_environments.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Protected environments API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Valid access levels
@@ -172,7 +175,11 @@ Example response:
## Update a protected environment
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351854) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351854) in GitLab 15.4.
+
+{{< /history >}}
Updates a single environment.
diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md
index 3ff43bd28969d834c1ce09fc5e81a46a9ef81374..036718cf2ef84063cfdf28fe632b957d190053e3 100644
--- a/doc/api/protected_tags.md
+++ b/doc/api/protected_tags.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Protected tags API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Valid access levels
@@ -19,7 +22,11 @@ These access levels are recognized:
## List protected tags
-> - Deploy key information [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116846) in GitLab 16.0.
+{{< history >}}
+
+- Deploy key information [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116846) in GitLab 16.0.
+
+{{< /history >}}
Gets a list of [protected tags](../user/project/protected_tags.md) from a project.
This function takes pagination parameters `page` and `per_page` to restrict the list of protected tags.
@@ -96,7 +103,11 @@ Example response:
## Protect repository tags
-> - `deploy_key_id` configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166866) in GitLab 17.5.
+{{< history >}}
+
+- `deploy_key_id` configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166866) in GitLab 17.5.
+
+{{< /history >}}
Protects a single repository tag, or several project repository
tags, using a wildcard protected tag.
diff --git a/doc/api/releases/_index.md b/doc/api/releases/_index.md
index 013d0289a35781b825635613c9a78d32b9fffd4a..f3a9ce7ea6fe5710dae04d277285c89559e42473 100644
--- a/doc/api/releases/_index.md
+++ b/doc/api/releases/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Releases API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to manipulate [release entries](../../user/project/releases/_index.md).
@@ -403,7 +406,11 @@ Example response:
## Download a release asset
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358188) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358188) in GitLab 15.4.
+
+{{< /history >}}
Download a release asset file by making a request with the following format:
@@ -425,7 +432,11 @@ curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.ex
### Get the latest release
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358188) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358188) in GitLab 15.4.
+
+{{< /history >}}
Latest release information is accessible through a permanent API URL.
@@ -593,9 +604,12 @@ Example response:
### Group milestones
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Group milestones associated with the project may be specified in the `milestones`
array for [Create a release](#create-a-release) and [Update a release](#update-a-release)
@@ -604,9 +618,12 @@ adding milestones for ancestor groups raises an error.
## Collect release evidence
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Creates an evidence for an existing release.
@@ -633,7 +650,11 @@ Example response:
## Update a release
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72448) to allow for `JOB-TOKEN` in GitLab 14.5.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72448) to allow for `JOB-TOKEN` in GitLab 14.5.
+
+{{< /history >}}
Updates a release. Developer level access to the project is required to update a release.
@@ -832,7 +853,11 @@ Additionally, if a [release is requested from the API](#list-releases), for each
## Historical releases
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199429) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199429) in GitLab 15.2.
+
+{{< /history >}}
A release with a `released_at` attribute set to a past date is labeled
as an **Historical release** [in the UI](../../user/project/releases/_index.md#historical-releases).
diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md
index 4b96452b25d57cd36231de655fd454f7626e84a2..b77c39e64045f54fce42193df79c5d2c757084f8 100644
--- a/doc/api/releases/links.md
+++ b/doc/api/releases/links.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Release links API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> Support for [GitLab CI/CD job token](../../ci/jobs/ci_job_token.md) authentication [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250819) in GitLab 15.1.
@@ -143,9 +146,12 @@ PUT /projects/:id/releases/:tag_name/assets/links/:link_id
| `direct_asset_path` | string | no | Optional path for a [direct asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). |
| `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. |
-NOTE:
+{{< alert type="note" >}}
+
You have to specify at least one of `name` or `url`
+{{< /alert >}}
+
Example request:
```shell
diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md
index a479425bf6dc5f92fe49dcb6734720bc2981aeae..4dbe3865da50b4572c9ebc283c7ac6a0625551eb 100644
--- a/doc/api/remote_mirrors.md
+++ b/doc/api/remote_mirrors.md
@@ -1,13 +1,16 @@
---
stage: Create
group: Source Code
-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"
+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
title: Project remote mirrors API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Push mirrors](../user/project/repository/mirror/push.md)
defined on a project's repository settings are called remote mirrors. You
@@ -16,11 +19,14 @@ can query and modify the state of these mirrors with the remote mirror API.
For security reasons, the `url` attribute in the API response is always scrubbed of username
and password information.
-NOTE:
+{{< alert type="note" >}}
+
[Pull mirrors](../user/project/repository/mirror/pull.md) use
[a different API endpoint](project_pull_mirroring.md#configure-pull-mirroring-for-a-project) to
display and update them.
+{{< /alert >}}
+
## List a project's remote mirrors
Returns an array of remote mirrors and their statuses:
@@ -88,7 +94,11 @@ Example response:
## Get a single project's remote mirror public key
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/180291) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/180291) in GitLab 17.9.
+
+{{< /history >}}
Get the public key of a remote mirror that uses SSH authentication.
@@ -132,10 +142,14 @@ project pull mirroring API.
## Create a push mirror
-> - Field `mirror_branch_regex` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/410354) in GitLab 16.2. Feature flag `mirror_only_branches_match_regex` removed.
-> - Field `auth_method` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75155) in GitLab 16.10.
+{{< history >}}
+
+- Field `mirror_branch_regex` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 15.8 [with a flag](../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/410354) in GitLab 16.2. Feature flag `mirror_only_branches_match_regex` removed.
+- Field `auth_method` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75155) in GitLab 16.10.
+
+{{< /history >}}
Push mirroring is disabled by default. To enable it, include the optional parameter
`enabled` when you create the mirror:
@@ -180,7 +194,11 @@ Example response:
## Update a remote mirror's attributes
-> - Field `auth_method` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75155) in GitLab 16.10.
+{{< history >}}
+
+- Field `auth_method` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75155) in GitLab 16.10.
+
+{{< /history >}}
Toggle a remote mirror on or off, or change which types of branches are
mirrored:
@@ -224,7 +242,11 @@ Example response:
## Force push mirror update
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388907) in GitLab 16.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388907) in GitLab 16.11.
+
+{{< /history >}}
[Force an update](../user/project/repository/mirror/_index.md#force-an-update) to a push mirror.
diff --git a/doc/api/repositories.md b/doc/api/repositories.md
index 62154b6f172b07433f1c795011317cee173090ae..e2c805461c3d99f4b05590f23e68fda380bc1580 100644
--- a/doc/api/repositories.md
+++ b/doc/api/repositories.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Documentation for the REST API for Git repositories in GitLab."
+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
+description: Documentation for the REST API for Git repositories in GitLab.
title: Repositories API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## List repository tree
@@ -20,10 +23,13 @@ command. For more information, refer to the section
[Tree Objects](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects.html#_tree_objects)
in the Git internals documentation.
-WARNING:
+{{< alert type="warning" >}}
+
This endpoint changed to [keyset-based pagination](rest/_index.md#keyset-based-pagination)
in GitLab 15.0. Iterating pages of results with a number (`?page=2`) is unsupported.
+{{< /alert >}}
+
```plaintext
GET /projects/:id/repository/tree
```
@@ -230,7 +236,11 @@ Example response:
## Contributors
-> - `ref` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/156852) in GitLab 17.4.
+{{< history >}}
+
+- `ref` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/156852) in GitLab 17.4.
+
+{{< /history >}}
Get repository contributors list. This endpoint can be accessed without
authentication if the repository is publicly accessible.
@@ -316,9 +326,13 @@ Example response:
## Add changelog data to a changelog file
-> - Commit range limits [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89032) in GitLab 15.1 [with a flag](../administration/feature_flags.md) named `changelog_commits_limitation`. Disabled by default.
-> - [Enabled on GitLab.com and by default on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/33893) in GitLab 15.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/364101) in GitLab 17.3. Feature flag `changelog_commits_limitation` removed.
+{{< history >}}
+
+- Commit range limits [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89032) in GitLab 15.1 [with a flag](../administration/feature_flags.md) named `changelog_commits_limitation`. Disabled by default.
+- [Enabled on GitLab.com and by default on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/33893) in GitLab 15.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/364101) in GitLab 17.3. Feature flag `changelog_commits_limitation` removed.
+
+{{< /history >}}
Generate changelog data based on commits in a repository.
@@ -451,7 +465,11 @@ curl --request POST \
## Generate changelog data
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172842) authentication through [CI/CD job token](../ci/jobs/ci_job_token.md) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172842) authentication through [CI/CD job token](../ci/jobs/ci_job_token.md) in GitLab 17.7.
+
+{{< /history >}}
Generate changelog data based on commits in a repository, without committing
them to a changelog file.
diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md
index 700837f8f06697fbcf5d1f5806ddc9ca81056538..1fa28fa51b13e94697dc0309cc9451d230603fae 100644
--- a/doc/api/repository_files.md
+++ b/doc/api/repository_files.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Documentation for the REST API for managing Git repository files in GitLab."
+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
+description: Documentation for the REST API for managing Git repository files in GitLab.
title: Repository files API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can fetch, create, update, and delete files in your repository with this API.
You can also [configure rate limits](../administration/settings/files_api_rate_limits.md)
@@ -234,9 +237,12 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=main"
```
-NOTE:
+{{< alert type="note" >}}
+
Like [Get file from repository](repository_files.md#get-file-from-repository), you can use `HEAD` to get just file metadata.
+{{< /alert >}}
+
## Create new file in repository
Allows you to create a single file. For creating multiple files with a single request,
diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md
index 0ce3418b2ec6186bf65b63ca5e6dbb922b1071f6..ade0caaff7f612dfeae93b81aef2fb6e7dff932c 100644
--- a/doc/api/repository_submodules.md
+++ b/doc/api/repository_submodules.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Repository submodules API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Update existing submodule reference in repository
diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md
index d53a1d59151f82849da728b61eef5ae4e91601a7..c3909990e9670186b3d8ca998b86f34593e3ff39 100644
--- a/doc/api/resource_groups.md
+++ b/doc/api/resource_groups.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Resource group API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can read more about [controlling the job concurrency with resource groups](../ci/resource_groups/_index.md).
diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md
index cd02c3a3285096f4b3bdec27f8923f45871e09aa..105790b144c2cdf503542cb64ff3cefbe10bcee5 100644
--- a/doc/api/resource_iteration_events.md
+++ b/doc/api/resource_iteration_events.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Resource iteration events API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Resource iteration events keep track of what happens to GitLab [issues](../user/project/issues/_index.md).
diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md
index 2d3aebabfd8d1b4fd95e0db92b937d1fcea3bfc0..2f1b15fd3632bfc6e78ab8b24e49564b8698cf36 100644
--- a/doc/api/resource_label_events.md
+++ b/doc/api/resource_label_events.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Resource label events API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Resource label events keep track about who, when, and which label was added to (or removed from)
an issue, merge request, or epic.
@@ -100,17 +103,23 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
## Epics
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0
and is planned for removal in v5 of the API.
In GitLab 17.4 or later, if your administrator [enabled the new look for epics](../user/group/epics/epic_work_items.md), use the
[Work Items API](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/) instead. For more information, see the [guide how to migrate your existing APIs](graphql/epic_work_items_api_migration_guide.md).
This change is a breaking change.
+{{< /alert >}}
+
### List group epic label events
Gets a list of all label events for a single epic.
diff --git a/doc/api/resource_milestone_events.md b/doc/api/resource_milestone_events.md
index f5c823fb87b8acabb23ae8c2b664cbb51f8e79d2..f3ab86701ab1472cd373dd61a47eab5b1df84b8b 100644
--- a/doc/api/resource_milestone_events.md
+++ b/doc/api/resource_milestone_events.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Resource milestone events API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Resource [milestone](../user/project/milestones/_index.md) events keep track of what happens to
GitLab [issues](../user/project/issues/_index.md) and [merge requests](../user/project/merge_requests/_index.md).
diff --git a/doc/api/resource_state_events.md b/doc/api/resource_state_events.md
index a839469112922f96c55757be943862dc6cc72258..588ca952fe172a766bd02ca3627704a3076f3ec7 100644
--- a/doc/api/resource_state_events.md
+++ b/doc/api/resource_state_events.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Resource state events API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Resource state events keep track of what happens to GitLab [issues](../user/project/issues/_index.md)
[merge requests](../user/project/merge_requests/_index.md) and [epics starting with GitLab 15.4](../user/group/epics/_index.md)
@@ -219,15 +222,22 @@ Example response:
## Epics
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97554) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97554) in GitLab 15.4.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0
and is planned for removal in v5 of the API.
In GitLab 17.4 or later, if your administrator [enabled the new look for epics](../user/group/epics/epic_work_items.md), use the
[Work Items API](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/) instead. For more information, see the [guide how to migrate your existing APIs](graphql/epic_work_items_api_migration_guide.md).
This change is a breaking change.
+{{< /alert >}}
+
### List group epic state events
Returns a list of all state events for a single epic.
diff --git a/doc/api/resource_weight_events.md b/doc/api/resource_weight_events.md
index 00aa221d6c8d244f4575a6423081eb30802dec1c..824c8561c05a26bfcb5a7383df962c9b64c98245 100644
--- a/doc/api/resource_weight_events.md
+++ b/doc/api/resource_weight_events.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Resource weight events API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Resource weight events keep track of what happens to GitLab [issues](../user/project/issues/_index.md).
diff --git a/doc/api/rest/_index.md b/doc/api/rest/_index.md
index 9b27080c6f2cef9de0c7ebe8554f96508a339d05..01b474491ad14cd8f44d609d46ae7f3227fe591d 100644
--- a/doc/api/rest/_index.md
+++ b/doc/api/rest/_index.md
@@ -1,14 +1,17 @@
---
stage: Foundations
group: Import and Integrate
-description: Programmatic interaction with GitLab.
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
+description: Programmatic interaction with GitLab.
title: REST API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the GitLab REST API to retrieve data by using any compatible REST API client.
@@ -237,8 +240,12 @@ In boolean arguments, you should only set `true` or `false` values (not `null`).
### Redirects
-> - Introduced in GitLab 16.4 [with a flag](../../user/feature_flags.md) named `api_redirect_moved_projects`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137578) in GitLab 16.7. Feature flag `api_redirect_moved_projects` removed.
+{{< history >}}
+
+- Introduced in GitLab 16.4 [with a flag](../../user/feature_flags.md) named `api_redirect_moved_projects`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137578) in GitLab 16.7. Feature flag `api_redirect_moved_projects` removed.
+
+{{< /history >}}
After [path changes](../../user/project/repository/_index.md#repository-path-changes) the
REST API might respond with a message noting that the endpoint has moved. When this happens, used
@@ -273,8 +280,12 @@ For large collections, you should use keyset pagination
### Offset-based pagination
-> - The `users` endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/426547) for offset-based pagination in GitLab 16.5 and is planned for removal in 17.0. This change is a breaking change. Use keyset-based pagination for this endpoint instead.
-> - The `users` endpoint enforces keyset-based pagination when the number of requested records is greater than 50,000 in GitLab 17.0.
+{{< history >}}
+
+- The `users` endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/426547) for offset-based pagination in GitLab 16.5 and is planned for removal in 17.0. This change is a breaking change. Use keyset-based pagination for this endpoint instead.
+- The `users` endpoint enforces keyset-based pagination when the number of requested records is greater than 50,000 in GitLab 17.0.
+
+{{< /history >}}
Sometimes, the returned result spans many pages. When listing resources, you can
pass the following parameters:
@@ -290,9 +301,12 @@ In the following example, we list 50 [namespaces](../namespaces.md) per page:
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50"
```
-NOTE:
+{{< alert type="note" >}}
+
There is a [max offset allowed limit](../../administration/instance_limits.md#max-offset-allowed-by-the-rest-api-for-offset-based-pagination) for offset pagination. You can change the limit in GitLab Self-Managed instances.
+{{< /alert >}}
+
#### Pagination `Link` header
[`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each
@@ -403,11 +417,14 @@ excludes already-retrieved records.
The type of filter depends on the
`order_by` option used, and we can have more than one additional filter.
-WARNING:
+{{< alert type="warning" >}}
+
The `Links` header was removed to be aligned with the
[W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link`
header should be used instead.
+{{< /alert >}}
+
When the end of the collection is reached and there are no additional
records to retrieve, the `Link` header is absent and the resulting array is
empty.
diff --git a/doc/api/rest/authentication.md b/doc/api/rest/authentication.md
index 33874e9dcea5277ad3c36d3aae160920b34d8330..ef448a90f3e7362aa5b1601e75711ad63d4c01e3 100644
--- a/doc/api/rest/authentication.md
+++ b/doc/api/rest/authentication.md
@@ -1,8 +1,8 @@
---
stage: Foundations
group: Import and Integrate
-description: Programmatic interaction with GitLab.
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
+description: Programmatic interaction with GitLab.
title: REST API authentication
---
@@ -40,10 +40,13 @@ status code of `401`:
}
```
-NOTE:
+{{< alert type="note" >}}
+
Deploy tokens can't be used with the GitLab public API. For details, see
[Deploy Tokens](../../user/project/deploy_tokens/_index.md).
+{{< /alert >}}
+
## OAuth 2.0 tokens
You can use an [OAuth 2.0 token](../oauth2.md) to authenticate with the API by passing it in either
@@ -63,11 +66,14 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/ap
Read more about [GitLab as an OAuth 2.0 provider](../oauth2.md).
-NOTE:
+{{< alert type="note" >}}
+
All OAuth access tokens are valid for two hours after they are created. You can use the
`refresh_token` parameter to refresh tokens. See [OAuth 2.0 token](../oauth2.md) documentation for
how to request a new access token using a refresh token.
+{{< /alert >}}
+
## Personal/project/group access tokens
You can use access tokens to authenticate with the API by passing it in either the `private_token`
@@ -141,9 +147,9 @@ either the `private_token` parameter or the `PRIVATE-TOKEN` header.
By default, impersonation is enabled. To disable impersonation:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit the `/etc/gitlab/gitlab.rb` file:
@@ -154,7 +160,9 @@ By default, impersonation is enabled. To disable impersonation:
1. Save the file, and then [reconfigure](../../administration/restart_gitlab.md#reconfigure-a-linux-package-installation)
GitLab for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit the `config/gitlab.yml` file:
@@ -166,7 +174,9 @@ By default, impersonation is enabled. To disable impersonation:
1. Save the file, and then [restart](../../administration/restart_gitlab.md#self-compiled-installations)
GitLab for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To re-enable impersonation, remove this configuration and reconfigure GitLab (Linux package
installations) or restart GitLab (self-compiled installations).
diff --git a/doc/api/rest/third_party_clients.md b/doc/api/rest/third_party_clients.md
index a2a37184b09a89ed4ef6f580683aaf722d7d7e22..150ce90da9fcdf6976e229a3a80b1fc17fbc377b 100644
--- a/doc/api/rest/third_party_clients.md
+++ b/doc/api/rest/third_party_clients.md
@@ -1,14 +1,17 @@
---
stage: Foundations
group: Import and Integrate
-description: Programmatic interaction with GitLab.
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
+description: Programmatic interaction with GitLab.
title: REST API third-party clients
---
-DETAILS:
-**Tier:** Free
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can integrate third-party API client libraries with GitLab. The following libraries are
maintained by community members and not officially supported by GitLab. Report bugs and feature
diff --git a/doc/api/rest/troubleshooting.md b/doc/api/rest/troubleshooting.md
index 1b2b2c928315e922b01b4f7c3c31b87442fd098a..53ac3c79f9825bf6ad5146a774b3b7d798c18f12 100644
--- a/doc/api/rest/troubleshooting.md
+++ b/doc/api/rest/troubleshooting.md
@@ -1,14 +1,17 @@
---
stage: Foundations
group: Import and Integrate
-description: Programmatic interaction with GitLab.
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
+description: Programmatic interaction with GitLab.
title: REST API troubleshooting
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with the REST API, you might encounter an issue.
@@ -181,9 +184,9 @@ To resolve this problem, edit the configuration for your reverse proxy:
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle Apache configuration
+{{< tab title="Apache configuration" >}}
```plaintext
<VirtualHost *:443>
@@ -207,7 +210,9 @@ For example:
</VirtualHost>
```
-:::TabTitle NGINX configuration
+{{< /tab >}}
+
+{{< tab title="NGINX configuration" >}}
```plaintext
server {
@@ -225,6 +230,8 @@ server {
}
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
For more information, see [issue 18775](https://gitlab.com/gitlab-org/gitlab/-/issues/18775).
diff --git a/doc/api/runners.md b/doc/api/runners.md
index 8abfcd2467ed632b37c75ccb31c279a0cf6ed00f..bea52dd545e5cf60dc440784403deb5eb2ea1811 100644
--- a/doc/api/runners.md
+++ b/doc/api/runners.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Runners API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page describes endpoints for runners registered to an instance. To create a runner linked to the current user, see [Create a runner](users.md#create-a-runner-linked-to-a-user).
@@ -75,21 +78,28 @@ GET /runners?tag_list=tag1,tag2
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
```
-NOTE:
+{{< alert type="note" >}}
+
The `active` and `paused` values in the `status` query parameter were deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The `active` attribute in the response was deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
The `ip_address` attribute in the response was deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and will be removed in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
This attribute will start returning an empty string in GitLab 17.0.
The `ipAddress` attribute can be found inside the respective runner manager, currently only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).
+{{< /alert >}}
Example response:
@@ -124,9 +134,12 @@ Example response:
## List all runners
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Get a list of all runners in the GitLab instance (project and shared). Access
is restricted to users with administrator access.
@@ -158,21 +171,28 @@ GET /runners/all?tag_list=tag1,tag2
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
```
-NOTE:
+{{< alert type="note" >}}
+
The `active` and `paused` values in the `status` query parameter were deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The `active` attribute in the response was deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
The `ip_address` attribute in the response was deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and will be removed in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
This attribute will start returning an empty string in GitLab 17.0.
The `ipAddress` attribute can be found inside the respective runner manager, currently only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).
+{{< /alert >}}
Example response:
@@ -254,28 +274,37 @@ GET /runners/:id
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
```
-NOTE:
+{{< alert type="note" >}}
+
The `token` attribute in the response was deprecated [in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320)
and removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/214322).
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The `active` attribute in the response was deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
The `ip_address` attribute in the response was deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and will be removed in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
This attribute will start returning an empty string in GitLab 17.0.
The `ipAddress` attribute can be found inside the respective runner manager, currently only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
The `version`, `revision`, `platform`, and `architecture` attributes in the response were deprecated
[in GitLab 17.0](https://gitlab.com/gitlab-org/gitlab/-/issues/457128) and will be removed in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
The same attributes can be found inside the respective runner manager, currently only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).
+{{< /alert >}}
Example response:
@@ -348,21 +377,28 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab
--form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
```
-NOTE:
+{{< alert type="note" >}}
+
The `token` attribute in the response was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/214320) in GitLab 12.10
and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/214322) in GitLab 13.0.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The `active` query parameter was deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
The `ip_address` attribute in the response was deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and will be removed in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
This attribute will start returning an empty string in GitLab 17.0.
The `ipAddress` attribute can be found inside the respective runner manager, currently only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).
+{{< /alert >}}
Example response:
@@ -438,13 +474,20 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "active=false" "https://gitlab.example.com/api/v4/runners/6"
```
-NOTE:
+{{< alert type="note" >}}
+
The `active` form attribute was deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
+{{< /alert >}}
+
## List jobs processed by a runner
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) in GitLab 10.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) in GitLab 10.3.
+
+{{< /history >}}
List jobs that are being processed or were processed by the specified runner. The list of jobs is limited
to projects where the user has at least the Reporter role.
@@ -614,21 +657,28 @@ GET /projects/:id/runners?tag_list=tag1,tag2
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
```
-NOTE:
+{{< alert type="note" >}}
+
The `active` and `paused` values in the `status` query parameter were deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The `active` attribute in the response was deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
The `ip_address` attribute in the response was deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and will be removed in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
This attribute will start returning an empty string in GitLab 17.0.
The `ipAddress` attribute can be found inside the respective runner manager, currently only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).
+{{< /alert >}}
Example response:
@@ -685,7 +735,8 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla
--form "runner_id=9"
```
-NOTE:
+{{< alert type="note" >}}
+
The `ip_address` attribute in the response was deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and will be removed in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
@@ -693,6 +744,8 @@ This attribute will start returning an empty string in GitLab 17.0.
The `ipAddress` attribute can be found inside the respective runner manager, currently only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).
+{{< /alert >}}
+
Example response:
```json
@@ -763,21 +816,28 @@ GET /groups/:id/runners?tag_list=tag1,tag2
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"
```
-NOTE:
+{{< alert type="note" >}}
+
The `active` and `paused` values in the `status` query parameter were deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The `active` attribute in the response was deprecated
and will be removed in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
The `ip_address` attribute in the response was deprecated
[in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and will be removed in
[a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
This attribute will start returning an empty string in GitLab 17.0.
The `ipAddress` attribute can be found inside the respective runner manager, currently only available through the GraphQL
[`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).
+{{< /alert >}}
Example response:
@@ -824,12 +884,15 @@ Example response:
## Create a runner
-WARNING:
+{{< alert type="warning" >}}
+
This endpoint returns an `HTTP 410 Gone` status code if registration with runner registration tokens
is disabled in the project or group settings. If registration with runner registration tokens
is disabled, use the [`POST /user/runners`](users.md#create-a-runner-linked-to-a-user) endpoint
to create and register runners instead.
+{{< /alert >}}
+
Create a runner with a runner registration token.
```plaintext
@@ -970,9 +1033,12 @@ Example response:
## Reset instance's runner registration token
-WARNING:
+{{< alert type="warning" >}}
+
Runner registration tokens, and support for certain configuration arguments, were [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 17.0. After GitLab 17.0, you will no longer be able to reset runner registration tokens and the `reset_registration_token` endpoint will not function.
+{{< /alert >}}
+
Reset the runner registration token for the GitLab instance.
```plaintext
@@ -986,9 +1052,12 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
## Reset project's runner registration token
-WARNING:
+{{< alert type="warning" >}}
+
Runner registration tokens, and support for certain configuration arguments, were [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 17.0. After GitLab 17.0, you will no longer be able to reset runner registration tokens and the `reset_registration_token` endpoint will not function.
+{{< /alert >}}
+
Reset the runner registration token for a project.
```plaintext
@@ -1002,9 +1071,12 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
## Reset group's runner registration token
-WARNING:
+{{< alert type="warning" >}}
+
Runner registration tokens, and support for certain configuration arguments, were [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 17.0. After GitLab 17.0, you will no longer be able to reset runner registration tokens and the `reset_registration_token` endpoint will not function.
+{{< /alert >}}
+
Reset the runner registration token for a group.
```plaintext
diff --git a/doc/api/saml.md b/doc/api/saml.md
index e337f69eb680c57f34e1a07756cbe3995f19f2a3..9e36e610e2b0b314568eb9856785159a908e8ee8 100644
--- a/doc/api/saml.md
+++ b/doc/api/saml.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: SAML API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
+
+{{< /history >}}
Use this API to interact with SAML features.
@@ -56,7 +63,11 @@ Example response:
### Get a single SAML identity
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123591) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123591) in GitLab 16.1.
+
+{{< /history >}}
```plaintext
GET /groups/:id/saml/:uid
@@ -113,7 +124,11 @@ curl --location --request PATCH "https://gitlab.com/api/v4/groups/33/saml/yrnZW4
### Delete a single SAML identity
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423592) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423592) in GitLab 16.5.
+
+{{< /history >}}
```plaintext
DELETE /groups/:id/saml/:uid
@@ -157,10 +172,14 @@ Use the Users API to [delete a single identity of a user](users.md#delete-authen
## SAML group links
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.0.
-> - `access_level` type [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95607) from `string` to `integer` in GitLab 15.3.3.
-> - `member_role_id` type [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417201) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `custom_roles_for_saml_group_links`. Disabled by default.
-> - `member_role_id` type [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/417201) in GitLab 16.8. Feature flag `custom_roles_for_saml_group_links` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.0.
+- `access_level` type [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95607) from `string` to `integer` in GitLab 15.3.3.
+- `member_role_id` type [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417201) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `custom_roles_for_saml_group_links`. Disabled by default.
+- `member_role_id` type [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/417201) in GitLab 16.8. Feature flag `custom_roles_for_saml_group_links` removed.
+
+{{< /history >}}
List, get, add, and delete [SAML group links](../user/group/saml_sso/group_sync.md#configure-saml-group-links) by using
the REST API.
diff --git a/doc/api/scim.md b/doc/api/scim.md
index caafa5619ba0f328db4ce1ef9945a4c31908eda9..30306ebd03a84567cc0be46c4c0d2c74cd67d3e1 100644
--- a/doc/api/scim.md
+++ b/doc/api/scim.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: SCIM API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98354) in GitLab 15.5.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98354) in GitLab 15.5.
+
+{{< /history >}}
Use this API to manage SCIM identities in groups.
@@ -32,7 +39,11 @@ This API differs from the [internal group SCIM API](../development/internal_api/
## Get SCIM identities for a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
+
+{{< /history >}}
```plaintext
GET /groups/:id/scim/identities
@@ -74,7 +85,11 @@ curl --location --request GET "https://gitlab.example.com/api/v4/groups/33/scim/
## Get a single SCIM identity
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123591) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123591) in GitLab 16.1.
+
+{{< /history >}}
```plaintext
GET /groups/:id/scim/:uid
@@ -105,7 +120,11 @@ Example response:
## Update `extern_uid` field for a SCIM identity
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
+
+{{< /history >}}
Fields that can be updated are:
@@ -134,7 +153,11 @@ curl --location --request PATCH "https://gitlab.example.com/api/v4/groups/33/sci
## Delete a single SCIM identity
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423592) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423592) in GitLab 16.5.
+
+{{< /history >}}
```plaintext
DELETE /groups/:id/scim/:uid
diff --git a/doc/api/search.md b/doc/api/search.md
index 5db53926f7bc7da31ff1b060dfee143df9f29a9b..781c22954cb8270f3bc3260337ec70b496df3758 100644
--- a/doc/api/search.md
+++ b/doc/api/search.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Search API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every API call to search must be authenticated.
@@ -138,9 +141,12 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
The `assignee` column is deprecated. It is shown as a single-sized array `assignees` to conform to the GitLab EE API.
+{{< /alert >}}
+
### Scope: `merge_requests`
```shell
@@ -299,8 +305,11 @@ Example response:
### Scope: `wiki_blobs`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
This scope is available only when [advanced search is enabled](../user/search/advanced_search.md#enable-advanced-search).
@@ -327,13 +336,19 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
+{{< /alert >}}
+
### Scope: `commits`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
This scope is available only when [advanced search is enabled](../user/search/advanced_search.md#enable-advanced-search).
@@ -368,8 +383,11 @@ Example response:
### Scope: `blobs`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
This scope is available only when [advanced search is enabled](../user/search/advanced_search.md#enable-advanced-search).
@@ -800,13 +818,19 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
+{{< /alert >}}
+
### Scope: `notes`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
This scope is available only when [advanced search is enabled](../user/search/advanced_search.md#enable-advanced-search).
@@ -927,9 +951,12 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
`assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API.
+{{< /alert >}}
+
### Scope: `merge_requests`
```shell
@@ -1057,8 +1084,11 @@ Example response:
### Scope: `wiki_blobs`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
This scope is available only when [advanced search is enabled](../user/search/advanced_search.md#enable-advanced-search).
@@ -1102,13 +1132,19 @@ Example response:
]
```
-NOTE:
+{{< alert type="note" >}}
+
`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521).
+{{< /alert >}}
+
### Scope: `commits`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
This scope is available only when [advanced search is enabled](../user/search/advanced_search.md#enable-advanced-search).
@@ -1143,8 +1179,11 @@ Example response:
### Scope: `blobs`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
This scope is available only when [advanced search is enabled](../user/search/advanced_search.md#enable-advanced-search).
diff --git a/doc/api/search_admin.md b/doc/api/search_admin.md
index bbb13e59484d6e97cd2de1113d9d087e977c6984..f93cb16a7bc77e67f4192d3447dd355b7e40c7a1 100644
--- a/doc/api/search_admin.md
+++ b/doc/api/search_admin.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Search admin API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120751) in GitLab 16.1
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120751) in GitLab 16.1
+
+{{< /history >}}
The search admin API returns information about [advanced search migrations](../integration/advanced_search/elasticsearch.md#advanced-search-migrations).
diff --git a/doc/api/secure_files.md b/doc/api/secure_files.md
index b37220ddfeaddebed8bf41eeda574a2aedab96dc..b4bddba111adc109d7db952ba9b2dbe04a7d3ed8 100644
--- a/doc/api/secure_files.md
+++ b/doc/api/secure_files.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project-level Secure Files API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) in GitLab 15.7. Feature flag `ci_secure_files` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) in GitLab 15.7. Feature flag `ci_secure_files` removed.
+
+{{< /history >}}
This feature is part of [Mobile DevOps](../ci/mobile_devops/_index.md) developed by [GitLab Incubation Engineering](https://handbook.gitlab.com/handbook/engineering/development/incubation/).
The feature is still in development, but you can:
diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md
index f52d0f384b4187348c447dc0ec4efbb6d09c9435..9badb3af03f57f76927b4e85fa038771d15d190f 100644
--- a/doc/api/sidekiq_metrics.md
+++ b/doc/api/sidekiq_metrics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sidekiq Metrics API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This API endpoint allows you to retrieve some information about the current state
of Sidekiq, its jobs, queues, and processes.
diff --git a/doc/api/snippet_repository_storage_moves.md b/doc/api/snippet_repository_storage_moves.md
index 208e812fe906e9e9ae7f938083e213b4cf897af0..31024e34640eb47eee87a447de09ab4319d8d805 100644
--- a/doc/api/snippet_repository_storage_moves.md
+++ b/doc/api/snippet_repository_storage_moves.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Snippet repository storage moves API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Snippet repositories can be moved between storages. This API can help you when
[migrating to Gitaly Cluster](../administration/gitaly/_index.md#migrate-to-gitaly-cluster), for
diff --git a/doc/api/snippets.md b/doc/api/snippets.md
index 13d046336e9d9f909eaf45cdd5d1172793e092e7..3bfda6c0741c5dbbf1a957efade10c48588186d2 100644
--- a/doc/api/snippets.md
+++ b/doc/api/snippets.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Snippets API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Snippets API operates on [snippets](../user/snippets.md). Related APIs exist for
[project snippets](project_snippets.md) and
@@ -210,9 +213,12 @@ Hello World snippet
Create a new snippet.
-NOTE:
+{{< alert type="note" >}}
+
The user must have permission to create new snippets.
+{{< /alert >}}
+
```plaintext
POST /snippets
```
@@ -295,9 +301,12 @@ Example response:
Update an existing snippet.
-NOTE:
+{{< alert type="note" >}}
+
The user must have permission to change an existing snippet.
+{{< /alert >}}
+
```plaintext
PUT /snippets/:id
```
@@ -477,7 +486,11 @@ Example response:
## List all snippets
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419640) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419640) in GitLab 16.3.
+
+{{< /history >}}
List all snippets the current user has access to.
Users with the Administrator or Auditor access levels can see all snippets
@@ -585,9 +598,12 @@ Example response:
## Get user agent details
-NOTE:
+{{< alert type="note" >}}
+
Available only for administrators.
+{{< /alert >}}
+
```plaintext
GET /snippets/:id/user_agent_detail
```
diff --git a/doc/api/statistics.md b/doc/api/statistics.md
index c6b0606cde5a638c2350692a4d244242450a06ed..7d41ec49747fb2260c16af433f958413f350dd13 100644
--- a/doc/api/statistics.md
+++ b/doc/api/statistics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Application statistics API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to retrieve statistics from your GitLab instance.
@@ -19,12 +22,15 @@ Prerequisites:
Gets details on the current application statistics.
-NOTE:
+{{< alert type="note" >}}
+
For values less than 10,000, this endpoint returns an exact count. For values of 10,000 and greater, this endpoint only returns approximate data when
[TablesampleCountStrategy](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/count/tablesample_count_strategy.rb?ref_type=heads#L16)
and [ReltuplesCountStrategy](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/count/reltuples_count_strategy.rb?ref_type=heads)
strategies are used for calculations.
+{{< /alert >}}
+
```plaintext
GET /application/statistics
```
diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md
index d76c2c7ee7bddf78998e49c3d476aaf09f8680fd..0bdc0dcf6aa881ce77a9ebd9c5ac7cbbf1b89cc3 100644
--- a/doc/api/status_checks.md
+++ b/doc/api/status_checks.md
@@ -1,13 +1,16 @@
---
stage: Security Risk Management
group: Security Policies
-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"
+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
title: External Status Checks API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Get project external status check services
@@ -53,10 +56,13 @@ You can create a new external status check service for a project using the follo
POST /projects/:id/external_status_checks
```
-WARNING:
+{{< alert type="warning" >}}
+
External status checks send information about all applicable merge requests to the
defined external service. This includes confidential merge requests.
+{{< /alert >}}
+
| Attribute | Type | Required | Description |
|------------------------|------------------|----------|------------------------------------------------|
| `id` | integer | yes | ID of a project |
@@ -129,8 +135,12 @@ GET /projects/:id/merge_requests/:merge_request_iid/status_checks
## Set status of an external status check
-> - Support for `failed` and `passed` [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/353836) in GitLab 15.0
-> - Support for `pending` in GitLab 16.5 [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/413723) in GitLab 16.5
+{{< history >}}
+
+- Support for `failed` and `passed` [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/353836) in GitLab 15.0
+- Support for `pending` in GitLab 16.5 [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/413723) in GitLab 16.5
+
+{{< /history >}}
For a single merge request, use the API to inform GitLab that a merge request has passed a check by an external service.
To set the status of an external check, the personal access token used must belong to a user with at least the Developer role on the target project of the merge request.
@@ -151,12 +161,19 @@ POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses
| `external_status_check_id` | integer | yes | ID of an external status check |
| `status` | string | no | Set to `pending` to mark the check as pending, `passed` to pass the check, or `failed` to fail it |
-NOTE:
+{{< alert type="note" >}}
+
`sha` must be the SHA at the `HEAD` of the merge request's source branch.
+{{< /alert >}}
+
## Retry failed status check for a merge request
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383200) in GitLab 15.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383200) in GitLab 15.7.
+
+{{< /history >}}
For a single merge request, retry the specified failed external status check. Even
though the merge request hasn't changed, this endpoint resends the current state of
diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md
index f38f36debe8efa4ff2cb56f011aade97e1db23dc..1fa261647df51d2f22a0fc48f62f216adee61034 100644
--- a/doc/api/suggestions.md
+++ b/doc/api/suggestions.md
@@ -1,13 +1,16 @@
---
stage: Create
group: Source Code
-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"
+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
title: Suggest Changes API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page describes the API for [suggesting changes](../user/project/merge_requests/reviews/suggestions.md).
diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md
index b9fff377249fa835eeb7f43edf0245d262b1ee4e..75d6233dc1c44437f5ef60d6869c51fe303a2fe9 100644
--- a/doc/api/system_hooks.md
+++ b/doc/api/system_hooks.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: System hooks API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
All methods require administrator authorization.
@@ -210,7 +213,11 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git
## Set a URL variable
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+
+{{< /history >}}
```plaintext
PUT /hooks/:hook_id/url_variables/:key
@@ -228,7 +235,11 @@ On success, this endpoint returns the response code `204 No Content`.
## Delete a URL variable
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90310) in GitLab 15.2.
+
+{{< /history >}}
```plaintext
DELETE /hooks/:hook_id/url_variables/:key
diff --git a/doc/api/tags.md b/doc/api/tags.md
index 40304fb1cef70c7c8e8bf272a9f2b24eece51cdf..06a43e612c630ba1e490b5eba2955bda3a3f959b 100644
--- a/doc/api/tags.md
+++ b/doc/api/tags.md
@@ -2,26 +2,36 @@
stage: Create
group: Source Code
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
-description: "Documentation for the REST API for Git tags in GitLab."
+description: Documentation for the REST API for Git tags in GitLab.
title: Tags API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## List project repository tags
-> - `version` value for the `order_by` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95150) in GitLab 15.4.
-> - `created_at` response attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451011) in GitLab 16.11.
+{{< history >}}
+
+- `version` value for the `order_by` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95150) in GitLab 15.4.
+- `created_at` response attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451011) in GitLab 16.11.
+
+{{< /history >}}
Get a list of repository tags from a project, sorted by update date and time in
descending order.
-NOTE:
+{{< alert type="note" >}}
+
If the repository is publicly accessible, authentication
(`--header "PRIVATE-TOKEN: <your_access_token>"`) is not required.
+{{< /alert >}}
+
```plaintext
GET /projects/:id/repository/tags
```
@@ -76,7 +86,11 @@ Example Response:
## Get a single repository tag
-> - `created_at` response attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451011) in GitLab 16.11.
+{{< history >}}
+
+- `created_at` response attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451011) in GitLab 16.11.
+
+{{< /history >}}
Get a specific repository tag determined by its name. This endpoint can be
accessed without authentication if the repository is publicly accessible.
@@ -128,7 +142,11 @@ Example Response:
## Create a new tag
-> - `created_at` response attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451011) in GitLab 16.11.
+{{< history >}}
+
+- `created_at` response attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451011) in GitLab 16.11.
+
+{{< /history >}}
Creates a new tag in the repository that points to the supplied ref.
@@ -210,7 +228,11 @@ Parameters:
## Get X.509 signature of a tag
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106578) in GitLab 15.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106578) in GitLab 15.7.
+
+{{< /history >}}
Get the [X.509 signature from a tag](../user/project/repository/signed_commits/x509.md),
if it is signed. Unsigned tags return a `404 Not Found` response.
diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md
index 0893e7666472e2bb0fa9aa0a882a56a6eca186e1..123d55a02dd7da85f18a96ba08c027b0f242f654 100644
--- a/doc/api/templates/dockerfiles.md
+++ b/doc/api/templates/dockerfiles.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dockerfiles API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides an API endpoint for Dockerfile templates available to the entire instance.
Default templates are defined at
@@ -18,9 +21,12 @@ Users with the Guest role can't access the Dockerfiles templates. For more infor
## Override Dockerfile API templates
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In [GitLab Premium and Ultimate](https://about.gitlab.com/pricing/) tiers, GitLab instance
administrators can override templates in the
diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md
index 54a6564c93c5bf27fd1c8d85eecf5284ebb37aa8..bc3b2418fa3b0377ad794a5b6bc629376a0cebff 100644
--- a/doc/api/templates/gitignores.md
+++ b/doc/api/templates/gitignores.md
@@ -2,12 +2,15 @@
stage: Create
group: Source Code
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
-title: '.gitignore API'
+title: .gitignore API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In GitLab, the `/gitignores` endpoint returns a list of Git `.gitignore` templates. For more information,
see the [Git documentation for `.gitignore`](https://git-scm.com/docs/gitignore).
diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md
index 3e5d359c769b646bc992a96a6a5efbf581878264..7d83f0b594106c636527b286bc33a6f34da7cfd3 100644
--- a/doc/api/templates/gitlab_ci_ymls.md
+++ b/doc/api/templates/gitlab_ci_ymls.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab CI YAML API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In GitLab, there is an API endpoint available to work with GitLab CI/CD YAML. For more
information on CI/CD pipeline configuration in GitLab, see the
diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md
index 355c88c152e51233280a071447fceee3a21180dd..0d76001e4557b5e4c112a5c0f12321e61c1edd40 100644
--- a/doc/api/templates/licenses.md
+++ b/doc/api/templates/licenses.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Licenses API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In GitLab, there is an API endpoint available for working with various open
source license templates. For more information on the terms of various
@@ -129,10 +132,13 @@ GET /templates/licenses/:key
| `project` | string | no | The copyrighted project name |
| `fullname` | string | no | The full-name of the copyright holder |
-NOTE:
+{{< alert type="note" >}}
+
If you omit the `fullname` parameter but authenticate your request, the name of
the authenticated user replaces the copyright holder placeholder.
+{{< /alert >}}
+
Example request:
```shell
diff --git a/doc/api/todos.md b/doc/api/todos.md
index 06b6eccf7e032f6033d5463f3a118d000acbfb0b..5d9d0380fc1f113a9c9e7151e24504116f7f9374 100644
--- a/doc/api/todos.md
+++ b/doc/api/todos.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab To-Do List API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Interact with [to-do items](../user/todos.md) using the REST API.
diff --git a/doc/api/topics.md b/doc/api/topics.md
index 00ff45d9e7d49314cb673966323ce3a77529c1b9..93ebcffc4af455864c1472d86c757bbc8f2d962c 100644
--- a/doc/api/topics.md
+++ b/doc/api/topics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Topics API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Interact with project topics using the REST API.
@@ -244,7 +247,11 @@ curl --request DELETE \
## Merge topics
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95501) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95501) in GitLab 15.4.
+
+{{< /history >}}
You must be an administrator to merge a source topic into a target topic.
When you merge topics, you delete the source topic and move all assigned projects to the target topic.
@@ -260,9 +267,12 @@ Supported attributes:
| `source_topic_id` | integer | Yes | ID of source project topic |
| `target_topic_id` | integer | Yes | ID of target project topic |
-NOTE:
+{{< alert type="note" >}}
+
The `source_topic_id` and `target_topic_id` must belong to the same organization.
+{{< /alert >}}
+
Example request:
```shell
diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md
index e8e15d6b8db123b3ffe481a8f95f6c92fd57b9d3..40729eb68ea5aaa04c2eee1cab3c2aa635dc75aa 100644
--- a/doc/api/usage_data.md
+++ b/doc/api/usage_data.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Service Ping API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Service Ping API is associated with [Service Ping](../development/internal_analytics/service_ping/_index.md).
## Export Service Ping data
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141446) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141446) in GitLab 16.9.
+
+{{< /history >}}
Requires a personal access token with `read_service_ping` scope.
@@ -89,8 +96,12 @@ Example response:
This action is behind the `usage_data_queries_api` feature flag and is available only for the GitLab instance [Administrator](../user/permissions.md) users.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57016) in GitLab 13.11.
-> - [Deployed behind a feature flag](../user/feature_flags.md) named `usage_data_queries_api`, disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57016) in GitLab 13.11.
+- [Deployed behind a feature flag](../user/feature_flags.md) named `usage_data_queries_api`, disabled by default.
+
+{{< /history >}}
Return all of the raw SQL queries used to compute Service Ping.
@@ -153,8 +164,12 @@ Example response:
This action is behind the `usage_data_non_sql_metrics` feature flag and is available only for the GitLab instance [Administrator](../user/permissions.md) users.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57050) in GitLab 13.11.
-> - [Deployed behind a feature flag](../user/feature_flags.md), named `usage_data_non_sql_metrics`, disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57050) in GitLab 13.11.
+- [Deployed behind a feature flag](../user/feature_flags.md), named `usage_data_non_sql_metrics`, disabled by default.
+
+{{< /history >}}
Return all non-SQL metrics data used in the Service ping.
diff --git a/doc/api/user_email_addresses.md b/doc/api/user_email_addresses.md
index 19ec18b875b7a81e03767523ed33dd62f0daae81..5d703a97ab23b20d11b736ad7c449a803690da54 100644
--- a/doc/api/user_email_addresses.md
+++ b/doc/api/user_email_addresses.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User email addresses API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with email addresses for user accounts. For more information, see [User account](../user/profile/_index.md).
@@ -42,9 +45,12 @@ Example response:
## List all email addresses for a user
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Lists all email addresses for a given user account.
@@ -123,9 +129,12 @@ error occurs a `400 Bad Request` is returned with a message explaining the error
## Add an email address for a user
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Adds an email address for a given user account.
@@ -172,9 +181,12 @@ Returns:
## Delete an email address for a user
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Deletes an email address for a given user account. You cannot delete a primary email address.
diff --git a/doc/api/user_follow_unfollow.md b/doc/api/user_follow_unfollow.md
index d4695caa703eeb93b23d6d5b3c41e216dedd0d1a..2601e96550b2bec559230c090f92a6d1c973168a 100644
--- a/doc/api/user_follow_unfollow.md
+++ b/doc/api/user_follow_unfollow.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User follow and unfollow API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to perform follower actions for user accounts. For more information, see [Follow users](../user/profile/_index.md#follow-users).
diff --git a/doc/api/user_keys.md b/doc/api/user_keys.md
index ff9ff4b5f3da54e0f3fd948da85d6851855911b4..e0198fc32a101073e91013a8d192d37dc315aa5c 100644
--- a/doc/api/user_keys.md
+++ b/doc/api/user_keys.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User SSH and GPG keys API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with SSH and GPG keys for users. For more information, see [SSH keys](../user/ssh.md) and [GPG keys](../user/project/repository/signed_commits/gpg.md).
@@ -143,7 +146,11 @@ Example response:
## Add an SSH key
-> - The `usage_type` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105551) in GitLab 15.7.
+{{< history >}}
+
+- The `usage_type` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105551) in GitLab 15.7.
+
+{{< /history >}}
Adds an SSH key for your user account.
@@ -195,13 +202,20 @@ Example response:
## Add an SSH key for a user
-> - The `usage_type` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105551) in GitLab 15.7.
+{{< history >}}
+
+- The `usage_type` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105551) in GitLab 15.7.
+
+{{< /history >}}
Adds an SSH key for a given user account.
-NOTE:
+{{< alert type="note" >}}
+
This also adds an audit event.
+{{< /alert >}}
+
Prerequisites:
- You must have administrator access to the instance.
diff --git a/doc/api/user_moderation.md b/doc/api/user_moderation.md
index 00e94dd18cf9e223255b7b86dd66e6b916e79e41..05848df650181cbb102a7e83d16056f901536408 100644
--- a/doc/api/user_moderation.md
+++ b/doc/api/user_moderation.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User moderation API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to moderate user accounts. For more information, see [Moderate users](../administration/moderate_users.md).
diff --git a/doc/api/user_service_accounts.md b/doc/api/user_service_accounts.md
index 3ae4e8454f57dec9e843a2a0feadb13e37fc1db4..f187dfa77bc42f2d915b2b8136908554467fa6e5 100644
--- a/doc/api/user_service_accounts.md
+++ b/doc/api/user_service_accounts.md
@@ -5,19 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Service account users API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with service accounts. For more information, see [Service accounts](../user/profile/service_accounts.md).
## List all service account users
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - List all service account users [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416729) in GitLab 17.1.
+{{< history >}}
+
+- List all service account users [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416729) in GitLab 17.1.
+
+{{< /history >}}
Lists all service account users.
@@ -63,8 +73,12 @@ Example response:
## Create a service account user
-> - Create a service account user was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/406782) in GitLab 16.1
-> - Username and name attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144841) in GitLab 16.10.
+{{< history >}}
+
+- Create a service account user was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/406782) in GitLab 16.1
+- Username and name attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144841) in GitLab 16.10.
+
+{{< /history >}}
Creates a service account user.
diff --git a/doc/api/user_tokens.md b/doc/api/user_tokens.md
index 11ca1db6b1112dd7d582c12299f676c0331982b1..a5b7ccc59e093d015579ddcbb61ca717b33d0040 100644
--- a/doc/api/user_tokens.md
+++ b/doc/api/user_tokens.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User tokens API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use this API to interact with personal access tokens and impersonation tokens. For more information, see [personal access tokens](../user/profile/personal_access_tokens.md) and [impersonation tokens](rest/authentication.md#impersonation-tokens).
## Create a personal access token for a user
-> - The `expires_at` attribute default was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120213) in GitLab 16.0.
+{{< history >}}
+
+- The `expires_at` attribute default was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120213) in GitLab 16.0.
+
+{{< /history >}}
Creates a personal access token for a given user.
@@ -65,7 +72,11 @@ Example response:
## Create a personal access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131923) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131923) in GitLab 16.5.
+
+{{< /history >}}
Creates a personal access token for your account. For security purposes, the token:
diff --git a/doc/api/users.md b/doc/api/users.md
index 34b9065ff272bf923eacc559c911e49eae1c8d03..8bc6ac5dd8fe68c856670fd78e03da126feffd0d 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Users API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can [manage your account](../user/profile/_index.md) and
[manage other users](../user/profile/account/create_accounts.md) by using the REST API.
@@ -20,7 +23,11 @@ Takes [pagination parameters](rest/_index.md#offset-based-pagination) `page` and
### As a regular user
-> - Keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419556) in GitLab 16.5.
+{{< history >}}
+
+- Keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419556) in GitLab 16.5.
+
+{{< /history >}}
```plaintext
GET /users
@@ -88,9 +95,12 @@ For example:
GET /users?username=jack_smith
```
-NOTE:
+{{< alert type="note" >}}
+
Username search is case insensitive.
+{{< /alert >}}
+
In addition, you can filter users based on the states `blocked` and `active`.
It does not support `active=false` or `blocked=false`.
@@ -140,14 +150,21 @@ GET /users?without_project_bots=true
### As an administrator
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
-> - The `scim_identities` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324247) in GitLab 16.1.
-> - The `auditors` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418023) in GitLab 16.2.
-> - The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
+- The `scim_identities` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324247) in GitLab 16.1.
+- The `auditors` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418023) in GitLab 16.2.
+- The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
+
+{{< /history >}}
```plaintext
GET /users
@@ -405,12 +422,19 @@ Example response:
### As an administrator
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
-> - The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
+{{< history >}}
+
+- The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
+- The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
+
+{{< /history >}}
Get a single user as an administrator.
@@ -483,9 +507,12 @@ Example response:
}
```
-NOTE:
+{{< alert type="note" >}}
+
The `plan` and `trial` parameters are only available on GitLab Enterprise Edition.
+{{< /alert >}}
+
Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see
the `shared_runners_minutes_limit`, `is_auditor`, and `extra_shared_runners_minutes_limit` parameters.
@@ -614,12 +641,19 @@ Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also se
### As an administrator
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
-> - The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
+{{< history >}}
+
+- The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
+- The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
+
+{{< /history >}}
Get your user details, or the details of another user.
@@ -693,11 +727,18 @@ parameters:
## Create a user
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - Ability to create an auditor user was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3.
+- Ability to create an auditor user was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3.
+
+{{< /history >}}
Create a user.
@@ -716,11 +757,14 @@ If `reset_password` and `force_random_password` are both `false`, then `password
`force_random_password` and `reset_password` take priority over `password`. Also, `reset_password` and
`force_random_password` can be used together.
-NOTE:
+{{< alert type="note" >}}
+
`private_profile` defaults to the value of the
[Set profiles of new users to private by default](../administration/settings/account_and_limit_settings.md#set-profiles-of-new-users-to-private-by-default) setting.
`bio` defaults to `""` instead of `null`.
+{{< /alert >}}
+
```plaintext
POST /users
```
@@ -766,11 +810,18 @@ Supported attributes:
## Modify a user
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - Ability to modify an auditor user was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3.
+- Ability to modify an auditor user was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3.
+
+{{< /history >}}
Modify an existing user.
@@ -830,9 +881,12 @@ For example, when renaming the email address to an existing one.
## Delete a user
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Delete a user.
@@ -1019,7 +1073,11 @@ Supported attributes:
## Upload an avatar for yourself
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148130) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148130) in GitLab 17.0.
+
+{{< /history >}}
Upload an avatar for yourself.
@@ -1137,9 +1195,12 @@ Example response:
## List a user's activity
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
@@ -1200,9 +1261,12 @@ Example response:
## List projects and groups that a user is a member of
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
@@ -1259,11 +1323,18 @@ Returns:
## Disable two-factor authentication for a user
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295260) in GitLab 15.2.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295260) in GitLab 15.2.
+
+{{< /history >}}
Prerequisites:
@@ -1299,9 +1370,12 @@ Returns:
## Create a runner linked to a user
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Create a runner linked to the current user.
@@ -1353,9 +1427,12 @@ Example response:
## Delete authentication identity from a user
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Delete a user's authentication identity using the provider name associated with that identity.
diff --git a/doc/api/version.md b/doc/api/version.md
index 53fd634ba158d592bf1bebe121ee3600bd1a2432..59f507bf198254940e5455597b213b228b0a605b 100644
--- a/doc/api/version.md
+++ b/doc/api/version.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Version API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
We recommend you use the [Metadata API](metadata.md) instead of the Version API.
It contains additional information and is aligned with the GraphQL metadata endpoint.
As of GitLab 15.5, the Version API is a mirror of the Metadata API.
+{{< /alert >}}
+
Retrieves version information for the GitLab instance. Responds with `200 OK` for
authenticated users.
diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md
index d48c6d2c21c13ad39c3891bb1c8938900f7906ff..464e3bc97b6494887d8a1bf10fda4fb82f45fcc0 100644
--- a/doc/api/vulnerabilities.md
+++ b/doc/api/vulnerabilities.md
@@ -5,28 +5,41 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Vulnerabilities API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - `last_edited_at` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
-> - `start_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
-> - `updated_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
-> - `last_edited_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
-> - `due_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- `last_edited_at` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- `start_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- `updated_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- `last_edited_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+- `due_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
The former Vulnerabilities API was renamed to Vulnerability Findings API
and its documentation was moved to [a different location](vulnerability_findings.md).
This document now describes the new Vulnerabilities API that provides access to
[Vulnerabilities](https://gitlab.com/groups/gitlab-org/-/epics/634).
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
This API is in the process of being deprecated and considered unstable.
The response payload may be subject to change or breakage
across GitLab releases. Use the
[GraphQL API](graphql/reference/_index.md#queryvulnerabilities) instead. For more information, see [GraphQL examples](#replace-vulnerability-rest-api-with-graphql).
+{{< /alert >}}
+
Every API call to vulnerabilities must be [authenticated](rest/authentication.md).
If an authenticated user does not have permission to
diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md
index 031b27b452a67986908f1d3af047fe5007c10d07..9f35245500cd587c8400f4fccb01a5c948bcff28 100644
--- a/doc/api/vulnerability_exports.md
+++ b/doc/api/vulnerability_exports.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Vulnerability export API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Every API call to vulnerability exports must be [authenticated](rest/authentication.md).
diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md
index ce4d47935f09cc3931a7bf888200a129c98e8a43..054d790515bf7f9bc77ca9bdeb0346723c4ac501 100644
--- a/doc/api/vulnerability_findings.md
+++ b/doc/api/vulnerability_findings.md
@@ -5,28 +5,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Vulnerability Findings API
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This API resource is renamed from Vulnerabilities to Vulnerability Findings because the Vulnerabilities are reserved
for serving [Vulnerability objects](https://gitlab.com/gitlab-org/gitlab/-/issues/13561).
To fix any broken integrations with the former Vulnerabilities API, change the `vulnerabilities` URL part to be
`vulnerability_findings`.
+{{< /alert >}}
+
Every API call to vulnerability findings must be [authenticated](rest/authentication.md).
If a user does not have permission to
[use the Project Security Dashboard](../user/permissions.md#project-members-permissions),
any request for vulnerability findings of this project returns a `403 Forbidden` status code.
-WARNING:
+{{< alert type="warning" >}}
+
This API is in the process of being deprecated and considered unstable.
The response payload may be subject to change or breakage
across GitLab releases. Use the
[GraphQL API](graphql/reference/_index.md#queryvulnerabilities) instead. For more information, see [GraphQL examples](vulnerabilities.md#replace-vulnerability-rest-api-with-graphql)
+{{< /alert >}}
+
## Vulnerability findings pagination
By default, `GET` requests return 20 results at a time because the API results
diff --git a/doc/api/web_commits.md b/doc/api/web_commits.md
index acd56d5502991a8905c985c75f0f5ceb9a45fcb7..8089682b27f9549252445485386dec7ea8f3bd6b 100644
--- a/doc/api/web_commits.md
+++ b/doc/api/web_commits.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Web Commits API
---
-DETAILS:
-**Tier:** Free
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442533) in GitLab 17.4.
+- Tier: Free
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442533) in GitLab 17.4.
+
+{{< /history >}}
Use this API to retrieve information about commits created with the Web UI.
diff --git a/doc/api/wikis.md b/doc/api/wikis.md
index 3bce7654fda1e9fca42ee5cff12be02362752452..c8c07c3843a4e16287504758563e237b808e5f2c 100644
--- a/doc/api/wikis.md
+++ b/doc/api/wikis.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project wikis API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The project [wikis](../user/project/wiki/_index.md) API is available only in APIv4.
An API for [group wikis](group_wikis.md) is also available.
diff --git a/doc/architecture/_index.md b/doc/architecture/_index.md
index 025f40af8ad0f9cc2db3853639c71c30d1f104bc..34f3afbfc3070428ccfa74b7348aa8db862f8884 100644
--- a/doc/architecture/_index.md
+++ b/doc/architecture/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/activity_pub/_index.md b/doc/architecture/blueprints/activity_pub/_index.md
index 376de4c3b6752c7f14969f5e4754b464309e910a..2763cff6a325829cb400d4896fa5028dd46c588d 100644
--- a/doc/architecture/blueprints/activity_pub/_index.md
+++ b/doc/architecture/blueprints/activity_pub/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/activity_pub/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/activity_pub/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ai_context_management/_index.md b/doc/architecture/blueprints/ai_context_management/_index.md
index 9e0b29416981c10270491a7c654342b244cc2c9a..81246494f3e5fcfde9d20b35315a2aa9bfbeccc4 100644
--- a/doc/architecture/blueprints/ai_context_management/_index.md
+++ b/doc/architecture/blueprints/ai_context_management/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_context_management/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_context_management/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ai_context_management/decisions/001_policy_on_the_client.md b/doc/architecture/blueprints/ai_context_management/decisions/001_policy_on_the_client.md
index 29ab10d223b0fad92db46fab0b2c6523e4863110..c8eae481b86cc051949f7e31231e5a5e44f7fbb5 100644
--- a/doc/architecture/blueprints/ai_context_management/decisions/001_policy_on_the_client.md
+++ b/doc/architecture/blueprints/ai_context_management/decisions/001_policy_on_the_client.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_context_management/decisions/001_policy_on_the_client/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_context_management/decisions/001_policy_on_the_client/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ai_gateway/_index.md b/doc/architecture/blueprints/ai_gateway/_index.md
index b0c8f0836d57ea2ae57698646b74920cd087f44b..ac77dab52a2ba6f54f09edb20c2798f4e3c5aeb8 100644
--- a/doc/architecture/blueprints/ai_gateway/_index.md
+++ b/doc/architecture/blueprints/ai_gateway/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_gateway/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_gateway/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ai_gateway/decisions/001_direct_connections.md b/doc/architecture/blueprints/ai_gateway/decisions/001_direct_connections.md
index e0ac0b5a2e0427f1a894e9600308e3f9a83beb6b..5e2586c83950ef478899c8d6b0eccf5f663d722e 100644
--- a/doc/architecture/blueprints/ai_gateway/decisions/001_direct_connections.md
+++ b/doc/architecture/blueprints/ai_gateway/decisions/001_direct_connections.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_gateway/001_direct_connections/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_gateway/001_direct_connections/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ai_gateway/decisions/002_proxy.md b/doc/architecture/blueprints/ai_gateway/decisions/002_proxy.md
index a4edf3d8f965bcd050bf344570fe915826c7b448..927ff219d8efed541fc4517bbeb67c162d61435c 100644
--- a/doc/architecture/blueprints/ai_gateway/decisions/002_proxy.md
+++ b/doc/architecture/blueprints/ai_gateway/decisions/002_proxy.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_gateway/002_proxy/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ai_gateway/002_proxy/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/autoflow/_index.md b/doc/architecture/blueprints/autoflow/_index.md
index 45944f6be086985bc6c48ee4be93cfec490251f5..37c7ce96507b940e09fd20bcf563112176901f9c 100644
--- a/doc/architecture/blueprints/autoflow/_index.md
+++ b/doc/architecture/blueprints/autoflow/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/autoflow/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/autoflow/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/autoflow/relation_to_ci.md b/doc/architecture/blueprints/autoflow/relation_to_ci.md
index a6e03b26641048e73774221c1cc59e57ce03d102..1f84dd85ff743c5f1e6741ffbc99e462fb484018 100644
--- a/doc/architecture/blueprints/autoflow/relation_to_ci.md
+++ b/doc/architecture/blueprints/autoflow/relation_to_ci.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/autoflow/relation_to_ci/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/autoflow/relation_to_ci/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/backup_and_restore/_index.md b/doc/architecture/blueprints/backup_and_restore/_index.md
index bafc6646654b1bfb3d22a9a2baf7aad5c2ab9a96..2523b053bf56f9f7fc35b125c3368ceeed150ac4 100644
--- a/doc/architecture/blueprints/backup_and_restore/_index.md
+++ b/doc/architecture/blueprints/backup_and_restore/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/backup_and_restore/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/backup_and_restore/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/backup_and_restore/glossary.md b/doc/architecture/blueprints/backup_and_restore/glossary.md
index 012d797e1a4fb7cec865df40046ea70bdacaa2ea..64ce22563fe4e4e3c06732baf0e443140829a9da 100644
--- a/doc/architecture/blueprints/backup_and_restore/glossary.md
+++ b/doc/architecture/blueprints/backup_and_restore/glossary.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/backup_and_restore/glossary/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/backup_and_restore/glossary/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/bundle_uri/_index.md b/doc/architecture/blueprints/bundle_uri/_index.md
index 66915b3025127158c2202c023c8c77417430407f..4683f2b850c0d063c64baa091bb4710f28214200 100644
--- a/doc/architecture/blueprints/bundle_uri/_index.md
+++ b/doc/architecture/blueprints/bundle_uri/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/bundle_uri/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/bundle_uri/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/capacity_planning/_index.md b/doc/architecture/blueprints/capacity_planning/_index.md
index 5d334a125bae53b704c42a398d3edaa8244e0841..8877806a68ffe7bba6404721b05a17f9e6abcdcd 100644
--- a/doc/architecture/blueprints/capacity_planning/_index.md
+++ b/doc/architecture/blueprints/capacity_planning/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/capacity_planning/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/capacity_planning/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cdot_orders/_index.md b/doc/architecture/blueprints/cdot_orders/_index.md
index bdb45e5d10623e21f4885a88c07890c229427203..50531c538bb5cd8ca917b0063b138a921f88e186 100644
--- a/doc/architecture/blueprints/cdot_orders/_index.md
+++ b/doc/architecture/blueprints/cdot_orders/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cdot_orders/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cdot_orders/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cdot_plan_managment/_index.md b/doc/architecture/blueprints/cdot_plan_managment/_index.md
index deec5782d76b17ad4a12ec151bf42d9cc56a91ff..d15f1929bbbe859d19044311b53c3ff818d0f0e6 100644
--- a/doc/architecture/blueprints/cdot_plan_managment/_index.md
+++ b/doc/architecture/blueprints/cdot_plan_managment/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cdot_plan_managment/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cdot_plan_managment/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/_index.md b/doc/architecture/blueprints/cells/_index.md
index 382d070652e58f66fa501ecbe0f96bedfa9bee59..f3521601b94e8a1f2d682d2e601dc30a20dfc1c9 100644
--- a/doc/architecture/blueprints/cells/_index.md
+++ b/doc/architecture/blueprints/cells/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/001_routing_technology.md b/doc/architecture/blueprints/cells/decisions/001_routing_technology.md
index d479e2c04650ec2d6ad2891e37cc77b84d1c56e6..54d9857c2c1c540f50b18e1f8c8ab55e0cb5ddc1 100644
--- a/doc/architecture/blueprints/cells/decisions/001_routing_technology.md
+++ b/doc/architecture/blueprints/cells/decisions/001_routing_technology.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/001_routing_technology/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/001_routing_technology/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/002_gcp_project_boundary.md b/doc/architecture/blueprints/cells/decisions/002_gcp_project_boundary.md
index 80f8ec2a81150873953ae3c625e94521cd02b805..8fff01e502031ca188aae4ea34f52dd8af87d951 100644
--- a/doc/architecture/blueprints/cells/decisions/002_gcp_project_boundary.md
+++ b/doc/architecture/blueprints/cells/decisions/002_gcp_project_boundary.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/002_gcp_project_boundary/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/002_gcp_project_boundary/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/003_num_gke_clusters_per_cell.md b/doc/architecture/blueprints/cells/decisions/003_num_gke_clusters_per_cell.md
index 0b59dcd726c9ff9ddac7ed51779f077cd415700d..7226eab86a476fceb920ec8dc7ee1100c1dd09f0 100644
--- a/doc/architecture/blueprints/cells/decisions/003_num_gke_clusters_per_cell.md
+++ b/doc/architecture/blueprints/cells/decisions/003_num_gke_clusters_per_cell.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/003_num_gke_clusters_per_cell/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/003_num_gke_clusters_per_cell/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/004_vpc_subnet_design.md b/doc/architecture/blueprints/cells/decisions/004_vpc_subnet_design.md
index d1795b9ec05ba22c90f889dd41d8598ca6b7c8fa..1b7a1273da7c66ed19fcf710f77f174c4227d4ca 100644
--- a/doc/architecture/blueprints/cells/decisions/004_vpc_subnet_design.md
+++ b/doc/architecture/blueprints/cells/decisions/004_vpc_subnet_design.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/004_vpc_subnet_design/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/004_vpc_subnet_design/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/005_flexible_reference_architectures.md b/doc/architecture/blueprints/cells/decisions/005_flexible_reference_architectures.md
index db459d8598f49f11da9f516f6bb6a1b1163e3dc6..a4ea7efceb1eca9d5cee33a51bf61a958853f092 100644
--- a/doc/architecture/blueprints/cells/decisions/005_flexible_reference_architectures.md
+++ b/doc/architecture/blueprints/cells/decisions/005_flexible_reference_architectures.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/005_flexible_reference_architectures/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/005_flexible_reference_architectures/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/006_disaster_recovery_geo.md b/doc/architecture/blueprints/cells/decisions/006_disaster_recovery_geo.md
index 88bbe0ba4398e3335e23c745c228bdde4cea03b2..e7a54e2f3541dd3e23759d247dc43bd6b3ac6b94 100644
--- a/doc/architecture/blueprints/cells/decisions/006_disaster_recovery_geo.md
+++ b/doc/architecture/blueprints/cells/decisions/006_disaster_recovery_geo.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/006_disaster_recovery_geo/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/006_disaster_recovery_geo/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/007_internal_customers.md b/doc/architecture/blueprints/cells/decisions/007_internal_customers.md
index 283265fe2f7f21d3969e460b050f89c164c97759..171563ef733aadd21e9dd11fb7079312bcb74715 100644
--- a/doc/architecture/blueprints/cells/decisions/007_internal_customers.md
+++ b/doc/architecture/blueprints/cells/decisions/007_internal_customers.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/007_internal_customers/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/007_internal_customers/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/008_database_sequences.md b/doc/architecture/blueprints/cells/decisions/008_database_sequences.md
index 1a406d8c31cb341766f0a251db0cf346027e389c..e0be384b1367ffe23642628825837fda5b0d0bcb 100644
--- a/doc/architecture/blueprints/cells/decisions/008_database_sequences.md
+++ b/doc/architecture/blueprints/cells/decisions/008_database_sequences.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/008_database_sequences/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/008_database_sequences/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/009_cell_initial_sizing.md b/doc/architecture/blueprints/cells/decisions/009_cell_initial_sizing.md
index dbbeadca074bea659d0836a2427fb4f1ce71039e..16d642d8097e4eb996507d3ef721eae402df7b7b 100644
--- a/doc/architecture/blueprints/cells/decisions/009_cell_initial_sizing.md
+++ b/doc/architecture/blueprints/cells/decisions/009_cell_initial_sizing.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/009_cell_initial_sizing/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/009_cell_initial_sizing/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/decisions/010_http_router_rules_and_cache.md b/doc/architecture/blueprints/cells/decisions/010_http_router_rules_and_cache.md
index 84f1233860d877ecd643f3bf28800dbf36aea704..36edc3f79907d48a4d23b8d7fe688c52d1307c3e 100644
--- a/doc/architecture/blueprints/cells/decisions/010_http_router_rules_and_cache.md
+++ b/doc/architecture/blueprints/cells/decisions/010_http_router_rules_and_cache.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/010_http_router_rules_and_cache/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/decisions/010_http_router_rules_and_cache/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/diagrams/_index.md b/doc/architecture/blueprints/cells/diagrams/_index.md
index 17206081cb7c2986db88a1a7e65c298e45037b99..dc5bbeadb45a8bd3c8d4663b4a4fd9a880587c43 100644
--- a/doc/architecture/blueprints/cells/diagrams/_index.md
+++ b/doc/architecture/blueprints/cells/diagrams/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/diagrams/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/diagrams/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/feature_flags.md b/doc/architecture/blueprints/cells/feature_flags.md
index fcbc560506a5c716b2e5bb7b9a24e060a51f9b77..16074e1293cb6fefa3450b326f9ce166b0d566c2 100644
--- a/doc/architecture/blueprints/cells/feature_flags.md
+++ b/doc/architecture/blueprints/cells/feature_flags.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/feature_flags/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/feature_flags/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/goals.md b/doc/architecture/blueprints/cells/goals.md
index 1afc02f5f5ed9e847f1df7622a68ba144f2b3862..aea986ab770efb8e58e93c53b128fb261f25e455 100644
--- a/doc/architecture/blueprints/cells/goals.md
+++ b/doc/architecture/blueprints/cells/goals.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/goals/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/goals/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/http_routing_service.md b/doc/architecture/blueprints/cells/http_routing_service.md
index 4e91e855978ec1c78bd1072ef8c25a7af33b6fd0..441ffe81cdf7406657ca339adcbe182566e27bb2 100644
--- a/doc/architecture/blueprints/cells/http_routing_service.md
+++ b/doc/architecture/blueprints/cells/http_routing_service.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/http_routing_service/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/http_routing_service/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/admin-area.md b/doc/architecture/blueprints/cells/impacted_features/admin-area.md
index 0fd6816a144193218a4709ce8eab2b8d026b7b4f..214be432834ee5ce987d81d3f33f9728ca8f6961 100644
--- a/doc/architecture/blueprints/cells/impacted_features/admin-area.md
+++ b/doc/architecture/blueprints/cells/impacted_features/admin-area.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/admin-area/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/admin-area/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/agent-for-kubernetes.md b/doc/architecture/blueprints/cells/impacted_features/agent-for-kubernetes.md
index 04813f18c580ef5541dc5052316c2bd3d850f465..015fe1617a80d86b1c219754426936d076f22763 100644
--- a/doc/architecture/blueprints/cells/impacted_features/agent-for-kubernetes.md
+++ b/doc/architecture/blueprints/cells/impacted_features/agent-for-kubernetes.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/agent-for-kubernetes/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/agent-for-kubernetes/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/backups.md b/doc/architecture/blueprints/cells/impacted_features/backups.md
index be86b05b59efffc5a806387e42d3042281119f47..ca8b789e6676e75941658aeb661965f7278aefb5 100644
--- a/doc/architecture/blueprints/cells/impacted_features/backups.md
+++ b/doc/architecture/blueprints/cells/impacted_features/backups.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/backups/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/backups/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/ci-cd-catalog.md b/doc/architecture/blueprints/cells/impacted_features/ci-cd-catalog.md
index 79a235db2b8bfed47589364af44c3627624a4012..e759ad60663feb6173a1b47eb4b27b4db893fae4 100644
--- a/doc/architecture/blueprints/cells/impacted_features/ci-cd-catalog.md
+++ b/doc/architecture/blueprints/cells/impacted_features/ci-cd-catalog.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/ci-cd-catalog/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/ci-cd-catalog/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/ci-runners.md b/doc/architecture/blueprints/cells/impacted_features/ci-runners.md
index 28e483a8adf8d1b74e555b5a8552d0ab5f8823d4..a3afb8f98661d3c80bba41ee1ac9b329fa93c280 100644
--- a/doc/architecture/blueprints/cells/impacted_features/ci-runners.md
+++ b/doc/architecture/blueprints/cells/impacted_features/ci-runners.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/ci-runners/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/ci-runners/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/container-registry.md b/doc/architecture/blueprints/cells/impacted_features/container-registry.md
index 827682bdcb39afb0d7e0d1cb2726ff06a2792b6b..03a10d167c855ccf1b4c2070a97b29d7595f5d65 100644
--- a/doc/architecture/blueprints/cells/impacted_features/container-registry.md
+++ b/doc/architecture/blueprints/cells/impacted_features/container-registry.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/container-registry/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/container-registry/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/contributions-forks.md b/doc/architecture/blueprints/cells/impacted_features/contributions-forks.md
index d0e34a2c5a369a7d15ad7b8e2139a0092ccc4414..e7e754676c859bedab967d8f24f0ed9d2059e4ef 100644
--- a/doc/architecture/blueprints/cells/impacted_features/contributions-forks.md
+++ b/doc/architecture/blueprints/cells/impacted_features/contributions-forks.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/contributions-forks/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/contributions-forks/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/data-migration.md b/doc/architecture/blueprints/cells/impacted_features/data-migration.md
index 32c2614098d2286aac89fc6b6edfd83aadd14319..29f1d8d2b554ef7259e8aa9d38725e4eb0b342f5 100644
--- a/doc/architecture/blueprints/cells/impacted_features/data-migration.md
+++ b/doc/architecture/blueprints/cells/impacted_features/data-migration.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/data-migration/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/data-migration/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/data-pipeline-ingestion.md b/doc/architecture/blueprints/cells/impacted_features/data-pipeline-ingestion.md
index db5166cfbd169ed38d37509c09f64c26caddf4af..b44983995ff2e0547f54344e3f8eb8d716f8a80b 100644
--- a/doc/architecture/blueprints/cells/impacted_features/data-pipeline-ingestion.md
+++ b/doc/architecture/blueprints/cells/impacted_features/data-pipeline-ingestion.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/data-pipeline-ingestion/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/data-pipeline-ingestion/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/database-sequences.md b/doc/architecture/blueprints/cells/impacted_features/database-sequences.md
index 12c1620e9c14ca6fdca0ecb4f33afe1fa3eea8d5..263378165cacda6bbfabb2f71b38b13911cfc657 100644
--- a/doc/architecture/blueprints/cells/impacted_features/database-sequences.md
+++ b/doc/architecture/blueprints/cells/impacted_features/database-sequences.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/database-sequences/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/database-sequences/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/explore.md b/doc/architecture/blueprints/cells/impacted_features/explore.md
index bf9de37a58d77aa9ec0aab5e36eca9a2218f6211..f2f9be3fa5276f5c44085557cb6268fa0f19afe3 100644
--- a/doc/architecture/blueprints/cells/impacted_features/explore.md
+++ b/doc/architecture/blueprints/cells/impacted_features/explore.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/explore/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/explore/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/git-access.md b/doc/architecture/blueprints/cells/impacted_features/git-access.md
index 25d992e77a391ecd94191ebef701d1f51cf4beb9..12dfe37c03cde0a738fe4e8cac1810c2956483bc 100644
--- a/doc/architecture/blueprints/cells/impacted_features/git-access.md
+++ b/doc/architecture/blueprints/cells/impacted_features/git-access.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/git-access/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/git-access/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/gitlab-pages.md b/doc/architecture/blueprints/cells/impacted_features/gitlab-pages.md
index 5cde4560bdd5b573295dd47bc80685eef32911c1..315c4809abfc7f4afaea4d15c4f52a1512405713 100644
--- a/doc/architecture/blueprints/cells/impacted_features/gitlab-pages.md
+++ b/doc/architecture/blueprints/cells/impacted_features/gitlab-pages.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/gitlab-pages/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/gitlab-pages/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/global-search.md b/doc/architecture/blueprints/cells/impacted_features/global-search.md
index 32fa424f4a09df0bb2d0b3fa752fe486b762f348..c167c0e960247454cd2227e7ce66cb42434ababe 100644
--- a/doc/architecture/blueprints/cells/impacted_features/global-search.md
+++ b/doc/architecture/blueprints/cells/impacted_features/global-search.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/global-search/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/global-search/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/graphql.md b/doc/architecture/blueprints/cells/impacted_features/graphql.md
index c98dd0420bc6f1125eb0e167ace828599bd12618..b003ee990c56f0579ddb37de4772ba2474649444 100644
--- a/doc/architecture/blueprints/cells/impacted_features/graphql.md
+++ b/doc/architecture/blueprints/cells/impacted_features/graphql.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/graphql/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/graphql/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/group-transfer.md b/doc/architecture/blueprints/cells/impacted_features/group-transfer.md
index 731711eabf9b4e50ce83f369a129c215a0372671..d45d7679141f1b7844392c2d193529c85e966030 100644
--- a/doc/architecture/blueprints/cells/impacted_features/group-transfer.md
+++ b/doc/architecture/blueprints/cells/impacted_features/group-transfer.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/group-transfer/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/group-transfer/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/issues.md b/doc/architecture/blueprints/cells/impacted_features/issues.md
index e2d702aedf3244df2974ad8ad3991c05955ed1a7..a26731102d40c2ab6955314b14ff6e9b7323925d 100644
--- a/doc/architecture/blueprints/cells/impacted_features/issues.md
+++ b/doc/architecture/blueprints/cells/impacted_features/issues.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/issues/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/issues/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/merge-requests.md b/doc/architecture/blueprints/cells/impacted_features/merge-requests.md
index 85130c73d8d570e5963ceb3ea3c12e2edc7be081..3eb4d28c6935a9c6b647da0349652dca67464995 100644
--- a/doc/architecture/blueprints/cells/impacted_features/merge-requests.md
+++ b/doc/architecture/blueprints/cells/impacted_features/merge-requests.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/merge-requests/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/merge-requests/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/organizations.md b/doc/architecture/blueprints/cells/impacted_features/organizations.md
index d719580812081f4973270d2b0fd4e90817b7a2ae..097b70e5dce34b89ce1bb5f9385bd3240d3f4b6c 100644
--- a/doc/architecture/blueprints/cells/impacted_features/organizations.md
+++ b/doc/architecture/blueprints/cells/impacted_features/organizations.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/organizations/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/organizations/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/personal-access-tokens.md b/doc/architecture/blueprints/cells/impacted_features/personal-access-tokens.md
index 361e740fa92c443cab916151053f2c1a093a73ab..894d5f5953bf8dc6088b2e81ff84a43912c7ccaa 100644
--- a/doc/architecture/blueprints/cells/impacted_features/personal-access-tokens.md
+++ b/doc/architecture/blueprints/cells/impacted_features/personal-access-tokens.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/personal-access-tokens/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/personal-access-tokens/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/personal-namespaces.md b/doc/architecture/blueprints/cells/impacted_features/personal-namespaces.md
index 6e1d8c9c7437e2814e779dffd7b0a55fddc8d7bd..8bf5f2aaa482d81edce2b033b8e4a96a520564ee 100644
--- a/doc/architecture/blueprints/cells/impacted_features/personal-namespaces.md
+++ b/doc/architecture/blueprints/cells/impacted_features/personal-namespaces.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/personal-namespaces/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/personal-namespaces/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/project-transfer.md b/doc/architecture/blueprints/cells/impacted_features/project-transfer.md
index a55ee1a830269f950d78759afb0fab88127289ac..affc748a2fe943fc5f88e82684d88c69db39f449 100644
--- a/doc/architecture/blueprints/cells/impacted_features/project-transfer.md
+++ b/doc/architecture/blueprints/cells/impacted_features/project-transfer.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/project-transfer/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/project-transfer/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/router-endpoints-classification.md b/doc/architecture/blueprints/cells/impacted_features/router-endpoints-classification.md
index b7ab7ae8fd19ebc040b8e01e61319238f2cdf8b2..2775c92fbfc0ce46473d7be1934eb85423d5b54e 100644
--- a/doc/architecture/blueprints/cells/impacted_features/router-endpoints-classification.md
+++ b/doc/architecture/blueprints/cells/impacted_features/router-endpoints-classification.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/router-endpoints-classification/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/router-endpoints-classification/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/schema-changes.md b/doc/architecture/blueprints/cells/impacted_features/schema-changes.md
index cef051e128e8700d2170538242879e62fbc982d6..3a4b4da16deeaed66a37bb6d0a193999d5174617 100644
--- a/doc/architecture/blueprints/cells/impacted_features/schema-changes.md
+++ b/doc/architecture/blueprints/cells/impacted_features/schema-changes.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/schema-changes/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/schema-changes/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/secrets.md b/doc/architecture/blueprints/cells/impacted_features/secrets.md
index fe3ba55baec2d8e95882afbbb83bb0efb9a4413e..8f2fde67e19e51b821d25181828df56164802008 100644
--- a/doc/architecture/blueprints/cells/impacted_features/secrets.md
+++ b/doc/architecture/blueprints/cells/impacted_features/secrets.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/secrets/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/secrets/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/snippets.md b/doc/architecture/blueprints/cells/impacted_features/snippets.md
index f48c1553b58931cf3ee2c675b3519d2f82e1fb93..48786cd3cc8ba7339a9d57eb5660a774fa8e24e5 100644
--- a/doc/architecture/blueprints/cells/impacted_features/snippets.md
+++ b/doc/architecture/blueprints/cells/impacted_features/snippets.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/snippets/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/snippets/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/template.md b/doc/architecture/blueprints/cells/impacted_features/template.md
index cc0b168207729dca5f8921cd6c65054bbeaf1e78..e32e84184d9f9fdb23cc9574a211de2737734950 100644
--- a/doc/architecture/blueprints/cells/impacted_features/template.md
+++ b/doc/architecture/blueprints/cells/impacted_features/template.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/template/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/template/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/uploads.md b/doc/architecture/blueprints/cells/impacted_features/uploads.md
index a04c28a3f3c3fdf56847876d65052201a7c8e4c7..acbd19b110e9593b14ef2cbd7fb1a816dcd352da 100644
--- a/doc/architecture/blueprints/cells/impacted_features/uploads.md
+++ b/doc/architecture/blueprints/cells/impacted_features/uploads.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/uploads/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/uploads/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/user-profile.md b/doc/architecture/blueprints/cells/impacted_features/user-profile.md
index d96e0732e030036019fff9bc3ed7f1ebe0849380..321389df1ed5b6ae7ab5cb3f993aa0c262ea9e62 100644
--- a/doc/architecture/blueprints/cells/impacted_features/user-profile.md
+++ b/doc/architecture/blueprints/cells/impacted_features/user-profile.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/user-profile/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/user-profile/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/impacted_features/your-work.md b/doc/architecture/blueprints/cells/impacted_features/your-work.md
index 2592cff2b8cd4e45f7abdc320e125bce52a0becd..6e6c5e09fe4dddb8ce18ea3b2ea2ce0ff1618285 100644
--- a/doc/architecture/blueprints/cells/impacted_features/your-work.md
+++ b/doc/architecture/blueprints/cells/impacted_features/your-work.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/your-work/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/your-work/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/infrastructure/_index.md b/doc/architecture/blueprints/cells/infrastructure/_index.md
index d813ee90dd769e391de7c8a60698210905d8eb03..577a8aeca087c3a08a7f09d2cf46ed33d5f50ff8 100644
--- a/doc/architecture/blueprints/cells/infrastructure/_index.md
+++ b/doc/architecture/blueprints/cells/infrastructure/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/infrastructure/cell_arch_tooling.md b/doc/architecture/blueprints/cells/infrastructure/cell_arch_tooling.md
index a3c43a1dcc76735d75e051690b4e82605e2f870d..a3475696daf0f4aafba9fa914181544f0f73f58f 100644
--- a/doc/architecture/blueprints/cells/infrastructure/cell_arch_tooling.md
+++ b/doc/architecture/blueprints/cells/infrastructure/cell_arch_tooling.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/cell_arch_tooling/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/cell_arch_tooling/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/infrastructure/deployments.md b/doc/architecture/blueprints/cells/infrastructure/deployments.md
index 6a69f2ce5d362e21174bfc1b060a5c6aaf41cc94..f3b8fb2fda137f58f64dec4468903322d75d6e1b 100644
--- a/doc/architecture/blueprints/cells/infrastructure/deployments.md
+++ b/doc/architecture/blueprints/cells/infrastructure/deployments.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/deployments/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/deployments/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/infrastructure/diff-between-dedicated.md b/doc/architecture/blueprints/cells/infrastructure/diff-between-dedicated.md
index af348b339f3d08ed4f90f637f6572ec38656d40b..cb79f8e716ca4254b8e4a008a8625007091fc5b3 100644
--- a/doc/architecture/blueprints/cells/infrastructure/diff-between-dedicated.md
+++ b/doc/architecture/blueprints/cells/infrastructure/diff-between-dedicated.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/diff-between-dedicated/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/diff-between-dedicated/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/infrastructure/disaster_recovery.md b/doc/architecture/blueprints/cells/infrastructure/disaster_recovery.md
index 121515a6a120375d755c407716bdce145ec291d1..0eadbc82128f7521f10849e9a40816e2699fac6f 100644
--- a/doc/architecture/blueprints/cells/infrastructure/disaster_recovery.md
+++ b/doc/architecture/blueprints/cells/infrastructure/disaster_recovery.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/disaster_recovery/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/disaster_recovery/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/infrastructure/observability.md b/doc/architecture/blueprints/cells/infrastructure/observability.md
index 639df2bc0368b6d1d0d232e68d89048272280411..60c117dbb59d2d06ca28fae90d0302913fe72d48 100644
--- a/doc/architecture/blueprints/cells/infrastructure/observability.md
+++ b/doc/architecture/blueprints/cells/infrastructure/observability.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/observability/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/observability/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/infrastructure/postgresql.md b/doc/architecture/blueprints/cells/infrastructure/postgresql.md
index 38348133bc1a001205c0da19fcfc0a34da7356c7..998901291dd8bc9a68b3a43c91191a4bb8d029e6 100644
--- a/doc/architecture/blueprints/cells/infrastructure/postgresql.md
+++ b/doc/architecture/blueprints/cells/infrastructure/postgresql.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/postgresql/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/postgresql/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/infrastructure/runner.md b/doc/architecture/blueprints/cells/infrastructure/runner.md
index 3c2079ed4544ec0f068fce836244cad52766038e..5c7e50da7c55a29184c59f7abe39fead9b43bf21 100644
--- a/doc/architecture/blueprints/cells/infrastructure/runner.md
+++ b/doc/architecture/blueprints/cells/infrastructure/runner.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/runner/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/infrastructure/runner/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/iterations/cells-1.0.md b/doc/architecture/blueprints/cells/iterations/cells-1.0.md
index 136a2f60798895fed1e29c2b7ee815556a80fc9f..fa240e9ff69b2cd94710e1034280d06929ff9ace 100644
--- a/doc/architecture/blueprints/cells/iterations/cells-1.0.md
+++ b/doc/architecture/blueprints/cells/iterations/cells-1.0.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-1.0/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-1.0/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/iterations/cells-1.5.md b/doc/architecture/blueprints/cells/iterations/cells-1.5.md
index ac78df9aa2c23946d3d64a7be22233369511bde9..f0e41132b640ed5acfd7113fc09544dec3f36f37 100644
--- a/doc/architecture/blueprints/cells/iterations/cells-1.5.md
+++ b/doc/architecture/blueprints/cells/iterations/cells-1.5.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-1.5/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-1.5/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/iterations/cells-2.0.md b/doc/architecture/blueprints/cells/iterations/cells-2.0.md
index f8b4fe642bb44475e3bff10434b62c8a0c8f221c..e78a9d7b7923655e7f373bdfb4434c9c2a371212 100644
--- a/doc/architecture/blueprints/cells/iterations/cells-2.0.md
+++ b/doc/architecture/blueprints/cells/iterations/cells-2.0.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-2.0/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-2.0/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/rejected/deployment-architecture.md b/doc/architecture/blueprints/cells/rejected/deployment-architecture.md
index 3605be4d9332e0b01048ae7447b269a845273ab7..04d7d0e4559145085ce5f6e1c14532f5fcfbcac6 100644
--- a/doc/architecture/blueprints/cells/rejected/deployment-architecture.md
+++ b/doc/architecture/blueprints/cells/rejected/deployment-architecture.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/rejected/deployment-architecture/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/rejected/deployment-architecture/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/rejected/impacted_features/database_sequences.md b/doc/architecture/blueprints/cells/rejected/impacted_features/database_sequences.md
index c85b8c07fcc9cc82583a1be34c8f8e2a58d250d6..ccb016fc257cfeb29a0df617851fbb43c8d68a81 100644
--- a/doc/architecture/blueprints/cells/rejected/impacted_features/database_sequences.md
+++ b/doc/architecture/blueprints/cells/rejected/impacted_features/database_sequences.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/rejected/impacted_features/database_sequences/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/rejected/impacted_features/database_sequences/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/rejected/proposal-stateless-router-with-buffering-requests.md b/doc/architecture/blueprints/cells/rejected/proposal-stateless-router-with-buffering-requests.md
index d342e30ba8a4884556fc3e8e4553c25be3a519db..d9c99be761217a9f0f600e4e78f352b6d212af3d 100644
--- a/doc/architecture/blueprints/cells/rejected/proposal-stateless-router-with-buffering-requests.md
+++ b/doc/architecture/blueprints/cells/rejected/proposal-stateless-router-with-buffering-requests.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/rejected/proposal-stateless-router-with-buffering-requests/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/rejected/proposal-stateless-router-with-buffering-requests/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/rejected/proposal-stateless-router-with-routes-learning.md b/doc/architecture/blueprints/cells/rejected/proposal-stateless-router-with-routes-learning.md
index 6b7ccc5f888d756bcbb40861d379ba15450aec38..84b56dcc3afb1fef36a2858b6aedb32f61d39f18 100644
--- a/doc/architecture/blueprints/cells/rejected/proposal-stateless-router-with-routes-learning.md
+++ b/doc/architecture/blueprints/cells/rejected/proposal-stateless-router-with-routes-learning.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/rejected/proposal-stateless-router-with-routes-learning/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/rejected/proposal-stateless-router-with-routes-learning/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/routing-service.md b/doc/architecture/blueprints/cells/routing-service.md
index 4e91e855978ec1c78bd1072ef8c25a7af33b6fd0..441ffe81cdf7406657ca339adcbe182566e27bb2 100644
--- a/doc/architecture/blueprints/cells/routing-service.md
+++ b/doc/architecture/blueprints/cells/routing-service.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/http_routing_service/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/http_routing_service/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/ssh_routing_service.md b/doc/architecture/blueprints/cells/ssh_routing_service.md
index 7e9529256e2708b88a17a2eeea9d55adf5b9e015..78026b9f531168e434ca63d79ee4457c397c29fb 100644
--- a/doc/architecture/blueprints/cells/ssh_routing_service.md
+++ b/doc/architecture/blueprints/cells/ssh_routing_service.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/ssh_routing_service/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/ssh_routing_service/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/topology_service.md b/doc/architecture/blueprints/cells/topology_service.md
index d483fe2fea30032ec04bd41210ea89a579a6279e..4b1caa55fbb31936960b84c2d0e02b3f4e8c5f83 100644
--- a/doc/architecture/blueprints/cells/topology_service.md
+++ b/doc/architecture/blueprints/cells/topology_service.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/topology_service/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/topology_service/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cells/unique_sequences.md b/doc/architecture/blueprints/cells/unique_sequences.md
index 43d4d2a08ebaa81a9b7994a11ada041662a4e85d..fdfd52492f6dbecae582dd13e955f7366170adbe 100644
--- a/doc/architecture/blueprints/cells/unique_sequences.md
+++ b/doc/architecture/blueprints/cells/unique_sequences.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/unique_sequences/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/unique_sequences/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_build_speed/_index.md b/doc/architecture/blueprints/ci_build_speed/_index.md
index aefde6649c158009bf3acd527e4070f7fe37d7f6..c14aaf9c784551799f5ee7865cd14769db175839 100644
--- a/doc/architecture/blueprints/ci_build_speed/_index.md
+++ b/doc/architecture/blueprints/ci_build_speed/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_build_speed/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_build_speed/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_build_speed/benchmark.md b/doc/architecture/blueprints/ci_build_speed/benchmark.md
index 91a13df6c5f20ef81f535ce135116ac09c802d68..5b016415cccef41cd88fb037606ca5ac1e6eed36 100644
--- a/doc/architecture/blueprints/ci_build_speed/benchmark.md
+++ b/doc/architecture/blueprints/ci_build_speed/benchmark.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_build_speed/benchmark/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_build_speed/benchmark/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/_index.md b/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/_index.md
index a89a0d74b33585555c292803f42d88e6e8fbffa5..bbeb67d72644108e2e3ef5e74fddcb2fa3bd1838 100644
--- a/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/_index.md
+++ b/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_builds_runner_fleet_metrics/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_builds_runner_fleet_metrics/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/ci_insights.md b/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/ci_insights.md
index 137e96536dd0ccaebe3666d063f07f97940a0818..2c9cc7460d21f7e738fe5bf1f60e44eb6b852894 100644
--- a/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/ci_insights.md
+++ b/doc/architecture/blueprints/ci_builds_runner_fleet_metrics/ci_insights.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_builds_runner_fleet_metrics/ci_insights/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_builds_runner_fleet_metrics/ci_insights/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_data_decay/_index.md b/doc/architecture/blueprints/ci_data_decay/_index.md
index dce10fcc1b5026433bc65f09bd727e6f302c368f..05e186726435a99650b53b5041e52e7f65551279 100644
--- a/doc/architecture/blueprints/ci_data_decay/_index.md
+++ b/doc/architecture/blueprints/ci_data_decay/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_data_decay/pipeline_archival.md b/doc/architecture/blueprints/ci_data_decay/pipeline_archival.md
index b17cabf2076d29b80cf7fe55b89f1efa0129c4a1..0a333bc41642ffef8bbe3000616c9e9c6524ff00 100644
--- a/doc/architecture/blueprints/ci_data_decay/pipeline_archival.md
+++ b/doc/architecture/blueprints/ci_data_decay/pipeline_archival.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/pipeline_archival/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/pipeline_archival/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md b/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md
index f52017e1292db678fb8331402b9368e1514e99a1..cd620f2b272593131915ce44dc1e55d0056d9e33 100644
--- a/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md
+++ b/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/pipeline_partitioning/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/pipeline_partitioning/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_data_decay/reduce_data_growth_rate.md b/doc/architecture/blueprints/ci_data_decay/reduce_data_growth_rate.md
index 5f7f36ca2da876d44affb0cc281cbd287c6e250f..376a93361a93944c63ece28dc6e23d6ac246112c 100644
--- a/doc/architecture/blueprints/ci_data_decay/reduce_data_growth_rate.md
+++ b/doc/architecture/blueprints/ci_data_decay/reduce_data_growth_rate.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/reduce_data_growth_rate/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/reduce_data_growth_rate/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_data_decay/retention_policies.md b/doc/architecture/blueprints/ci_data_decay/retention_policies.md
index 670047d3c8e342572a1a6754976131b67902f268..5f22dd23ebbeffb0d0d03e758b7805a60109e8a7 100644
--- a/doc/architecture/blueprints/ci_data_decay/retention_policies.md
+++ b/doc/architecture/blueprints/ci_data_decay/retention_policies.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/retention_policies/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_data_decay/retention_policies/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_gcp_secrets_manager/_index.md b/doc/architecture/blueprints/ci_gcp_secrets_manager/_index.md
index 9f4476f8dc2aa0f00594028cb99ae2127588157a..bc6312e5a8cdc6231f9fd01357e29c91a9019be0 100644
--- a/doc/architecture/blueprints/ci_gcp_secrets_manager/_index.md
+++ b/doc/architecture/blueprints/ci_gcp_secrets_manager/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_gcp_secrets_manager/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_gcp_secrets_manager/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_pipeline_components/_index.md b/doc/architecture/blueprints/ci_pipeline_components/_index.md
index 986f272a12582977792e09fc1bee81b203a1d979..c99a75463121349c3dd0e17eb6d4be210fc7f4be 100644
--- a/doc/architecture/blueprints/ci_pipeline_components/_index.md
+++ b/doc/architecture/blueprints/ci_pipeline_components/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_pipeline_components/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_pipeline_components/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_pipeline_processing/_index.md b/doc/architecture/blueprints/ci_pipeline_processing/_index.md
index 10d47193c923e59f227b2a1509bda62f1ffa7f5b..d0fe4eecb81758318f57ca7bf3825aa7f5cf6d52 100644
--- a/doc/architecture/blueprints/ci_pipeline_processing/_index.md
+++ b/doc/architecture/blueprints/ci_pipeline_processing/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_pipeline_processing/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_pipeline_processing/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ci_scale/_index.md b/doc/architecture/blueprints/ci_scale/_index.md
index 68a3e1bfc7e06cbfd437cdaaaed6122be4e6e0bb..4a43482d9b6e0fa68c3b2dea8baecf82a909571f 100644
--- a/doc/architecture/blueprints/ci_scale/_index.md
+++ b/doc/architecture/blueprints/ci_scale/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_scale/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ci_scale/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/clickhouse_ingestion_pipeline/_index.md b/doc/architecture/blueprints/clickhouse_ingestion_pipeline/_index.md
index 317bb40ee53a78877503b1aee3b608b456aa51b7..cf76dea8dfdcb7adb760136dc005a2b32fe6764e 100644
--- a/doc/architecture/blueprints/clickhouse_ingestion_pipeline/_index.md
+++ b/doc/architecture/blueprints/clickhouse_ingestion_pipeline/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/clickhouse_ingestion_pipeline/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/clickhouse_ingestion_pipeline/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/clickhouse_read_abstraction_layer/_index.md b/doc/architecture/blueprints/clickhouse_read_abstraction_layer/_index.md
index bc00bc0ec692e5220e50d1d4096563b424edebec..a77abe4e8fc90b1d5632a328bd588d3180151f5c 100644
--- a/doc/architecture/blueprints/clickhouse_read_abstraction_layer/_index.md
+++ b/doc/architecture/blueprints/clickhouse_read_abstraction_layer/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/clickhouse_read_abstraction_layer/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/clickhouse_read_abstraction_layer/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/clickhouse_usage/_index.md b/doc/architecture/blueprints/clickhouse_usage/_index.md
index 8e1018f257a6f1c6f5a8734e149741d7c817cea3..534d21db94d25d64b3100e0fb87738acd032edaa 100644
--- a/doc/architecture/blueprints/clickhouse_usage/_index.md
+++ b/doc/architecture/blueprints/clickhouse_usage/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/clickhouse_usage/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/clickhouse_usage/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/clickhouse_usage/self_managed_costs_and_requirements/_index.md b/doc/architecture/blueprints/clickhouse_usage/self_managed_costs_and_requirements/_index.md
index c7b0e3969222f95840214904752d2a2769863ff7..f45766ed11849b97b42075906e4d2c92d1d2c0fd 100644
--- a/doc/architecture/blueprints/clickhouse_usage/self_managed_costs_and_requirements/_index.md
+++ b/doc/architecture/blueprints/clickhouse_usage/self_managed_costs_and_requirements/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/clickhouse_usage/self_managed_costs_and_requirements/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/clickhouse_usage/self_managed_costs_and_requirements/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cloud_connector/_index.md b/doc/architecture/blueprints/cloud_connector/_index.md
index b04b14bceec2d0e342575143dbfafb18a1260b36..38557a1182a422f1624c494f52e3a73153f8c173 100644
--- a/doc/architecture/blueprints/cloud_connector/_index.md
+++ b/doc/architecture/blueprints/cloud_connector/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cloud_connector/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cloud_connector/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cloud_connector/decisions/001_lb_entry_point.md b/doc/architecture/blueprints/cloud_connector/decisions/001_lb_entry_point.md
index dfdc5fe04a99e42bdd2c1fd994785dd02cbe3829..b3c6455c2431511dc9a2d02c465e8dfefe773dca 100644
--- a/doc/architecture/blueprints/cloud_connector/decisions/001_lb_entry_point.md
+++ b/doc/architecture/blueprints/cloud_connector/decisions/001_lb_entry_point.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cloud_connector/decisions/001_lb_entry_point/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cloud_connector/decisions/001_lb_entry_point/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cloud_native_build_logs/_index.md b/doc/architecture/blueprints/cloud_native_build_logs/_index.md
index 57d2c712915e1e1315a721a3399c06f995ee48e8..229f635a63dc9f0e1882fd1d17d1590e84f80316 100644
--- a/doc/architecture/blueprints/cloud_native_build_logs/_index.md
+++ b/doc/architecture/blueprints/cloud_native_build_logs/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cloud_native_build_logs/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cloud_native_build_logs/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/cloud_native_gitlab_pages/_index.md b/doc/architecture/blueprints/cloud_native_gitlab_pages/_index.md
index ffda81714de85da769f16dbe8b427a96c40bb06a..79228f47893c01c12cad76915b0ec3b548c1e8ac 100644
--- a/doc/architecture/blueprints/cloud_native_gitlab_pages/_index.md
+++ b/doc/architecture/blueprints/cloud_native_gitlab_pages/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cloud_native_gitlab_pages/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cloud_native_gitlab_pages/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/code_search_with_zoekt/_index.md b/doc/architecture/blueprints/code_search_with_zoekt/_index.md
index d5d5d11bc865cbe4604f66d1091f7002b280a9d1..3e75670f522d85b624630fb54166357a38218cdf 100644
--- a/doc/architecture/blueprints/code_search_with_zoekt/_index.md
+++ b/doc/architecture/blueprints/code_search_with_zoekt/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/code_search_with_zoekt/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/code_search_with_zoekt/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/composable_codebase_using_rails_engines/_index.md b/doc/architecture/blueprints/composable_codebase_using_rails_engines/_index.md
index ba7b913236079d566c242b868b2a907f0b41ba66..35f71786393c355ac6a97064df79a7f0a65adf49 100644
--- a/doc/architecture/blueprints/composable_codebase_using_rails_engines/_index.md
+++ b/doc/architecture/blueprints/composable_codebase_using_rails_engines/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/composable_codebase_using_rails_engines/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/composable_codebase_using_rails_engines/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/consolidating_groups_and_projects/_index.md b/doc/architecture/blueprints/consolidating_groups_and_projects/_index.md
index c634aa60e883e25113b12453d76894159b9a38df..a4ea086aa6fe6402a76c2a12f0c3c92883abb45e 100644
--- a/doc/architecture/blueprints/consolidating_groups_and_projects/_index.md
+++ b/doc/architecture/blueprints/consolidating_groups_and_projects/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/consolidating_groups_and_projects/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/consolidating_groups_and_projects/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/container_registry_metadata_database/_index.md b/doc/architecture/blueprints/container_registry_metadata_database/_index.md
index c893d47a8c20dbed708a47f3a60e2cefcd3bb688..ae95578bafadd31f34a98667691d08ac7fc299bc 100644
--- a/doc/architecture/blueprints/container_registry_metadata_database/_index.md
+++ b/doc/architecture/blueprints/container_registry_metadata_database/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/container_registry_metadata_database/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/container_registry_metadata_database/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/_index.md b/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/_index.md
index 5df4d63e824bb5ca502aa9cc7139fc00d02fbe6e..ac78580cbc847f79d69e52ed7e43a82b6ef8c945 100644
--- a/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/_index.md
+++ b/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/container_registry_metadata_database_self_managed_rollout/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/container_registry_metadata_database_self_managed_rollout/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/custom_models/_index.md b/doc/architecture/blueprints/custom_models/_index.md
index 4e87ec3ea960488f1c83d094156efb99c602ca76..71fc095fd6089c22d311662f9192556397f7a20e 100644
--- a/doc/architecture/blueprints/custom_models/_index.md
+++ b/doc/architecture/blueprints/custom_models/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/custom_models/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/custom_models/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/database/automated_query_analysis/_index.md b/doc/architecture/blueprints/database/automated_query_analysis/_index.md
index aa42831226218f1395140e9756e3eabb72dca92f..7c28b4b02b86ce848d20ace18c9b5d53e7c0ced4 100644
--- a/doc/architecture/blueprints/database/automated_query_analysis/_index.md
+++ b/doc/architecture/blueprints/database/automated_query_analysis/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/automated_query_analysis/'
-remove_date: '2025-09-10'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/automated_query_analysis/
+remove_date: "2025-09-10"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/database_scaling/size-limits.md b/doc/architecture/blueprints/database_scaling/size-limits.md
index 57956d1ce7161671e1415911bd046d1d7339d91f..af1d548dd71d2884e1eab53e0379ce4389fc4ddb 100644
--- a/doc/architecture/blueprints/database_scaling/size-limits.md
+++ b/doc/architecture/blueprints/database_scaling/size-limits.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/database_size_limits/'
-remove_date: '2025-07-19'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/database_size_limits/
+remove_date: "2025-07-19"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/database_testing/_index.md b/doc/architecture/blueprints/database_testing/_index.md
index 6eec8fa895e735d34e4456292764a26cca465773..3503e5eb861c4587845ad4d8fca6fd81b772290c 100644
--- a/doc/architecture/blueprints/database_testing/_index.md
+++ b/doc/architecture/blueprints/database_testing/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/database_testing/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/database_testing/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/disaster_recovery/_index.md b/doc/architecture/blueprints/disaster_recovery/_index.md
index cf2b82eff7e37ef441034fcf0061d295282ce9eb..6846322335b9b44fe9bbdb57dfcca8c0e1c43433 100644
--- a/doc/architecture/blueprints/disaster_recovery/_index.md
+++ b/doc/architecture/blueprints/disaster_recovery/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/disaster_recovery/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/disaster_recovery/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/disaster_recovery/regional.md b/doc/architecture/blueprints/disaster_recovery/regional.md
index a662e95f2115e565b433fb131d1c6a767b9b3efc..099ede9404034abcef80504217eb44b16313050d 100644
--- a/doc/architecture/blueprints/disaster_recovery/regional.md
+++ b/doc/architecture/blueprints/disaster_recovery/regional.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/disaster_recovery/regional/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/disaster_recovery/regional/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/disaster_recovery/zonal.md b/doc/architecture/blueprints/disaster_recovery/zonal.md
index da415676e2d429c1ca670d0819661e6463d57c50..67bca47a33782b8e88c8012574c85976cff55b2d 100644
--- a/doc/architecture/blueprints/disaster_recovery/zonal.md
+++ b/doc/architecture/blueprints/disaster_recovery/zonal.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/disaster_recovery/zonal/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/disaster_recovery/zonal/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/duo_workflow/_index.md b/doc/architecture/blueprints/duo_workflow/_index.md
index f6a98580a23de59f75b2ea3b48b4de9b9152beee..0ac36527cec7433c72433d93473109fa8ad69930 100644
--- a/doc/architecture/blueprints/duo_workflow/_index.md
+++ b/doc/architecture/blueprints/duo_workflow/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/duo_workflow/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/duo_workflow/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/email_ingestion/_index.md b/doc/architecture/blueprints/email_ingestion/_index.md
index 5f4f2402d4ee3e7ced296d7ee59a163ecf554539..54b93cca9ff2a7b3d0da736f8803902a466b5403 100644
--- a/doc/architecture/blueprints/email_ingestion/_index.md
+++ b/doc/architecture/blueprints/email_ingestion/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/email-ingestion/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/email-ingestion/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/epss/_index.md b/doc/architecture/blueprints/epss/_index.md
index 2a099f2f584687e8b7e09da56b9c2e59d73be432..e7be3722f2adf5621977ea174580966e584727e5 100644
--- a/doc/architecture/blueprints/epss/_index.md
+++ b/doc/architecture/blueprints/epss/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/epss/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/epss/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/epss/decisions/002_use_new_bucket.md b/doc/architecture/blueprints/epss/decisions/002_use_new_bucket.md
index b2f6038f14d2e00981e9c26c498ed011cf8f1234..93f94151385904bea03f424c18c6e7022859a07f 100644
--- a/doc/architecture/blueprints/epss/decisions/002_use_new_bucket.md
+++ b/doc/architecture/blueprints/epss/decisions/002_use_new_bucket.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/epss/decisions/002_use_new_bucket/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/epss/decisions/002_use_new_bucket/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/feature_flags_development/_index.md b/doc/architecture/blueprints/feature_flags_development/_index.md
index 929e21c763bc651056df96c9d83129cde4008d4a..06906ebcd66331bc68910f6a44643321c2eb70f2 100644
--- a/doc/architecture/blueprints/feature_flags_development/_index.md
+++ b/doc/architecture/blueprints/feature_flags_development/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/feature_flags_development/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/feature_flags_development/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/feature_flags_usage_in_dev_and_ops/_index.md b/doc/architecture/blueprints/feature_flags_usage_in_dev_and_ops/_index.md
index 504067415dce7569d27ec6925fb0170793c17027..94a3934502650d0f0767f8a6372c0b925cd4e5ad 100644
--- a/doc/architecture/blueprints/feature_flags_usage_in_dev_and_ops/_index.md
+++ b/doc/architecture/blueprints/feature_flags_usage_in_dev_and_ops/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/feature_flags_usage_in_dev_and_ops/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/feature_flags_usage_in_dev_and_ops/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/git_data_offloading/_index.md b/doc/architecture/blueprints/git_data_offloading/_index.md
index 15cf0847d1c86a827d67f7a962303dc9c25fa462..177d6e6edf204619b276c440f9f77c7ccf816c53 100644
--- a/doc/architecture/blueprints/git_data_offloading/_index.md
+++ b/doc/architecture/blueprints/git_data_offloading/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/git_data_offloading/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/git_data_offloading/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/_index.md b/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/_index.md
index 0eb451d003ed042271011e5c1504fd73bda79f25..6c5e1add9bc17716e885f2b3283f3c55d9191765 100644
--- a/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/_index.md
+++ b/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitaly_adaptive_concurrency_limit/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitaly_adaptive_concurrency_limit/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitaly_handle_upload_pack_in_http2_server/_index.md b/doc/architecture/blueprints/gitaly_handle_upload_pack_in_http2_server/_index.md
index 3323fb2214713a95b830e28eec690bf432318355..55c2fa55e48050bce795df0db5e60a09079f84a1 100644
--- a/doc/architecture/blueprints/gitaly_handle_upload_pack_in_http2_server/_index.md
+++ b/doc/architecture/blueprints/gitaly_handle_upload_pack_in_http2_server/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitaly_handle_upload_pack_in_http2_server/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitaly_handle_upload_pack_in_http2_server/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitaly_plugins/_index.md b/doc/architecture/blueprints/gitaly_plugins/_index.md
index 7afe41bbb97966aafa4d23175f2a83a7fa6f6881..0881b303361e61d129ca8b744bbf7a498941d7b2 100644
--- a/doc/architecture/blueprints/gitaly_plugins/_index.md
+++ b/doc/architecture/blueprints/gitaly_plugins/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitaly_plugins/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitaly_plugins/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitaly_transaction_management/_index.md b/doc/architecture/blueprints/gitaly_transaction_management/_index.md
index 47639d64910227b5bf87214a4f3f3787f7a6c693..b33d863ed67ef5a102fcec5192b5a21f2e54a91b 100644
--- a/doc/architecture/blueprints/gitaly_transaction_management/_index.md
+++ b/doc/architecture/blueprints/gitaly_transaction_management/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitaly_transaction_management/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitaly_transaction_management/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_agent_deployments/_index.md b/doc/architecture/blueprints/gitlab_agent_deployments/_index.md
index 1a92246a2f63daa780fa0b2e101e7ea000fd5731..452fc7c08c8f6cc32a6ecbeb1d4bc755b28c26d6 100644
--- a/doc/architecture/blueprints/gitlab_agent_deployments/_index.md
+++ b/doc/architecture/blueprints/gitlab_agent_deployments/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_agent_deployments/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_agent_deployments/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_ci_events/_index.md b/doc/architecture/blueprints/gitlab_ci_events/_index.md
index e9393529ae1c0438e04508120b83edf684114afd..a1d2ab94c83cea6b3054b683cb76db6e471a8909 100644
--- a/doc/architecture/blueprints/gitlab_ci_events/_index.md
+++ b/doc/architecture/blueprints/gitlab_ci_events/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_ci_events/decisions/001_hierarchical_events.md b/doc/architecture/blueprints/gitlab_ci_events/decisions/001_hierarchical_events.md
index 7c6cae72432912f23ce7368543c712e9336db8e3..b6852a213f3fc6f502d7acdc734f2261d85d6a58 100644
--- a/doc/architecture/blueprints/gitlab_ci_events/decisions/001_hierarchical_events.md
+++ b/doc/architecture/blueprints/gitlab_ci_events/decisions/001_hierarchical_events.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/decisions/001_hierarchical_events/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/decisions/001_hierarchical_events/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_ci_events/proposal-1-using-the-gitlab-ci-file.md b/doc/architecture/blueprints/gitlab_ci_events/proposal-1-using-the-gitlab-ci-file.md
index fc392d4f0a3687989d8daac094f9045b5a0aa918..a0e3ef343aed86163f3c08e0fa8a0b6e4ef02415 100644
--- a/doc/architecture/blueprints/gitlab_ci_events/proposal-1-using-the-gitlab-ci-file.md
+++ b/doc/architecture/blueprints/gitlab_ci_events/proposal-1-using-the-gitlab-ci-file.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-1-using-the-gitlab-ci-file/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-1-using-the-gitlab-ci-file/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_ci_events/proposal-2-using-the-rules-keyword.md b/doc/architecture/blueprints/gitlab_ci_events/proposal-2-using-the-rules-keyword.md
index ece127c36548c31d642ad070073a95fda6dcf934..dce40b9bf4cab04c12c25760a2d05ea7835af05a 100644
--- a/doc/architecture/blueprints/gitlab_ci_events/proposal-2-using-the-rules-keyword.md
+++ b/doc/architecture/blueprints/gitlab_ci_events/proposal-2-using-the-rules-keyword.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-2-using-the-rules-keyword/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-2-using-the-rules-keyword/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_ci_events/proposal-3-using-the-gitlab-ci-events-folder.md b/doc/architecture/blueprints/gitlab_ci_events/proposal-3-using-the-gitlab-ci-events-folder.md
index 73066f47a6fd769f0850d0e8163ce1587fba357c..ec3c130bc3c2c9191889349dec0493bcb79a14ae 100644
--- a/doc/architecture/blueprints/gitlab_ci_events/proposal-3-using-the-gitlab-ci-events-folder.md
+++ b/doc/architecture/blueprints/gitlab_ci_events/proposal-3-using-the-gitlab-ci-events-folder.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-3-using-the-gitlab-ci-events-folder/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-3-using-the-gitlab-ci-events-folder/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_ci_events/proposal-4-creating-events-via-ci-files.md b/doc/architecture/blueprints/gitlab_ci_events/proposal-4-creating-events-via-ci-files.md
index ec495aeacf3f9c4cfdcbed1eb27452ff98c44284..a771d140f7e62f89791257d4b7b7627d535bf38d 100644
--- a/doc/architecture/blueprints/gitlab_ci_events/proposal-4-creating-events-via-ci-files.md
+++ b/doc/architecture/blueprints/gitlab_ci_events/proposal-4-creating-events-via-ci-files.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-4-creating-events-via-ci-files/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-4-creating-events-via-ci-files/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_ci_events/proposal-5-combined-proposal.md b/doc/architecture/blueprints/gitlab_ci_events/proposal-5-combined-proposal.md
index 3c22b667f2964ca1818b7d59461549db8688dd82..e3dc8e77cabea6961d3c76aaf4879d01cb997d22 100644
--- a/doc/architecture/blueprints/gitlab_ci_events/proposal-5-combined-proposal.md
+++ b/doc/architecture/blueprints/gitlab_ci_events/proposal-5-combined-proposal.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-5-combined-proposal/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ci_events/proposal-5-combined-proposal/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_duo_rag/_index.md b/doc/architecture/blueprints/gitlab_duo_rag/_index.md
index 65e5b0989a1abbdf72373ab51614fc2e1a6ad54b..9f29f3e5c8f6feb423cc8152d7eaa4c034cfca80 100644
--- a/doc/architecture/blueprints/gitlab_duo_rag/_index.md
+++ b/doc/architecture/blueprints/gitlab_duo_rag/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_duo_rag/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_duo_rag/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_duo_rag/elasticsearch.md b/doc/architecture/blueprints/gitlab_duo_rag/elasticsearch.md
index 22f9b5fb20f05245fc61a304a8b6aac394b63524..10f5b5c3093431c7ce47abce6237711cd9314fd0 100644
--- a/doc/architecture/blueprints/gitlab_duo_rag/elasticsearch.md
+++ b/doc/architecture/blueprints/gitlab_duo_rag/elasticsearch.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_duo_rag/elasticsearch/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_duo_rag/elasticsearch/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_duo_rag/postgresql.md b/doc/architecture/blueprints/gitlab_duo_rag/postgresql.md
index 1be8ad0fd9c4d4eb0f8582491eedb123d02c8389..387f39770bbfab5eacc2a555c623e87008baa8fc 100644
--- a/doc/architecture/blueprints/gitlab_duo_rag/postgresql.md
+++ b/doc/architecture/blueprints/gitlab_duo_rag/postgresql.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_duo_rag/postgresql/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_duo_rag/postgresql/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_duo_rag/vertex_ai_search.md b/doc/architecture/blueprints/gitlab_duo_rag/vertex_ai_search.md
index f8846abca7c2d33be03672793333c81cc129cb60..ddc8cd89a6434c837c691a6d1599951981b53de6 100644
--- a/doc/architecture/blueprints/gitlab_duo_rag/vertex_ai_search.md
+++ b/doc/architecture/blueprints/gitlab_duo_rag/vertex_ai_search.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_duo_rag/vertex_ai_search/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_duo_rag/vertex_ai_search/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_events_platform/_index.md b/doc/architecture/blueprints/gitlab_events_platform/_index.md
index 2d3091fba4020ff8a47b2defde61e1b5beb2a4b8..984b3e6fbb36858db80ead307987b5dd4fedb304 100644
--- a/doc/architecture/blueprints/gitlab_events_platform/_index.md
+++ b/doc/architecture/blueprints/gitlab_events_platform/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_events_platform/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_events_platform/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_housekeeper/_index.md b/doc/architecture/blueprints/gitlab_housekeeper/_index.md
index 1ce547e6df770784f8d2edd2622b248fb0391ec3..86d47aac7433ac9d4da0ae67e7f28f0b4ce41574 100644
--- a/doc/architecture/blueprints/gitlab_housekeeper/_index.md
+++ b/doc/architecture/blueprints/gitlab_housekeeper/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_housekeeper/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_housekeeper/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_ml_experiments/_index.md b/doc/architecture/blueprints/gitlab_ml_experiments/_index.md
index 32d3d7e168a359de5b29dee0c37e8803548c78d0..b4014fea2b342732b5fc1e45888456c5de8b3cbc 100644
--- a/doc/architecture/blueprints/gitlab_ml_experiments/_index.md
+++ b/doc/architecture/blueprints/gitlab_ml_experiments/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ml_experiments/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_ml_experiments/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_rag/_index.md b/doc/architecture/blueprints/gitlab_rag/_index.md
index dfd5a94589d1ebd8af996caa97ec19bf019f4b67..69e1b0e329dd7d6b5da445d4a583e094f307c30b 100644
--- a/doc/architecture/blueprints/gitlab_rag/_index.md
+++ b/doc/architecture/blueprints/gitlab_rag/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_rag/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_rag/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_rag/elasticsearch.md b/doc/architecture/blueprints/gitlab_rag/elasticsearch.md
index d6a254a0edc9e92761b0224c30e89e5969f6ee16..6beb018629e27856f9398e126b1f1435a67bc6dd 100644
--- a/doc/architecture/blueprints/gitlab_rag/elasticsearch.md
+++ b/doc/architecture/blueprints/gitlab_rag/elasticsearch.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_rag/elasticsearch/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_rag/elasticsearch/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_rag/postgresql.md b/doc/architecture/blueprints/gitlab_rag/postgresql.md
index 0c9c8c8824f5ad3218300f7af1307c32024162e9..08c2a96f7f1a43017257d852822c5452cbacc695 100644
--- a/doc/architecture/blueprints/gitlab_rag/postgresql.md
+++ b/doc/architecture/blueprints/gitlab_rag/postgresql.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_rag/postgresql/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_rag/postgresql/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_rag/vertex_ai_search.md b/doc/architecture/blueprints/gitlab_rag/vertex_ai_search.md
index fedc2e2444c7ff4cdd4d4064a870bfff40e5da29..b24e5a1794e556cb231292490ff615c2254fac66 100644
--- a/doc/architecture/blueprints/gitlab_rag/vertex_ai_search.md
+++ b/doc/architecture/blueprints/gitlab_rag/vertex_ai_search.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_rag/vertex_ai_search/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_rag/vertex_ai_search/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_services/_index.md b/doc/architecture/blueprints/gitlab_services/_index.md
index 33f9873b14917abb786757ced9bb766956e44e8d..8486757305d1da31dd9f422f61afe2115790b10a 100644
--- a/doc/architecture/blueprints/gitlab_services/_index.md
+++ b/doc/architecture/blueprints/gitlab_services/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_services/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_services/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_steps/_index.md b/doc/architecture/blueprints/gitlab_steps/_index.md
index cfc9bc935e494d5f06dffc9bbcd2f5e74e3072e0..fb3774b882eaaa46cf010afb97d3fd8a3541db0c 100644
--- a/doc/architecture/blueprints/gitlab_steps/_index.md
+++ b/doc/architecture/blueprints/gitlab_steps/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_steps/decisions/001_initial_support.md b/doc/architecture/blueprints/gitlab_steps/decisions/001_initial_support.md
index 137da36edbce6b35b461a8315e715ba0ee881a8e..3edd2a77e15282c753499ad054c7d7f257a63c68 100644
--- a/doc/architecture/blueprints/gitlab_steps/decisions/001_initial_support.md
+++ b/doc/architecture/blueprints/gitlab_steps/decisions/001_initial_support.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/decisions/001_initial_support/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/decisions/001_initial_support/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_steps/gitlab-ci.md b/doc/architecture/blueprints/gitlab_steps/gitlab-ci.md
index 487a2c0ea8fa4c0d1962c41eb4d6cdf777240e6c..471f3cc476e718db2560bb341e5ae9f9d6858eb5 100644
--- a/doc/architecture/blueprints/gitlab_steps/gitlab-ci.md
+++ b/doc/architecture/blueprints/gitlab_steps/gitlab-ci.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/gitlab-ci/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/gitlab-ci/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_steps/implementation.md b/doc/architecture/blueprints/gitlab_steps/implementation.md
index 2e2a240b2bc1b677369c78df4d8bef6e6351d83c..275ee1a5c0d327d50b66703dda642159624956fa 100644
--- a/doc/architecture/blueprints/gitlab_steps/implementation.md
+++ b/doc/architecture/blueprints/gitlab_steps/implementation.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/implementation/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/implementation/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_steps/runner-integration.md b/doc/architecture/blueprints/gitlab_steps/runner-integration.md
index 5d850778ba890561c34e6842e5ed3fb0644a4d21..ad53c89cb65da74a63ff9fbbdb4794092b2b510a 100644
--- a/doc/architecture/blueprints/gitlab_steps/runner-integration.md
+++ b/doc/architecture/blueprints/gitlab_steps/runner-integration.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/runner-integration/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/runner-integration/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_steps/service-deployment.md b/doc/architecture/blueprints/gitlab_steps/service-deployment.md
index 3bd410d1c23d070edd3c2a044da4c3ab230bbd24..b4947273e0ddb528e7afe106539bf26c6835612b 100644
--- a/doc/architecture/blueprints/gitlab_steps/service-deployment.md
+++ b/doc/architecture/blueprints/gitlab_steps/service-deployment.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/service-deployment/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/service-deployment/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_steps/step-definition.md b/doc/architecture/blueprints/gitlab_steps/step-definition.md
index eeda23ea8c477b8f52763a5e3688c4089390c322..ddfcf876020935a6381125b335c8ecc6542ed1d1 100644
--- a/doc/architecture/blueprints/gitlab_steps/step-definition.md
+++ b/doc/architecture/blueprints/gitlab_steps/step-definition.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/step-definition/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/step-definition/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_steps/steps-syntactic-sugar.md b/doc/architecture/blueprints/gitlab_steps/steps-syntactic-sugar.md
index 411fe01041cf7cf2efbe80168974431e93c170d7..06af0c0b351777333a37e86be4b84b373c57c747 100644
--- a/doc/architecture/blueprints/gitlab_steps/steps-syntactic-sugar.md
+++ b/doc/architecture/blueprints/gitlab_steps/steps-syntactic-sugar.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/steps-syntactic-sugar/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_steps/steps-syntactic-sugar/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_to_kubernetes_communication/_index.md b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/_index.md
index d53a904eacc13e26957ef630ab8a0b63df241d90..28011874d51f49e65f7863caa466e3ecb50eb4ac 100644
--- a/doc/architecture/blueprints/gitlab_to_kubernetes_communication/_index.md
+++ b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_to_kubernetes_communication/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_to_kubernetes_communication/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/gitlab_xray_rag/_index.md b/doc/architecture/blueprints/gitlab_xray_rag/_index.md
index 9a70dfd21e2075475531f3e7ad15cb53b2cd45e2..37eb699788d2b6161d87af34aaeddbe07c138d55 100644
--- a/doc/architecture/blueprints/gitlab_xray_rag/_index.md
+++ b/doc/architecture/blueprints/gitlab_xray_rag/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_xray_rag/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gitlab_xray_rag/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/google_artifact_registry_integration/_index.md b/doc/architecture/blueprints/google_artifact_registry_integration/_index.md
index 95577a1f9c5f5262d1cbf7ca2c17e81ef3f29f99..86bb08e1898575421da03aebeef3a99a9b06c203 100644
--- a/doc/architecture/blueprints/google_artifact_registry_integration/_index.md
+++ b/doc/architecture/blueprints/google_artifact_registry_integration/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/google_artifact_registry_integration/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/google_artifact_registry_integration/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/google_artifact_registry_integration/backend.md b/doc/architecture/blueprints/google_artifact_registry_integration/backend.md
index f1cbd11557fa16dd7b1c0494edca17ca3c2ad958..e33ea013d9e8da21b1bfd5aab16ccbc9ba6a6480 100644
--- a/doc/architecture/blueprints/google_artifact_registry_integration/backend.md
+++ b/doc/architecture/blueprints/google_artifact_registry_integration/backend.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/google_artifact_registry_integration/backend/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/google_artifact_registry_integration/backend/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/google_artifact_registry_integration/ui_ux.md b/doc/architecture/blueprints/google_artifact_registry_integration/ui_ux.md
index 8e61053716d17efdea81127757660b253dcdad0a..7df00cb718d7587497516bcfc8bba603f4b66de3 100644
--- a/doc/architecture/blueprints/google_artifact_registry_integration/ui_ux.md
+++ b/doc/architecture/blueprints/google_artifact_registry_integration/ui_ux.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/google_artifact_registry_integration/ui_ux/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/google_artifact_registry_integration/ui_ux/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/google_cloud_platform_integration/_index.md b/doc/architecture/blueprints/google_cloud_platform_integration/_index.md
index 501b06e2d75261a6f719ffb0cbc9c5c359db2e41..dd6f130ee6d52b8b737f2872a6482cb8e36f7d95 100644
--- a/doc/architecture/blueprints/google_cloud_platform_integration/_index.md
+++ b/doc/architecture/blueprints/google_cloud_platform_integration/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/google_cloud_platform_integration/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/google_cloud_platform_integration/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/graphql_api/_index.md b/doc/architecture/blueprints/graphql_api/_index.md
index fbbdc3811fa13986fc5609d3cd8b8220670785ac..787619e096c52823efdc9614a2d462c04efcd6a7 100644
--- a/doc/architecture/blueprints/graphql_api/_index.md
+++ b/doc/architecture/blueprints/graphql_api/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/graphql_api/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/graphql_api/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/image_resizing/_index.md b/doc/architecture/blueprints/image_resizing/_index.md
index 2febcc21d7a16bc7856514d99aff193d6b0f7cc5..3ba51c92fe9ca6cc9aa70c8367eee7490da512f7 100644
--- a/doc/architecture/blueprints/image_resizing/_index.md
+++ b/doc/architecture/blueprints/image_resizing/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/image_resizing/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/image_resizing/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/model_experiments_and_registry/_index.md b/doc/architecture/blueprints/model_experiments_and_registry/_index.md
index 5554c03f747a6bfc060ccb4ad04fef18684f2923..b59f25c65257457bdcc815885154390c613509b7 100644
--- a/doc/architecture/blueprints/model_experiments_and_registry/_index.md
+++ b/doc/architecture/blueprints/model_experiments_and_registry/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/model_experiments_and_registry/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/model_experiments_and_registry/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/modular_monolith/_index.md b/doc/architecture/blueprints/modular_monolith/_index.md
index b84caffa9179f9737e0e8aa46636700f9029af02..55e376198d98541a7dd9c50483bed13e680733dc 100644
--- a/doc/architecture/blueprints/modular_monolith/_index.md
+++ b/doc/architecture/blueprints/modular_monolith/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/modular_monolith/bounded_contexts.md b/doc/architecture/blueprints/modular_monolith/bounded_contexts.md
index b22b62058b204db8eff875a7200261ee73cb27a1..4e5b67074d0ab3555cad10db685fcc9a7aa3d901 100644
--- a/doc/architecture/blueprints/modular_monolith/bounded_contexts.md
+++ b/doc/architecture/blueprints/modular_monolith/bounded_contexts.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/bounded_contexts/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/bounded_contexts/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/modular_monolith/decisions/001_modular_application_domain.md b/doc/architecture/blueprints/modular_monolith/decisions/001_modular_application_domain.md
index 32a43b27f0fa5fd94121b6046f974e7ce2694ee9..3cb711344ca4d036489dd2f0afd4ad6524c00e1e 100644
--- a/doc/architecture/blueprints/modular_monolith/decisions/001_modular_application_domain.md
+++ b/doc/architecture/blueprints/modular_monolith/decisions/001_modular_application_domain.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/decisions/001_modular_application_domain/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/decisions/001_modular_application_domain/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/modular_monolith/decisions/002_bounded_contexts_definition.md b/doc/architecture/blueprints/modular_monolith/decisions/002_bounded_contexts_definition.md
index a06a0cc8337c47b03c2a7efeddcddeb34e234067..cf8782d7f679c85cddbf81486e67243ffa96456f 100644
--- a/doc/architecture/blueprints/modular_monolith/decisions/002_bounded_contexts_definition.md
+++ b/doc/architecture/blueprints/modular_monolith/decisions/002_bounded_contexts_definition.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/decisions/002_bounded_contexts_definition/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/decisions/002_bounded_contexts_definition/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/modular_monolith/decisions/003_stewardship.md b/doc/architecture/blueprints/modular_monolith/decisions/003_stewardship.md
index 13a20c84c612cbc3e17b6e49c86ebf553d0a9991..be9750e48f184cc2f972ea3c53826ec91c5efa87 100644
--- a/doc/architecture/blueprints/modular_monolith/decisions/003_stewardship.md
+++ b/doc/architecture/blueprints/modular_monolith/decisions/003_stewardship.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/decisions/003_stewardship/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/decisions/003_stewardship/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/modular_monolith/hexagonal_monolith/_index.md b/doc/architecture/blueprints/modular_monolith/hexagonal_monolith/_index.md
index 502de99e0461a9e8d714bb4cee928bd4171042ec..9032f7c2cc398e8439f6ed8f021704776af75100 100644
--- a/doc/architecture/blueprints/modular_monolith/hexagonal_monolith/_index.md
+++ b/doc/architecture/blueprints/modular_monolith/hexagonal_monolith/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/hexagonal_monolith/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/hexagonal_monolith/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/modular_monolith/packages_extraction.md b/doc/architecture/blueprints/modular_monolith/packages_extraction.md
index e4c9ca970d63dff7df4718d5d698660aee878e9f..8976e7bd1bdf7b9e7d5dbb0d1efa51ef5ed6b88b 100644
--- a/doc/architecture/blueprints/modular_monolith/packages_extraction.md
+++ b/doc/architecture/blueprints/modular_monolith/packages_extraction.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/packages_extraction/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/packages_extraction/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/modular_monolith/proof_of_concepts.md b/doc/architecture/blueprints/modular_monolith/proof_of_concepts.md
index 61b9e4559d88fc9bb7237de1c5022a4d295c25b1..cb5d8c776cd19d03b94c6a4893840a25df88c4e6 100644
--- a/doc/architecture/blueprints/modular_monolith/proof_of_concepts.md
+++ b/doc/architecture/blueprints/modular_monolith/proof_of_concepts.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/proof_of_concepts/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/proof_of_concepts/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/modular_monolith/references.md b/doc/architecture/blueprints/modular_monolith/references.md
index 557c53f941e45969f312e6c726e613342a4cadca..7508ecc1cdf37b4600c6bb37757a88e1e6b04cf7 100644
--- a/doc/architecture/blueprints/modular_monolith/references.md
+++ b/doc/architecture/blueprints/modular_monolith/references.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/references/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/modular_monolith/references/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/notes_table_partitioning.md b/doc/architecture/blueprints/notes_table_partitioning.md
index ef5dc3017dd852dc8176b246c759193cdde3914c..f59989d39425a3637ab8b1712c24f237dc077dac 100644
--- a/doc/architecture/blueprints/notes_table_partitioning.md
+++ b/doc/architecture/blueprints/notes_table_partitioning.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/notes_table_partitioning/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/notes_table_partitioning/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/object_pools/_index.md b/doc/architecture/blueprints/object_pools/_index.md
index 222e49e667c97a7f11529cf77f4b641870e4b728..e9522f38dae157596c3ea419ac4a06f032106daa 100644
--- a/doc/architecture/blueprints/object_pools/_index.md
+++ b/doc/architecture/blueprints/object_pools/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/object_pools/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/object_pools/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/object_storage/_index.md b/doc/architecture/blueprints/object_storage/_index.md
index 2d9159eaaf4faa57d4642d0a30217c5541a6fab6..ff47ae525116b7e82c4516e75147ec48cf7d0af1 100644
--- a/doc/architecture/blueprints/object_storage/_index.md
+++ b/doc/architecture/blueprints/object_storage/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/object_storage/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/object_storage/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/observability_for_self_managed/_index.md b/doc/architecture/blueprints/observability_for_self_managed/_index.md
index 58e40f28e1e4f06408f3648d1de4e4fa08ce1830..087e52f77ec89e62b147e0d35931d39c1025582d 100644
--- a/doc/architecture/blueprints/observability_for_self_managed/_index.md
+++ b/doc/architecture/blueprints/observability_for_self_managed/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_for_self_managed/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_for_self_managed/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/observability_logging/_index.md b/doc/architecture/blueprints/observability_logging/_index.md
index e9cd4013cd4c4394845f3c1b3e507e9335a508c5..804cd3da87599e75b938c89b320e973ddfe9259b 100644
--- a/doc/architecture/blueprints/observability_logging/_index.md
+++ b/doc/architecture/blueprints/observability_logging/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_logging/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_logging/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/observability_metrics/_index.md b/doc/architecture/blueprints/observability_metrics/_index.md
index 971d38839413354c2bd42e394ccd33b5e65f8a47..260974506353575429efd4e3043153db69b599b8 100644
--- a/doc/architecture/blueprints/observability_metrics/_index.md
+++ b/doc/architecture/blueprints/observability_metrics/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_metrics/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_metrics/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/observability_tracing/_index.md b/doc/architecture/blueprints/observability_tracing/_index.md
index d2bb18810395797323aa1af1738a1b013f801cbe..727cc74d2bf8a418c1d3ba534c3c2f12996680e7 100644
--- a/doc/architecture/blueprints/observability_tracing/_index.md
+++ b/doc/architecture/blueprints/observability_tracing/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_tracing/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_tracing/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/organization/_index.md b/doc/architecture/blueprints/organization/_index.md
index f462632f191aacefe506723d5bcf62c829bd51dd..5da419522572903c75ebf26c4347aaa45e9e532f 100644
--- a/doc/architecture/blueprints/organization/_index.md
+++ b/doc/architecture/blueprints/organization/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/organization/isolation.md b/doc/architecture/blueprints/organization/isolation.md
index aae2f5320f0cf48237649ad51e5da551a873bd58..d56cec2e16597d6c64e87777ca76aae998c87b03 100644
--- a/doc/architecture/blueprints/organization/isolation.md
+++ b/doc/architecture/blueprints/organization/isolation.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/isolation/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/isolation/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/organization/organization-faq.md b/doc/architecture/blueprints/organization/organization-faq.md
index ffa82470009a6aed6e37b0a1dc91551670b2d675..ef68306d2f4574ecd8c6fc54ebc844159ac7fa43 100644
--- a/doc/architecture/blueprints/organization/organization-faq.md
+++ b/doc/architecture/blueprints/organization/organization-faq.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/organization-faq/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/organization-faq/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/organization/organization-users.md b/doc/architecture/blueprints/organization/organization-users.md
index c24c2a8278d7e2509a59fceebf10eaa53d5b47e6..ffe841bc07cc37feabe647a6f9a8e5b03c17be12 100644
--- a/doc/architecture/blueprints/organization/organization-users.md
+++ b/doc/architecture/blueprints/organization/organization-users.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/organizations-users/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/organization/organizations-users/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/permissions/_index.md b/doc/architecture/blueprints/permissions/_index.md
index 45ee0351ce5e00c6d53d6f9cba98b93100c44ada..ef73385f0e9e1b02df68e4ae844cb6e6bd082982 100644
--- a/doc/architecture/blueprints/permissions/_index.md
+++ b/doc/architecture/blueprints/permissions/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/permissions/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/permissions/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/pipeline_execution_policy/_index.md b/doc/architecture/blueprints/pipeline_execution_policy/_index.md
index d84df932ef1b700e1029a4cebe15897163433cdf..6c7241f01d8efd772868e74746c2a1fac13fef00 100644
--- a/doc/architecture/blueprints/pipeline_execution_policy/_index.md
+++ b/doc/architecture/blueprints/pipeline_execution_policy/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/pipeline_execution_policy/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/pipeline_execution_policy/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/pipeline_mini_graph/_index.md b/doc/architecture/blueprints/pipeline_mini_graph/_index.md
index ef6c114f06c3851fe8b557b95be65bd6a2612536..ca35a17eb443b4d42bdeb38c5e48881bf2f4e27b 100644
--- a/doc/architecture/blueprints/pipeline_mini_graph/_index.md
+++ b/doc/architecture/blueprints/pipeline_mini_graph/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/pipeline_mini_graph/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/pipeline_mini_graph/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/rapid_diffs/_index.md b/doc/architecture/blueprints/rapid_diffs/_index.md
index f56b166a0a0a43fe82e92042d1fb0f3975cd1201..f6746a9b820690bfcf5f9398cc01e8c186a9c13f 100644
--- a/doc/architecture/blueprints/rapid_diffs/_index.md
+++ b/doc/architecture/blueprints/rapid_diffs/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/rapid_diffs/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/rapid_diffs/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/rapid_diffs/features.md b/doc/architecture/blueprints/rapid_diffs/features.md
index da72733d5e4ddd5f09a314431f60db9765456598..abbe944c11df9a5a61258d12c6fbc22abbff9072 100644
--- a/doc/architecture/blueprints/rapid_diffs/features.md
+++ b/doc/architecture/blueprints/rapid_diffs/features.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/rapid_diffs/features/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/rapid_diffs/features/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/rate_limiting/_index.md b/doc/architecture/blueprints/rate_limiting/_index.md
index 7a992616356f8a1d69334e277895f54382f9bea9..d070b7f3250a85e5ce50e709e7d12585d4d937b3 100644
--- a/doc/architecture/blueprints/rate_limiting/_index.md
+++ b/doc/architecture/blueprints/rate_limiting/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/rate_limiting/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/rate_limiting/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/remote_development/_index.md b/doc/architecture/blueprints/remote_development/_index.md
index 77c1142d9eed9a349d7b965210101fcf73d4981c..83ffdf79bdaa9fd3b456e9ee94362aea60e93016 100644
--- a/doc/architecture/blueprints/remote_development/_index.md
+++ b/doc/architecture/blueprints/remote_development/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/remote_development/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/remote_development/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/remote_development/decisions/100_new_agent_authorization_strategy.md b/doc/architecture/blueprints/remote_development/decisions/100_new_agent_authorization_strategy.md
index 66bfd39ed31a4fa097e82319fedfd163c96f65dc..a04a8a350a8df57a85ab840e4eff733bb35750a6 100644
--- a/doc/architecture/blueprints/remote_development/decisions/100_new_agent_authorization_strategy.md
+++ b/doc/architecture/blueprints/remote_development/decisions/100_new_agent_authorization_strategy.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/remote_development/decisions/100_new_agent_authorization_strategy/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/remote_development/decisions/100_new_agent_authorization_strategy/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/repository_backups/_index.md b/doc/architecture/blueprints/repository_backups/_index.md
index 76cc26a61585a36bce2be9b21933864916c59f56..3428542c99138d0d4ae9514cb648bb7c608dee1c 100644
--- a/doc/architecture/blueprints/repository_backups/_index.md
+++ b/doc/architecture/blueprints/repository_backups/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/repository_backups/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/repository_backups/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/runner_admission_controller/_index.md b/doc/architecture/blueprints/runner_admission_controller/_index.md
index 98d027b548300c92c1b7082e78feec48e389db25..ecc53a8ffb0cf4b260fd57eb199a389a0e2df06a 100644
--- a/doc/architecture/blueprints/runner_admission_controller/_index.md
+++ b/doc/architecture/blueprints/runner_admission_controller/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runner_admission_controller/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runner_admission_controller/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/runner_scaling/_index.md b/doc/architecture/blueprints/runner_scaling/_index.md
index 70f7d81185e5a64946526584f5b8569dce4ce297..9f3328809a5ca59807d568ab8fb4f2dee548064b 100644
--- a/doc/architecture/blueprints/runner_scaling/_index.md
+++ b/doc/architecture/blueprints/runner_scaling/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runner_scaling/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runner_scaling/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/runner_tokens/_index.md b/doc/architecture/blueprints/runner_tokens/_index.md
index a866d7fd20e41fcfe85ca0ba49feff2ea8389ee4..889cfaff6f64a12fba6e6a2933d6179cc312fb40 100644
--- a/doc/architecture/blueprints/runner_tokens/_index.md
+++ b/doc/architecture/blueprints/runner_tokens/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runner_tokens/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runner_tokens/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/runway/_index.md b/doc/architecture/blueprints/runway/_index.md
index 4ab12dba5309821624bfc4243c81ccfd4b4b9bfd..accfd03675977f6f9a28219be715a480822862bf 100644
--- a/doc/architecture/blueprints/runway/_index.md
+++ b/doc/architecture/blueprints/runway/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runway/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/runway/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_detection/_index.md b/doc/architecture/blueprints/secret_detection/_index.md
index 0793b807d41acc14714f7c4e1b4303df266cca59..2095afa7299d89db6f90cdfcd5ee00fd74122bf6 100644
--- a/doc/architecture/blueprints/secret_detection/_index.md
+++ b/doc/architecture/blueprints/secret_detection/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_detection/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_detection/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_detection/decisions/001_use_ruby_push_check_approach_within_monolith.md b/doc/architecture/blueprints/secret_detection/decisions/001_use_ruby_push_check_approach_within_monolith.md
index 02fa44573a435bf93bd1e264a084c4cc0e5ffe2c..524c002f18c8bec3f74838fdbaeae9e043cf6ff7 100644
--- a/doc/architecture/blueprints/secret_detection/decisions/001_use_ruby_push_check_approach_within_monolith.md
+++ b/doc/architecture/blueprints/secret_detection/decisions/001_use_ruby_push_check_approach_within_monolith.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/001_use_ruby_push_check_approach_within_monolith/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/001_use_ruby_push_check_approach_within_monolith/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_detection/decisions/002_store_the_secret_detection_gem_in_the_same_repository.md b/doc/architecture/blueprints/secret_detection/decisions/002_store_the_secret_detection_gem_in_the_same_repository.md
index 6138bee01930f0be106d243609a37ec40b41652a..20de0b151c8edf80d7d7952f026152775f48d186 100644
--- a/doc/architecture/blueprints/secret_detection/decisions/002_store_the_secret_detection_gem_in_the_same_repository.md
+++ b/doc/architecture/blueprints/secret_detection/decisions/002_store_the_secret_detection_gem_in_the_same_repository.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/002_store_the_secret_detection_gem_in_the_same_repository/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/002_store_the_secret_detection_gem_in_the_same_repository/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_detection/decisions/003_run_scan_within_subprocess.md b/doc/architecture/blueprints/secret_detection/decisions/003_run_scan_within_subprocess.md
index 1ad21a5031c3e61227f23d6a77055644f6325408..d6e62650b860f452cde6f856e1fc3b052aacf1a6 100644
--- a/doc/architecture/blueprints/secret_detection/decisions/003_run_scan_within_subprocess.md
+++ b/doc/architecture/blueprints/secret_detection/decisions/003_run_scan_within_subprocess.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/003_run_scan_within_subprocess/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/003_run_scan_within_subprocess/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_detection/decisions/004_secret_detection_scanner_service.md b/doc/architecture/blueprints/secret_detection/decisions/004_secret_detection_scanner_service.md
index c1542b88c57f174cd061e6ca35099b7f5b9e5143..df024e71d3ecceafc30567e17022672315c98d05 100644
--- a/doc/architecture/blueprints/secret_detection/decisions/004_secret_detection_scanner_service.md
+++ b/doc/architecture/blueprints/secret_detection/decisions/004_secret_detection_scanner_service.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/004_secret_detection_scanner_service/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/004_secret_detection_scanner_service/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_detection/decisions/005_use_runway_for_deployment.md b/doc/architecture/blueprints/secret_detection/decisions/005_use_runway_for_deployment.md
index 409993f1616cf3ea950ce2b3029060831594ccb6..6ca2df1b8524daa1a39d9f5175cc075b9acbb0e5 100644
--- a/doc/architecture/blueprints/secret_detection/decisions/005_use_runway_for_deployment.md
+++ b/doc/architecture/blueprints/secret_detection/decisions/005_use_runway_for_deployment.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/005_use_runway_for_deployment/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/decisions/005_use_runway_for_deployment/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_manager/_index.md b/doc/architecture/blueprints/secret_manager/_index.md
index f6b795ba9c5df1bd0cabc3d0d32143bdef4f5343..d3ad6bda50b1f55d4d681347826ebbb01e038d0c 100644
--- a/doc/architecture/blueprints/secret_manager/_index.md
+++ b/doc/architecture/blueprints/secret_manager/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_manager/decisions/001_envelop_encryption.md b/doc/architecture/blueprints/secret_manager/decisions/001_envelop_encryption.md
index 9d0cf4216e6d54614d8640c389ea6cad2516b4e8..a0b805d38435b2cf7bf87369dce7dafed8565a29 100644
--- a/doc/architecture/blueprints/secret_manager/decisions/001_envelop_encryption.md
+++ b/doc/architecture/blueprints/secret_manager/decisions/001_envelop_encryption.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/001_envelop_encryption/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/001_envelop_encryption/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_manager/decisions/002_gcp_kms.md b/doc/architecture/blueprints/secret_manager/decisions/002_gcp_kms.md
index d3182a80cf1e1dfd8d9bcc0d2e3d127e9bd12901..49fb7a56ba4a42572552fc02b2a5b2fe703db878 100644
--- a/doc/architecture/blueprints/secret_manager/decisions/002_gcp_kms.md
+++ b/doc/architecture/blueprints/secret_manager/decisions/002_gcp_kms.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/002_gcp_kms/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/002_gcp_kms/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_manager/decisions/003_go_service.md b/doc/architecture/blueprints/secret_manager/decisions/003_go_service.md
index b26343a4e99b336b42f680564ff41d38770d8e9e..7d27263c688643bcb5256cde338d0b248a7a1eb8 100644
--- a/doc/architecture/blueprints/secret_manager/decisions/003_go_service.md
+++ b/doc/architecture/blueprints/secret_manager/decisions/003_go_service.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/003_go_service/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/003_go_service/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_manager/decisions/004_openbao.md b/doc/architecture/blueprints/secret_manager/decisions/004_openbao.md
index 435328761b0ae5583fb7ed510e9755d61bd18a06..88195dfb7d32f0d680169dec3e34103ad37909c9 100644
--- a/doc/architecture/blueprints/secret_manager/decisions/004_openbao.md
+++ b/doc/architecture/blueprints/secret_manager/decisions/004_openbao.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/004_openbao/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/004_openbao/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_manager/decisions/004_staleless_kms.md b/doc/architecture/blueprints/secret_manager/decisions/004_staleless_kms.md
index 7edf2fadcd074d4da594c9551772d5b3e2e3970b..43efa9d56b91f26c280474aa9e8052ae3d518155 100644
--- a/doc/architecture/blueprints/secret_manager/decisions/004_staleless_kms.md
+++ b/doc/architecture/blueprints/secret_manager/decisions/004_staleless_kms.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/004_staleless_kms/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/004_staleless_kms/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_manager/decisions/005_secrets_key_structure.md b/doc/architecture/blueprints/secret_manager/decisions/005_secrets_key_structure.md
index 129f7ca3f9618913a3d4502a7b87eb016eb7b0cb..cfca7ac1d7e688bb872f717fc2e88db5180b624a 100644
--- a/doc/architecture/blueprints/secret_manager/decisions/005_secrets_key_structure.md
+++ b/doc/architecture/blueprints/secret_manager/decisions/005_secrets_key_structure.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/005_secrets_key_structure/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/005_secrets_key_structure/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_manager/decisions/006_approle_authentication_rails.md b/doc/architecture/blueprints/secret_manager/decisions/006_approle_authentication_rails.md
index 3edb524007701403cd25c2805f69a724419aa1c2..41a89189dc00caac772bccd1d0b32afaa4a79c5c 100644
--- a/doc/architecture/blueprints/secret_manager/decisions/006_approle_authentication_rails.md
+++ b/doc/architecture/blueprints/secret_manager/decisions/006_approle_authentication_rails.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/006_approle_authentication_rails/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/decisions/006_approle_authentication_rails/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/secret_manager/studies/ci_job_secrets.md b/doc/architecture/blueprints/secret_manager/studies/ci_job_secrets.md
index 09ffeeb4043f49119949faa1d036f8a85125aa4f..1f2788e38013b60173a26dbc22ad17ad25ba6e6a 100644
--- a/doc/architecture/blueprints/secret_manager/studies/ci_job_secrets.md
+++ b/doc/architecture/blueprints/secret_manager/studies/ci_job_secrets.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/studies/ci_job_secrets/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_manager/studies/ci_job_secrets/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/security_policies_database_read_model/_index.md b/doc/architecture/blueprints/security_policies_database_read_model/_index.md
index 7654d6edd1d95381acceb01d6d350846d7fd16c4..07533da68091290840e33b235fa15ca39bb93553 100644
--- a/doc/architecture/blueprints/security_policies_database_read_model/_index.md
+++ b/doc/architecture/blueprints/security_policies_database_read_model/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/security_policies_database_read_model/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/security_policies_database_read_model/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/ssh_certificates/_index.md b/doc/architecture/blueprints/ssh_certificates/_index.md
index df489c311e41f623674f35b344cd1b9682ed79b5..a81a8816ccb9fc97c2a54dc2269df66db110e35e 100644
--- a/doc/architecture/blueprints/ssh_certificates/_index.md
+++ b/doc/architecture/blueprints/ssh_certificates/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ssh_certificates/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/ssh_certificates/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/tailwindcss/_index.md b/doc/architecture/blueprints/tailwindcss/_index.md
index e34a8df13c65d45199d658a71470b0cd7167e236..0c9b9727bedca0219bec4c68d0d8378f8520d472 100644
--- a/doc/architecture/blueprints/tailwindcss/_index.md
+++ b/doc/architecture/blueprints/tailwindcss/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/tailwindcss/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/tailwindcss/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/transfer_data/_index.md b/doc/architecture/blueprints/transfer_data/_index.md
index b3290cbc8c8b584a0ce7f0a8e14b66ab36be294d..836939ae6cbfcc19c3221b66ed8e8b5a23c334d6 100644
--- a/doc/architecture/blueprints/transfer_data/_index.md
+++ b/doc/architecture/blueprints/transfer_data/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/transfer_data/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/transfer_data/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/transfer_data/repository.md b/doc/architecture/blueprints/transfer_data/repository.md
index de010d07eaeb2f13cd6f10b6f6fb99f9ed09cb12..ac1693f70a337d6fecb88b40b958754e29da9346 100644
--- a/doc/architecture/blueprints/transfer_data/repository.md
+++ b/doc/architecture/blueprints/transfer_data/repository.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/transfer_data/repository/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/transfer_data/repository/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/architecture/blueprints/work_items/_index.md b/doc/architecture/blueprints/work_items/_index.md
index d3f4f33add563b02a8852ed8b25f604604fa308c..615f77ffbaa4e7d64d7475e62d7f3a23959df79c 100644
--- a/doc/architecture/blueprints/work_items/_index.md
+++ b/doc/architecture/blueprints/work_items/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/'
-remove_date: '2025-07-08'
+redirect_to: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/
+remove_date: "2025-07-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/ci/_index.md b/doc/ci/_index.md
index 7fd236866e834fef6fa41cd205da0a524214335e..6469baff4f681dc65edf21c027cabca3df9a9f07 100644
--- a/doc/ci/_index.md
+++ b/doc/ci/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Get started with GitLab CI/CD
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
CI/CD is a continuous method of software development, where you continuously build,
test, deploy, and monitor iterative code changes.
diff --git a/doc/ci/caching/_index.md b/doc/ci/caching/_index.md
index 5d7b97354d967a7c4fb19e50d0d3305c6fda3d7c..c83280e65779f9d51c7afaf89593e3c401810a1c 100644
--- a/doc/ci/caching/_index.md
+++ b/doc/ci/caching/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Caching in GitLab CI/CD
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A cache is one or more files a job downloads and saves. Subsequent jobs that use
the same cache don't have to download the files again, so they execute more quickly.
@@ -98,7 +101,11 @@ the global fallback cache is fetched every time a cache is not found.
### Per-cache fallback keys
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110467) in GitLab 16.0
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110467) in GitLab 16.0
+
+{{< /history >}}
Each cache entry supports up to five fallback keys with the [`fallback_keys` keyword](../yaml/_index.md#cachefallback_keys).
When a job does not find a cache key, the job attempts to retrieve a fallback cache instead.
@@ -140,7 +147,11 @@ Fallback keys follow the same processing logic as `cache:key`:
### Global fallback key
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4.
+
+{{< /history >}}
You can use the `$CI_COMMIT_REF_SLUG` [predefined variable](../variables/predefined_variables.md)
to specify your [`cache:key`](../yaml/_index.md#cachekey). For example, if your
@@ -264,7 +275,11 @@ cache:
### Use a variable to control a job's cache policy
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371480) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371480) in GitLab 16.1.
+
+{{< /history >}}
To reduce duplication of jobs where the only difference is the pull policy, you can use a [CI/CD variable](../variables/_index.md).
@@ -512,7 +527,11 @@ be overwritten because caches are restored before artifacts.
#### Cache key names
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330047) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330047) in GitLab 15.0.
+
+{{< /history >}}
A suffix is added to the cache key, with the exception of the [global fallback cache key](#global-fallback-key).
@@ -526,7 +545,11 @@ and `feature`, then the following table represents the resulting cache keys:
##### Use the same cache for all branches
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361643) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361643) in GitLab 15.0.
+
+{{< /history >}}
If you do not want to use [cache key names](#cache-key-names),
you can have all branches (protected and unprotected) use the same cache.
@@ -637,9 +660,12 @@ You can clear the cache in the GitLab UI:
On the next commit, your CI/CD jobs use a new cache.
-NOTE:
+{{< alert type="note" >}}
+
Each time you clear the cache manually, the [internal cache name](#where-the-caches-are-stored) is updated. The name uses the format `cache-<index>`, and the index increments by one. The old cache is not deleted. You can manually delete these files from the runner storage.
+{{< /alert >}}
+
## Troubleshooting
### Cache mismatch
diff --git a/doc/ci/chatops/_index.md b/doc/ci/chatops/_index.md
index a111043a8bd6ec24a7379188513f3b908f47006b..e8bfc864ba5c168193376fd266985d58894d2613 100644
--- a/doc/ci/chatops/_index.md
+++ b/doc/ci/chatops/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab ChatOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use GitLab ChatOps to interact with CI/CD jobs through chat services
like Slack.
diff --git a/doc/ci/ci_cd_for_external_repos/_index.md b/doc/ci/ci_cd_for_external_repos/_index.md
index df1a9ab5d8b4c976ca7268cf638c316a605f6b49..ed3405b34c28c1553d38a3163176f2be3fba7cd7 100644
--- a/doc/ci/ci_cd_for_external_repos/_index.md
+++ b/doc/ci/ci_cd_for_external_repos/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab CI/CD for external repositories
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab CI/CD can be used with [GitHub](github_integration.md), [Bitbucket Cloud](bitbucket_integration.md),
or any other Git server. Some [known issues](#known-issues) exist.
@@ -24,7 +27,7 @@ snippets disabled. These features
To connect to an external repository:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Run CI/CD for external repository**.
1. Select **GitHub** or **Repository by URL**.
1. Complete the fields.
diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md
index 8cbe866975e274c2f7477f983729583cfd8a9907..e1426a37f501a4bda770391c7ad6f21a7cab4cad 100644
--- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md
+++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using GitLab CI/CD with a Bitbucket Cloud repository
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab CI/CD can be used with Bitbucket Cloud by:
@@ -26,7 +29,7 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:
1. In GitLab, create a project:
- 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+ 1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Run CI/CD for external repository**.
1. Select **Repository by URL**.
1. Complete the fields:
diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md
index 0f9790c0975de50485b5edfe44cecfb930756beb..81183bf9ce6eba898610991f448968c2a27ac601 100644
--- a/doc/ci/ci_cd_for_external_repos/github_integration.md
+++ b/doc/ci/ci_cd_for_external_repos/github_integration.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using GitLab CI/CD with a GitHub repository
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab CI/CD can be used with **GitHub.com** and **GitHub Enterprise** by
creating a [CI/CD project](_index.md) to connect your GitHub repository to
@@ -16,11 +19,14 @@ GitLab.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
Watch a video on [Using GitLab CI/CD pipelines with GitHub repositories](https://www.youtube.com/watch?v=qgl3F2j-1cI).
-NOTE:
+{{< alert type="note" >}}
+
Because of [GitHub limitations](https://gitlab.com/gitlab-org/gitlab/-/issues/9147),
[GitHub OAuth](../../integration/github.md#enable-github-oauth-in-gitlab)
cannot be used to authenticate with GitHub as an external CI/CD repository.
+{{< /alert >}}
+
## Connect with personal access token
Personal access tokens can only be used to connect GitHub.com
@@ -36,7 +42,7 @@ repositories:
`repo` and `admin:repo_hook` so that GitLab can access your project,
update commit statuses, and create a web hook to notify GitLab of new commits.
1. In GitLab, create a project:
- 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+ 1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Run CI/CD for external repository**.
1. Select **GitHub**.
1. For **Personal access token**, paste the token.
@@ -63,7 +69,7 @@ To manually enable GitLab CI/CD for your repository:
1. Enter a **Token description** and update the scope to allow
`repo` so that GitLab can access your project and update commit statuses.
1. In GitLab, create a project:
- 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+ 1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Run CI/CD for external repository** and **Repository by URL**.
1. In the **Git repository URL** field, enter the HTTPS URL for your GitHub repository.
If your project is private, use the personal access token you just created for authentication.
diff --git a/doc/ci/cloud_deployment/_index.md b/doc/ci/cloud_deployment/_index.md
index 0d3609be038c5728e70bcf9a35ea9c72f8f09766..5c9d7100d06097091b4e2d49d03f58e4211518ba 100644
--- a/doc/ci/cloud_deployment/_index.md
+++ b/doc/ci/cloud_deployment/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deploy to AWS from GitLab CI/CD
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides Docker images with the libraries and tools you need to deploy
to AWS. You can reference these images in your CI/CD pipeline.
@@ -15,12 +18,15 @@ to AWS. You can reference these images in your CI/CD pipeline.
If you're using GitLab.com and deploying to the [Amazon Elastic Container Service](https://aws.amazon.com/ecs/) (ECS),
read about [deploying to ECS](ecs/deploy_to_aws_ecs.md).
-NOTE:
+{{< alert type="note" >}}
+
If you are comfortable configuring a deployment yourself and just need to retrieve
AWS credentials, consider using [ID tokens and OpenID Connect](../cloud_services/aws/_index.md).
ID tokens are more secure than storing credentials in CI/CD variables, but do not
work with the guidance on this page.
+{{< /alert >}}
+
## Authenticate GitLab with AWS
To use GitLab CI/CD to connect to AWS, you must authenticate.
@@ -102,10 +108,13 @@ To deploy to your ECS cluster:
| `CI_AWS_ECS_TASK_DEFINITION` | If the task definition is in ECS, the name of the task definition tied to the service. |
| `CI_AWS_ECS_TASK_DEFINITION_FILE` | If the task definition is a JSON file in GitLab, the filename, including the path. For example, `ci/aws/my_task_definition.json`. If the name of the task definition in your JSON file is the same name as an existing task definition in ECS, then a new revision is created when CI/CD runs. Otherwise, a brand new task definition is created, starting at revision 1. |
- WARNING:
+ {{< alert type="warning" >}}
+
If you define both `CI_AWS_ECS_TASK_DEFINITION_FILE` and `CI_AWS_ECS_TASK_DEFINITION`,
`CI_AWS_ECS_TASK_DEFINITION_FILE` takes precedence.
+ {{< /alert >}}
+
1. Include this template in `.gitlab-ci.yml`:
```yaml
@@ -129,11 +138,15 @@ Finally, your AWS ECS service is updated with the new revision of the
task definition, making the cluster pull the newest version of your
application.
-NOTE:
+{{< alert type="note" >}}
+
ECS deploy jobs wait for the rollout to complete before exiting. To disable this behavior,
set `CI_AWS_ECS_WAIT_FOR_ROLLOUT_COMPLETE_DISABLED` to a non-empty value.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The [`AWS/Deploy-ECS.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/AWS/Deploy-ECS.gitlab-ci.yml)
template includes two templates: [`Jobs/Build.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Build.gitlab-ci.yml)
and [`Jobs/Deploy/ECS.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy/ECS.gitlab-ci.yml). Do not include these templates on their own. Only include the
@@ -142,6 +155,8 @@ used only with the main template. They may move or change unexpectedly. Also, th
these templates may change. Do not override these job names in your own pipeline,
because the override stops working when the name changes.
+{{< /alert >}}
+
## Deploy your application to EC2
GitLab provides a template, called `AWS/CF-Provision-and-Deploy-EC2`,
diff --git a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md
index 880d8810e59dca5bdd1de5ae36d48cf25fd59332..4a54c21c8284296b84029a63995b93958aa042ce 100644
--- a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md
+++ b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deploy to Amazon Elastic Container Service
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This step-by-step guide helps you deploy a project hosted on GitLab.com to
the Amazon [Elastic Container Service (ECS)](https://aws.amazon.com/ecs/).
@@ -42,7 +45,7 @@ For the first step here, you create a demo application from a project template.
Use a GitLab project template to get started. As the name suggests, these projects provide a
bare-bones application built on some well-known frameworks.
-1. In GitLab on the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. In GitLab on the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**, where you can choose from a Ruby on Rails, Spring, or
NodeJS Express project. For this guide, use the Ruby on Rails template.
1. Give your project a name. In this example, it's named `ecs-demo`. Make it public so that you can
@@ -200,9 +203,12 @@ create a deployer user on AWS:
1. Select **Create user**.
1. Take note of the **Access key ID** and **Secret access key** of the created user.
-NOTE:
+{{< alert type="note" >}}
+
Do not share the secret access key in a public place. You must save it in a secure place.
+{{< /alert >}}
+
### Setup credentials in GitLab to let pipeline jobs access to ECS
You can register the access information in [GitLab CI/CD Variables](../../variables/_index.md).
@@ -237,10 +243,13 @@ Change a file in the project and see if it's reflected in the demo application o
Congratulations! You successfully set up continuous deployment to ECS.
-NOTE:
+{{< alert type="note" >}}
+
ECS deploy jobs wait for the rollout to complete before exiting. To disable this behavior,
set `CI_AWS_ECS_WAIT_FOR_ROLLOUT_COMPLETE_DISABLED` to a non-empty value.
+{{< /alert >}}
+
## Set up review apps
To use [review apps](../../../development/testing_guide/review_apps.md) with ECS:
diff --git a/doc/ci/cloud_deployment/heroku.md b/doc/ci/cloud_deployment/heroku.md
index 72d132f5af18986931c66a7b1e78b4a2d07daf1a..f0a0fe85d0bcbc1f47d9a94e56430bc46b0139bf 100644
--- a/doc/ci/cloud_deployment/heroku.md
+++ b/doc/ci/cloud_deployment/heroku.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use GitLab CI/CD to deploy to Heroku
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can deploy an application to Heroku by using GitLab CI/CD.
diff --git a/doc/ci/cloud_services/_index.md b/doc/ci/cloud_services/_index.md
index fe9d0bc786c6cdeebc7f42c3a948025556b0e297..95d582e82e299f827c9a2162b32b67456c6798de 100644
--- a/doc/ci/cloud_services/_index.md
+++ b/doc/ci/cloud_services/_index.md
@@ -5,16 +5,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Connect to cloud services
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [ID tokens](../yaml/_index.md#id_tokens) to support any OIDC provider, including HashiCorp Vault, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [ID tokens](../yaml/_index.md#id_tokens) to support any OIDC provider, including HashiCorp Vault, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
`CI_JOB_JWT` and `CI_JOB_JWT_V2` were [deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated)
and are scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/_index.md#id_tokens) instead.
+{{< /alert >}}
+
GitLab CI/CD supports [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) to
give your build and deployment jobs access to cloud credentials and services.
Historically, teams stored secrets in projects or applied permissions on the GitLab Runner
@@ -35,12 +45,15 @@ ID tokens support cloud providers with OIDC, including:
- GCP
- HashiCorp Vault
-NOTE:
+{{< alert type="note" >}}
+
Configuring OIDC enables JWT token access to the target environments for all pipelines.
When you configure OIDC for a pipeline, you should complete a software supply chain security
review for the pipeline, focusing on the additional access. For more information about supply chain attacks, see
[How a DevOps Platform helps protect against supply chain attacks](https://about.gitlab.com/blog/2021/04/28/devops-platform-supply-chain-attacks/).
+{{< /alert >}}
+
## Use cases
- Removes the need to store secrets in your GitLab group or project. Temporary credentials can be retrieved from your cloud provider through OIDC.
diff --git a/doc/ci/cloud_services/aws/_index.md b/doc/ci/cloud_services/aws/_index.md
index f8650c93a04af7aa6eb33a9351ab1088cf84686a..225a60540e18bc20d43ea4066fefd232695ff439 100644
--- a/doc/ci/cloud_services/aws/_index.md
+++ b/doc/ci/cloud_services/aws/_index.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure OpenID Connect in AWS to retrieve temporary credentials
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
`CI_JOB_JWT_V2` was [deprecated in GitLab 15.9](../../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated)
and is scheduled to be removed in GitLab 17.0. Use [ID tokens](../../yaml/_index.md#id_tokens) instead.
+{{< /alert >}}
+
In this tutorial, we'll show you how to use a GitLab CI/CD job with a JSON web token (JWT) to retrieve temporary credentials from AWS without needing to store secrets.
To do this, you must configure OpenID Connect (OIDC) for ID federation between GitLab and AWS. For background and requirements for integrating GitLab using OIDC, see [Connect to cloud services](../_index.md).
diff --git a/doc/ci/cloud_services/azure/_index.md b/doc/ci/cloud_services/azure/_index.md
index b253c2c9e04fe09e9110a7625e8cf4ef62d7f732..dd2542582901dd5d9bdb5d746436d62ceb168ba0 100644
--- a/doc/ci/cloud_services/azure/_index.md
+++ b/doc/ci/cloud_services/azure/_index.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure OpenID Connect in Azure to retrieve temporary credentials
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
`CI_JOB_JWT_V2` was [deprecated in GitLab 15.9](../../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated)
and is scheduled to be removed in GitLab 17.0. Use [ID tokens](../../yaml/_index.md#id_tokens) instead.
+{{< /alert >}}
+
This tutorial demonstrates how to use a JSON web token (JWT) in a GitLab CI/CD job
to retrieve temporary credentials from Azure without needing to store secrets.
diff --git a/doc/ci/cloud_services/google_cloud/_index.md b/doc/ci/cloud_services/google_cloud/_index.md
index c59df6d4064d70321d0824bc2b518c736cab27d7..dd7eb33598f51413d427895cae4cf832f885308d 100644
--- a/doc/ci/cloud_services/google_cloud/_index.md
+++ b/doc/ci/cloud_services/google_cloud/_index.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure OpenID Connect with GCP Workload Identity Federation
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
`CI_JOB_JWT_V2` was [deprecated in GitLab 15.9](../../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated)
and is scheduled to be removed in GitLab 17.0. Use [ID tokens](../../yaml/_index.md#id_tokens) instead.
+{{< /alert >}}
+
This tutorial demonstrates authenticating to Google Cloud from a GitLab CI/CD job
using a JSON Web Token (JWT) token and Workload Identity Federation. This configuration
generates on-demand, short-lived credentials without needing to store any secrets.
@@ -25,10 +31,13 @@ This tutorial assumes you have a Google Cloud account and a Google Cloud project
Your account must have at least the **Workload Identity Pool Admin** permission
on the Google Cloud project.
-NOTE:
+{{< alert type="note" >}}
+
If you would prefer to use a Terraform module and a CI/CD template instead of this tutorial,
see [How OIDC can simplify authentication of GitLab CI/CD pipelines with Google Cloud](https://about.gitlab.com/blog/2023/06/28/introduction-of-oidc-modules-for-integration-between-google-cloud-and-gitlab-ci/).
+{{< /alert >}}
+
To complete this tutorial:
1. [Create the Google Cloud Workload Identity Pool](#create-the-google-cloud-workload-identity-pool).
diff --git a/doc/ci/components/_index.md b/doc/ci/components/_index.md
index 8a8132043f133697fed4319d79310c061f67dae0..3c82fd16d7852f3f92bbbdfafb38b11c46119ef3 100644
--- a/doc/ci/components/_index.md
+++ b/doc/ci/components/_index.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI/CD components
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Introduced as an [experimental feature](../../policy/development_stages_support.md#experiment) in GitLab 16.0, [with a flag](../../administration/feature_flags.md) named `ci_namespace_catalog_experimental`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/9897) in GitLab 16.2.
-> - [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](../../policy/development_stages_support.md#beta) in GitLab 16.6.
-> - [Made generally available](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/134062) in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced as an [experimental feature](../../policy/development_stages_support.md#experiment) in GitLab 16.0, [with a flag](../../administration/feature_flags.md) named `ci_namespace_catalog_experimental`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/groups/gitlab-org/-/epics/9897) in GitLab 16.2.
+- [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](../../policy/development_stages_support.md#beta) in GitLab 16.6.
+- [Made generally available](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/134062) in GitLab 17.0.
+
+{{< /history >}}
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.
@@ -40,7 +47,11 @@ blog post.
## Component project
-> - The maximum number of components per project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/436565) from 10 to 30 in GitLab 16.9.
+{{< history >}}
+
+- The maximum number of components per project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/436565) from 10 to 30 in GitLab 16.9.
+
+{{< /history >}}
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 30 components per project.
@@ -86,9 +97,12 @@ The repository must contain:
- 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`.
-NOTE:
+{{< alert type="note" >}}
+
Optionally, each component can also have its own `README.md` file that provides more detailed information, and can be linked from the top-level `README.md` file. This helps to provide a better overview of your component project and how to use it.
+{{< /alert >}}
+
You should also:
- Configure the project's `.gitlab-ci.yml` to [test the components](#test-the-component)
@@ -165,12 +179,15 @@ the component's configuration.
To use GitLab.com components on a GitLab Self-Managed instance, you must
[mirror the component project](#use-a-gitlabcom-component-on-gitlab-self-managed).
-WARNING:
+{{< alert type="warning" >}}
+
If a component requires the use of tokens, passwords, or other sensitive data to function,
be sure to audit the component's source code to verify that the data is only used to
perform actions that you expect and authorize. You should also use tokens and secrets
with the minimum permissions, access, or scope required to complete the action.
+{{< /alert >}}
+
### Component versions
In order of highest priority first, the component version can be:
@@ -193,7 +210,11 @@ might not be published in the CI/CD catalog, but could be used for testing.
#### Semantic version ranges
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/450835) in GitLab 16.11
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/450835) in GitLab 16.11
+
+{{< /history >}}
When [referencing a CI/CD catalog component](#component-versions), you can use a
special format to specify the latest [semantic version](#semantic-versioning) in a range.
@@ -339,9 +360,12 @@ create-release:
After committing and pushing changes, the pipeline tests the component, then creates
a release if the earlier jobs pass.
-NOTE:
+{{< alert type="note" >}}
+
Authentication is necessary if the project is private.
+{{< /alert >}}
+
#### Test a component against sample files
In some cases, components require source files to interact with. For example, a component
@@ -550,13 +574,20 @@ In other cases, CI/CD variables might still be preferred. For example:
## CI/CD Catalog
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407249) as an [experiment](../../policy/development_stages_support.md#experiment) in GitLab 16.1.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/432045) to [beta](../../policy/development_stages_support.md#beta) in GitLab 16.7.
-> - [Made Generally Available](https://gitlab.com/gitlab-org/gitlab/-/issues/454306) in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407249) as an [experiment](../../policy/development_stages_support.md#experiment) in GitLab 16.1.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/432045) to [beta](../../policy/development_stages_support.md#beta) in GitLab 16.7.
+- [Made Generally Available](https://gitlab.com/gitlab-org/gitlab/-/issues/454306) in GitLab 17.0.
+
+{{< /history >}}
The [CI/CD Catalog](https://gitlab.com/explore/catalog) is a list of projects with published CI/CD components you can use
to extend your CI/CD workflow.
@@ -659,7 +690,11 @@ is published to the CI/CD catalog.
#### Semantic versioning
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427286) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427286) in GitLab 16.10.
+
+{{< /history >}}
When tagging and [releasing new versions](#publish-a-new-release) of components to the Catalog,
you must use [semantic versioning](https://semver.org). Semantic versioning is the standard
@@ -672,21 +707,28 @@ For example, `1.0.0`, `2.3.4`, and `1.0.0-alpha` are all valid semantic versions
To remove a component project from the catalog, turn off the [**CI/CD Catalog resource**](#set-a-component-project-as-a-catalog-project)
toggle in the project settings.
-WARNING:
+{{< alert type="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.
+{{< /alert >}}
+
To publish the component project in the catalog again, you need to [publish a new release](#publish-a-new-release).
### Verified component creators
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433443) in GitLab 16.11
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433443) in GitLab 16.11
+
+{{< /history >}}
Some CI/CD components are badged with an icon to show that the component was created
and is maintained by users verified by GitLab:
-- GitLab-maintained (**{tanuki-verified}**): Components that are created and maintained by GitLab.
-- GitLab Partner (**{partner-verified}**): Components that are independently created
+- GitLab-maintained ({{< icon name="tanuki-verified" >}}): Components that are created and maintained by GitLab.
+- GitLab Partner ({{< icon name="partner-verified" >}}): Components that are independently created
and maintained by a GitLab-verified partner.
GitLab partners can contact a member of the GitLab Partner Alliance to have their
@@ -695,13 +737,16 @@ and is maintained by users verified by GitLab:
creates an internal request issue on behalf of the verified partner (GitLab team members only):
`https://gitlab.com/gitlab-com/support/internal-requests/-/issues/new?issuable_template=CI%20Catalog%20Badge%20Request`.
- WARNING:
+ {{< alert type="warning" >}}
+
GitLab Partner-created components are provided **as-is**, without warranty of any kind.
An end user's use of a GitLab Partner-created component is at their own risk and
GitLab shall have no indemnification obligations nor any liability of any type
with respect to the end user's use of the component. The end user's use of such content
and any liability related thereto shall be between the publisher of the content and the end user.
+ {{< /alert >}}
+
## Convert a CI/CD template to a component
Any existing CI/CD template that you use in projects by using the `include:` syntax
@@ -722,9 +767,12 @@ You can learn more by following a practical example for [migrating the Go CI/CD
## Use a GitLab.com component on GitLab Self-Managed
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The CI/CD catalog of a fresh install of a GitLab instance starts with no published CI/CD components.
To populate your instance's catalog, you can:
diff --git a/doc/ci/components/examples.md b/doc/ci/components/examples.md
index 9da71a46957126fa41fb1f655a82ade903a20a55..243637b1b6512bc3cd5a2fcf807cd40a816c0738 100644
--- a/doc/ci/components/examples.md
+++ b/doc/ci/components/examples.md
@@ -5,9 +5,12 @@ info: This page is maintained by Developer Relations, author @dnsmichi, see http
title: CI/CD component examples
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Test a component
@@ -241,10 +244,13 @@ compile:
- mybinaries
```
-NOTE:
+{{< alert type="note" >}}
+
You can also start with migrating one job, instead of all jobs. Follow the instructions below,
and only migrate the `build` CI/CD job in the first iteration.
+{{< /alert >}}
+
The CI/CD template migration involves the following steps:
1. Analyze the CI/CD jobs and dependencies, and define migration actions:
diff --git a/doc/ci/debugging.md b/doc/ci/debugging.md
index 1d375300e025bb0746b63e027b54288a6c652a7a..eb4293f4885cf3c0235be995935636a18ea2f4cd 100644
--- a/doc/ci/debugging.md
+++ b/doc/ci/debugging.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Debugging CI/CD pipelines
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides several tools to help make it easier to debug your CI/CD configuration.
@@ -230,10 +233,13 @@ job1:
- rspec.xmp
```
-WARNING:
+{{< alert type="warning" >}}
+
Do not save tokens, passwords, or other sensitive information in artifacts,
as they could be viewed by any user with access to the pipelines.
+{{< /alert >}}
+
### Run the job's commands locally
You can use a tool like [Rancher Desktop](https://rancherdesktop.io/) or [similar alternatives](https://handbook.gitlab.com/handbook/tools-and-tips/mac/#docker-desktop)
@@ -378,7 +384,7 @@ This issue is [resolved](https://gitlab.com/gitlab-org/gitlab/-/issues/229352) i
### `Checking pipeline status` message
-This message displays with a spinning status icon (**{spinner}**) when the merge request
+This message displays with a spinning status icon ({{< icon name="spinner" >}}) when the merge request
does not yet have a pipeline associated with the latest commit. This might be because:
- GitLab hasn't finished creating the pipeline yet.
@@ -437,7 +443,11 @@ Ensure that included configuration files do not create a loop of references to e
### `Failed to pull image` messages
-> - **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
+{{< history >}}
+
+- **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
+
+{{< /history >}}
A runner might return a `Failed to pull image` message when trying to pull a container image
in a CI/CD job.
diff --git a/doc/ci/docker/_index.md b/doc/ci/docker/_index.md
index ee48b7ea4b0743ef24f61a3d3127e1e0c154ac20..2e90ea1df88bf0a300e2537f2e72cae033a2a79a 100644
--- a/doc/ci/docker/_index.md
+++ b/doc/ci/docker/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Docker integration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can incorporate [Docker](https://www.docker.com) into your CI/CD workflow in two primary ways:
diff --git a/doc/ci/docker/authenticate_registry.md b/doc/ci/docker/authenticate_registry.md
index 583357b88728d0bfc6c52d9549cc9cffac17ea3b..43bb16cbf5bae91c396c15dc9622d0c5eefb8828 100644
--- a/doc/ci/docker/authenticate_registry.md
+++ b/doc/ci/docker/authenticate_registry.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Authenticate with registry in Docker-in-Docker
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you use Docker-in-Docker, the
[standard authentication methods](using_docker_images.md#access-an-image-from-a-private-container-registry)
diff --git a/doc/ci/docker/buildah_rootless_tutorial.md b/doc/ci/docker/buildah_rootless_tutorial.md
index 9f38629bb2df0c98072be53913f9ea2136828a8a..569ea976421fbb5c7c7a241f7fec64113fc4062a 100644
--- a/doc/ci/docker/buildah_rootless_tutorial.md
+++ b/doc/ci/docker/buildah_rootless_tutorial.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Use Buildah in a rootless container with GitLab Runner Operator on OpenShift'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This tutorial teaches you how to successfully build images using the `buildah` tool,
with GitLab Runner deployed using [GitLab Runner Operator](https://gitlab.com/gitlab-org/gl-openshift/gitlab-runner-operator)
diff --git a/doc/ci/docker/docker_layer_caching.md b/doc/ci/docker/docker_layer_caching.md
index ff42005694b4d035ec0f573e9a343bf943328462..5d00a76ab49e4a0dedaa878b95dbeeb36334221d 100644
--- a/doc/ci/docker/docker_layer_caching.md
+++ b/doc/ci/docker/docker_layer_caching.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Make Docker-in-Docker builds faster with Docker layer caching
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When using Docker-in-Docker, Docker downloads all layers of your image every
time you create a build. Recent versions of Docker (Docker 1.13 and later) can
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md
index bca891dbd9e791667ec74a4de098781969614be5..e51710aa45e6d22bd84ed857a6e14271b017b229 100644
--- a/doc/ci/docker/using_docker_build.md
+++ b/doc/ci/docker/using_docker_build.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Docker to build Docker images
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use GitLab CI/CD with Docker to create Docker images.
For example, you can create a Docker image of your application,
@@ -105,11 +108,14 @@ You can use the Docker executor to run jobs in a Docker container.
The Docker daemon supports connections over TLS. TLS is the default in Docker 19.03.12 and later.
-WARNING:
+{{< alert type="warning" >}}
+
This task enables `--docker-privileged`, which effectively disables the container's security mechanisms and exposes your host to privilege
escalation. This action can cause container breakout. For more information, see
[runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities).
+{{< /alert >}}
+
To use Docker-in-Docker with TLS enabled:
1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/).
@@ -607,9 +613,12 @@ of this file. You can do this with a command like:
kubectl create configmap docker-daemon --namespace gitlab-runner --from-file /tmp/daemon.json
```
-NOTE:
+{{< alert type="note" >}}
+
You must use the namespace that the Kubernetes executor for GitLab Runner uses to create job pods.
+{{< /alert >}}
+
After the ConfigMap is created, you can update the `config.toml`
file to mount the file to `/etc/docker/daemon.json`. This update
mounts the file for **every** container created by GitLab Runner.
@@ -676,9 +685,12 @@ When using Docker-in-Docker, Docker downloads all layers of your image every tim
## Use the OverlayFS driver
-NOTE:
+{{< alert type="note" >}}
+
The instance runners on GitLab.com use the `overlay2` driver by default.
+{{< /alert >}}
+
By default, when using `docker:dind`, Docker uses the `vfs` storage driver, which
copies the file system on every run. You can avoid this disk-intensive operation by using a different driver, for example `overlay2`.
diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md
index df9a01a4d4f4a8ac7f9535007335752a6a29f5b6..a0bcc26eb89f97ca2676493b3725ad480ca6e24f 100644
--- a/doc/ci/docker/using_docker_images.md
+++ b/doc/ci/docker/using_docker_images.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Run your CI/CD jobs in Docker containers
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can run your CI/CD jobs in Docker containers hosted on dedicated CI/CD build servers or your local machine.
@@ -98,7 +101,11 @@ The image name must be in one of the following formats:
## Extended Docker configuration options
-> - Introduced in GitLab and GitLab Runner 9.4.
+{{< history >}}
+
+- Introduced in GitLab and GitLab Runner 9.4.
+
+{{< /history >}}
You can use a string or a map for the `image` or `services` entries:
@@ -138,7 +145,11 @@ When a CI job runs in a Docker container, the `before_script`, `script`, and `af
### Override the entrypoint of an image
-> - Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](../docker/using_docker_images.md#extended-docker-configuration-options).
+{{< history >}}
+
+- Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](../docker/using_docker_images.md#extended-docker-configuration-options).
+
+{{< /history >}}
Before explaining the available entrypoint override methods, let's describe
how the runner starts. It uses a Docker image for the containers used in the
@@ -296,8 +307,11 @@ Use one of the following methods to determine the value for `DOCKER_AUTH_CONFIG`
bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
```
- NOTE:
- If your username includes special characters like `@`, you must escape them with a backslash (<code>\</code>) to prevent authentication problems.
+ {{< alert type="note" >}}
+
+If your username includes special characters like `@`, you must escape them with a backslash (<code>\</code>) to prevent authentication problems.
+
+ {{< /alert >}}
Create the Docker JSON configuration content as follows:
@@ -409,7 +423,11 @@ pulling from Docker Hub fails. Docker daemon tries to use the same credentials f
### Use Credential Helpers
-> - Introduced in GitLab Runner 12.0.
+{{< history >}}
+
+- Introduced in GitLab Runner 12.0.
+
+{{< /history >}}
As an example, let's assume that you want to use the `<aws_account_id>.dkr.ecr.<region>.amazonaws.com/private/image:latest`
image. This image is private and requires you to sign in to a private container registry.
@@ -443,9 +461,12 @@ To configure access for `<aws_account_id>.dkr.ecr.<region>.amazonaws.com`, follo
}
```
- NOTE:
+ {{< alert type="note" >}}
+
If you use `{"credsStore": "ecr-login"}`, set the region explicitly in the AWS shared configuration file (`~/.aws/config`). The region must be specified when the ECR Credential Helper retrieves the authorization token.
+ {{< /alert >}}
+
- Or, if you're running self-managed runners,
add the previous JSON to `${GITLAB_RUNNER_HOME}/.docker/config.json`.
GitLab Runner reads this configuration file and uses the needed helper for this
diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md
index d2ce25f1817ec373a281e719dbaaf1e376592b42..31d0cad9b4437b561cfff386c672e99a06e9e926 100644
--- a/doc/ci/docker/using_kaniko.md
+++ b/doc/ci/docker/using_kaniko.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use kaniko to build Docker images
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[kaniko](https://github.com/GoogleContainerTools/kaniko) is a tool to build
container images from a Dockerfile, inside a container or Kubernetes cluster.
diff --git a/doc/ci/environments/_index.md b/doc/ci/environments/_index.md
index e8a1cfe752ab5307947ab21eb7434ad444433218..8a4a1f56d567b758cd16ee74cd2cd1db779c7b4a 100644
--- a/doc/ci/environments/_index.md
+++ b/doc/ci/environments/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Environments
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Environments connect GitLab to your infrastructure. An environment:
@@ -42,8 +45,12 @@ Deployments show up in this list only after a deployment job has created them.
### Environment URL
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/337417) to persist arbitrary URLs in GitLab 15.2 [with a flag](../../administration/feature_flags.md) named `soft_validation_on_external_url`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/337417) in GitLab 15.3. [Feature flag `soft_validation_on_external_url`](https://gitlab.com/gitlab-org/gitlab/-/issues/367206) removed.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/337417) to persist arbitrary URLs in GitLab 15.2 [with a flag](../../administration/feature_flags.md) named `soft_validation_on_external_url`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/337417) in GitLab 15.3. [Feature flag `soft_validation_on_external_url`](https://gitlab.com/gitlab-org/gitlab/-/issues/367206) removed.
+
+{{< /history >}}
The [environment URL](../yaml/_index.md#environmenturl) is displayed in a few
places in GitLab:
@@ -121,10 +128,13 @@ To create a static environment, in your `.gitlab-ci.yml` file:
1. In the job, define the environment `name` and `url`. If an
environment of that name doesn't exist when the pipeline runs, it is created.
-NOTE:
+{{< alert type="note" >}}
+
Some characters cannot be used in environment names. For more information about the
`environment` keywords, see the [`.gitlab-ci.yml` keyword reference](../yaml/_index.md#environment).
+{{< /alert >}}
+
For example, to create an environment named `staging`, with URL `https://staging.example.com`:
```yaml
@@ -155,10 +165,13 @@ To create a dynamic environment, in your `.gitlab-ci.yml` file:
environments with the same prefix.
- `url`: Optional. Prefix the hostname with a related CI/CD variable like `$CI_ENVIRONMENT_SLUG`.
-NOTE:
+{{< alert type="note" >}}
+
Some characters cannot be used in environment names. For more information about the
`environment` keywords, see the [`.gitlab-ci.yml` keyword reference](../yaml/_index.md#environment).
+{{< /alert >}}
+
In the following example, every time the `deploy_review_app` job runs the environment's name and
URL are defined using unique values.
@@ -241,9 +254,12 @@ Note the following:
for these jobs. This ensures that runners can fetch the repository even after a feature branch is
deleted. For more information, see [Ref Specs for Runners](../pipelines/_index.md#ref-specs-for-runners).
-NOTE:
+{{< alert type="note" >}}
+
For Windows runners, you should use the PowerShell `Add-Content` command to write to `.env` files.
+{{< /alert >}}
+
```powershell
Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL"
```
@@ -274,8 +290,12 @@ Instead, you can use the [`deployment_tier` keyword](../yaml/_index.md#environme
### Rename an environment
-> - Renaming an environment by using the API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) in GitLab 15.9.
-> - Renaming an environment with the API [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) in GitLab 16.0.
+{{< history >}}
+
+- Renaming an environment by using the API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) in GitLab 15.9.
+- Renaming an environment with the API [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) in GitLab 16.0.
+
+{{< /history >}}
You cannot rename an environment.
@@ -332,9 +352,13 @@ GitLab validates the pipeline configuration at pipeline creation.
## Search environments
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10754) in GitLab 15.5.
-> - [Searching environments within a folder](https://gitlab.com/gitlab-org/gitlab/-/issues/373850) was introduced in GitLab 15.7 with [Feature flag `enable_environments_search_within_folder`](https://gitlab.com/gitlab-org/gitlab/-/issues/382108). Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/382108) in GitLab 17.4. Feature flag `enable_environments_search_within_folder` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10754) in GitLab 15.5.
+- [Searching environments within a folder](https://gitlab.com/gitlab-org/gitlab/-/issues/373850) was introduced in GitLab 15.7 with [Feature flag `enable_environments_search_within_folder`](https://gitlab.com/gitlab-org/gitlab/-/issues/382108). Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/382108) in GitLab 17.4. Feature flag `enable_environments_search_within_folder` removed.
+
+{{< /history >}}
To search environments by name:
@@ -376,11 +400,14 @@ an environment before it can be deleted.
### Stop an environment by using the UI
-NOTE:
+{{< alert type="note" >}}
+
To trigger an `on_stop` action and manually stop an environment from the
Environments view, the stop and deploy jobs must be in the same
[`resource_group`](../yaml/_index.md#resource_group).
+{{< /alert >}}
+
To stop an environment in the GitLab UI:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -461,11 +488,14 @@ stop_review:
You can set an environment to stop automatically after a certain time period.
-NOTE:
+{{< alert type="note" >}}
+
Due to resource limitations, a background worker for stopping environments runs only once every
hour. This means that environments may not be stopped after the exact time period specified, but are
instead stopped when the background worker detects expired environments.
+{{< /alert >}}
+
In your `.gitlab-ci.yml` file, specify the [`environment:auto_stop_in`](../yaml/_index.md#environmentauto_stop_in)
keyword. Specify the time period in natural language, such as `1 hour and 30 minutes` or `1 day`.
After the time period passes, GitLab automatically triggers a job to stop the environment.
@@ -524,7 +554,7 @@ To override an environment's expiration in the UI:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Operate > Environments**.
1. Select the environment name.
-1. in the upper-right corner, select the thumbtack (**{thumbtack}**).
+1. in the upper-right corner, select the thumbtack ({{< icon name="thumbtack" >}}).
To override an environment's expiration in the `.gitlab-ci.yml`:
@@ -536,8 +566,12 @@ manually.
### Clean up stale environments
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108616) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `stop_stale_environments`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112098) in GitLab 15.10. Feature flag `stop_stale_environments` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108616) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `stop_stale_environments`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112098) in GitLab 15.10. Feature flag `stop_stale_environments` removed.
+
+{{< /history >}}
Clean up stale environments when you want to stop old environments in a project.
@@ -558,8 +592,12 @@ Protected environments are ignored and not stopped.
### Run a pipeline job when environment is stopped
-> - Feature flag `environment_stop_actions_include_all_finished_deployments` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435128) in GitLab 16.9. Disabled by default.
-> - Feature flag `environment_stop_actions_include_all_finished_deployments` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150932) in GitLab 17.0.
+{{< history >}}
+
+- Feature flag `environment_stop_actions_include_all_finished_deployments` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435128) in GitLab 16.9. Disabled by default.
+- Feature flag `environment_stop_actions_include_all_finished_deployments` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150932) in GitLab 17.0.
+
+{{< /history >}}
You can define a stop job for the environment with an [`on_stop` action](../yaml/_index.md#environmenton_stop) in the environment's deploy job.
@@ -610,7 +648,11 @@ stop_review_app:
### Multiple stop actions for an environment
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/358911) in GitLab 15.0. [Feature flag `environment_multiple_stop_actions`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86685) removed.
+{{< history >}}
+
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/358911) in GitLab 15.0. [Feature flag `environment_multiple_stop_actions`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86685) removed.
+
+{{< /history >}}
To configure multiple **parallel** stop actions on an environment, specify the
[`on_stop`](../yaml/_index.md#environmenton_stop) keyword across multiple
@@ -619,11 +661,14 @@ To configure multiple **parallel** stop actions on an environment, specify the
When an environment is stopped, the matching `on_stop` actions from only successful deployment jobs are run in parallel, in no particular order.
-NOTE:
+{{< alert type="note" >}}
+
All `on_stop` actions for an environment must belong to the same pipeline. To use multiple `on_stop` actions in
[downstream pipelines](../pipelines/downstream_pipelines.md), you must configure the environment actions in
the parent pipeline. For more information, see [downstream pipelines for deployments](../pipelines/downstream_pipelines.md#advanced-example).
+{{< /alert >}}
+
In the following example, for the `test` environment there are two deployment jobs:
- `deploy-to-cloud-a`
@@ -735,9 +780,12 @@ to get alerts when there are critical issues that need immediate attention.
### View the latest alerts for environments
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you [set up an alert integration](../../operations/incident_management/integrations.md#configuration),
alerts for environments are shown on the environments page. The alert with the highest
@@ -753,9 +801,12 @@ deployment tab from the environment page and select which deployment to roll bac
### Auto Rollback
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In a typical Continuous Deployment workflow, the CI pipeline tests every commit before deploying to
production. However, problematic code can still make it to production. For example, inefficient code
@@ -817,9 +868,12 @@ See [Deployment-only access to protected environments](protected_environments.md
## Web terminals (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< /alert >}}
+
If you deploy to your environments with the help of a deployment service (for example,
the [Kubernetes integration](../../user/infrastructure/clusters/_index.md)), GitLab can open
a terminal session to your environment. You can then debug issues without leaving your web browser.
diff --git a/doc/ci/environments/configure_kubernetes_deployments.md b/doc/ci/environments/configure_kubernetes_deployments.md
index 07cac7fa04e7c083512a2aa01d94157624c96891..c56c0cd737033a1057a40d2dc548b59cb0109ae8 100644
--- a/doc/ci/environments/configure_kubernetes_deployments.md
+++ b/doc/ci/environments/configure_kubernetes_deployments.md
@@ -5,21 +5,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure Kubernetes deployments (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< /alert >}}
+
If you are deploying to a [Kubernetes cluster](../../user/infrastructure/clusters/_index.md)
associated with your project, you can configure these deployments from your
`.gitlab-ci.yml` file.
-NOTE:
+{{< alert type="note" >}}
+
Kubernetes configuration isn't supported for Kubernetes clusters
[managed by GitLab](../../user/project/clusters/gitlab_managed_clusters.md).
+{{< /alert >}}
+
The following configuration options are supported:
- [`namespace`](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md
index c4e99a420b58a4df7e03146bd3a0ca979d3ca072..2a8b695a85edb91e3b78eac75b1fe631b512974a 100644
--- a/doc/ci/environments/deployment_approvals.md
+++ b/doc/ci/environments/deployment_approvals.md
@@ -6,9 +6,12 @@ description: Require approvals prior to deploying to a Protected Environment
title: Deployment approvals
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can require additional approvals for deployments to protected
environments. Deployments are blocked until all required approvals are
@@ -52,8 +55,12 @@ The environments in your project require approval before deployment.
### Add multiple approval rules
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/345678) in GitLab 15.0. [Feature flag `deployment_approval_rules`](https://gitlab.com/gitlab-org/gitlab/-/issues/345678) removed.
-> - UI configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378445) in GitLab 15.11.
+{{< history >}}
+
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/345678) in GitLab 15.0. [Feature flag `deployment_approval_rules`](https://gitlab.com/gitlab-org/gitlab/-/issues/345678) removed.
+- UI configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378445) in GitLab 15.11.
+
+{{< /history >}}
Add multiple approval rules to control who can approve and execute deployment jobs.
@@ -67,8 +74,12 @@ After a deployment job is approved, you must [run the job manually](../jobs/job_
### Allow self-approval
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381418) in GitLab 15.8.
-> - Automatic approval [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124638) in GitLab 16.2 due to [usability issues](https://gitlab.com/gitlab-org/gitlab/-/issues/391258).
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381418) in GitLab 15.8.
+- Automatic approval [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124638) in GitLab 16.2 due to [usability issues](https://gitlab.com/gitlab-org/gitlab/-/issues/391258).
+
+{{< /history >}}
By default, the user who triggers a deployment pipeline can't also approve the deployment job.
diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md
index 6bcb86b85fdb41e6498543b60c9cb5641ff0c3f3..f73b508a13c984c4be3cfa3cca9716284ec29eaf 100644
--- a/doc/ci/environments/deployment_safety.md
+++ b/doc/ci/environments/deployment_safety.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deployment safety
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Deployment jobs](../jobs/_index.md#deployment-jobs) are a specific kind of CI/CD
job. They can be more sensitive than other jobs in a pipeline,
@@ -72,7 +75,11 @@ For more information, see [Resource Group documentation](../resource_groups/_ind
## Prevent outdated deployment jobs
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/363328) in GitLab 15.5 to prevent outdated job runs.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/363328) in GitLab 15.5 to prevent outdated job runs.
+
+{{< /history >}}
The effective execution order of pipeline jobs can vary from run to run, which
could cause undesired behavior. For example, a [deployment job](../jobs/_index.md#deployment-jobs)
@@ -89,7 +96,7 @@ When an older deployment job starts, it fails and is labeled:
- `The deployment job is older than the latest deployment, and therefore failed.`
when viewing the completed job.
-When an older deployment job is manual, the **Run** (**{play}**) button is disabled with a message
+When an older deployment job is manual, the **Run** ({{< icon name="play" >}}) button is disabled with a message
`This deployment job does not run automatically and must be started manually, but it's older than the latest deployment, and therefore can't run.`.
Job age is determined by the job start time, not the commit time, so a newer commit
@@ -97,8 +104,12 @@ can be prevented in some circumstances.
### Job retries for rollback deployments
-> - Rollback via job retry [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378359) in GitLab 15.6.
-> - Job retries for rollback deployments checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/410427) in GitLab 16.3.
+{{< history >}}
+
+- Rollback via job retry [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378359) in GitLab 15.6.
+- Job retries for rollback deployments checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/410427) in GitLab 16.3.
+
+{{< /history >}}
You might need to quickly roll back to a stable, outdated deployment.
By default, pipeline job retries for [deployment rollback](deployments.md#deployment-rollback) are enabled.
diff --git a/doc/ci/environments/deployments.md b/doc/ci/environments/deployments.md
index d0cc9574a4d80dff3a963e5973846c6cf0c1c6d3..ac17787235b20242a28d4da971a1fd17e755ac60 100644
--- a/doc/ci/environments/deployments.md
+++ b/doc/ci/environments/deployments.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deployments
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you deploy a version of your code to an environment, you create a deployment.
There is usually only one active deployment per environment.
@@ -43,10 +46,10 @@ deploy_prod:
The `when: manual` action:
-- Exposes the **Run** (**{play}**) button for the job in the GitLab UI, with the text **Can be manually deployed to <environment>**.
+- Exposes the **Run** ({{< icon name="play" >}}) button for the job in the GitLab UI, with the text **Can be manually deployed to <environment>**.
- Means the `deploy_prod` job must be triggered manually.
-You can find **Run** (**{play}**) in the pipelines, environments, deployments, and jobs views.
+You can find **Run** ({{< icon name="play" >}}) in the pipelines, environments, deployments, and jobs views.
## Track newly included merge requests per deployment
@@ -101,10 +104,13 @@ Archived deployments are still available, in the UI or by using the API, for aud
Also, you can still fetch the deployed commit from the repository
with specifying the commit SHA (for example, `git checkout <deployment-sha>`), even after archive.
-NOTE:
+{{< alert type="note" >}}
+
GitLab preserves all commits as [`keep-around` refs](../../user/project/repository/repository_size.md#methods-to-reduce-repository-size)
so that deployed commits are not garbage collected, even if it's not referenced by the deployment refs.
+{{< /alert >}}
+
## Deployment rollback
When you roll back a deployment on a specific commit,
@@ -133,11 +139,14 @@ To retry or roll back a deployment:
- To retry a deployment, select **Re-deploy to environment**.
- To roll back to a deployment, next to a previously successful deployment, select **Rollback environment**.
-NOTE:
+{{< alert type="note" >}}
+
If you have [prevented outdated deployment jobs](deployment_safety.md#prevent-outdated-deployment-jobs) in your project,
the rollback buttons might be hidden or disabled.
In this case, see [job retries for rollback deployments](deployment_safety.md#job-retries-for-rollback-deployments).
+{{< /alert >}}
+
## Related topics
- [Environments](_index.md)
diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md
index 4820b2792fbe75f3ca73dfb5b24429846b556eea..5cf5c52e367ea551701c7d5eb9c9ffe53bf0c2d0 100644
--- a/doc/ci/environments/environments_dashboard.md
+++ b/doc/ci/environments/environments_dashboard.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Environments Dashboard
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Environments Dashboard provides a cross-project
environment-based view that lets you see the big picture
diff --git a/doc/ci/environments/external_deployment_tools.md b/doc/ci/environments/external_deployment_tools.md
index 64ddecf964e445a71db23df8d4070c9b366a9fca..ddc0825d9b84665229a0bb75f592a0d4f7ed81dd 100644
--- a/doc/ci/environments/external_deployment_tools.md
+++ b/doc/ci/environments/external_deployment_tools.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Track deployments of an external deployment tool
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
While GitLab offers a [built-in deployment solution](_index.md), you might prefer to use an external deployment tool, such as Heroku or ArgoCD.
GitLab can receive deployment events from these external tools and allows you to track the deployments within GitLab.
@@ -19,10 +22,13 @@ For example, the following features are available by setting up tracking:
- [View environments and deployments](_index.md#view-environments-and-deployments).
- [Track newly included merge requests per deployment](deployments.md#track-newly-included-merge-requests-per-deployment).
-NOTE:
+{{< alert type="note" >}}
+
Some of the features are not available because GitLab can't authorize and leverage those external deployments, including
[Protected Environments](protected_environments.md), [Deployment Approvals](deployment_approvals.md), [Deployment safety](deployment_safety.md), and [Deployment rollback](deployments.md#deployment-rollback).
+{{< /alert >}}
+
## How to set up deployment tracking
External deployment tools usually offer a [webhook](https://en.wikipedia.org/wiki/Webhook) to execute an additional API request when deployment state is changed.
@@ -32,9 +38,12 @@ You can configure your tool to make a request to the GitLab [Deployment API](../
- When a deployment succeeds, [update the deployment status to `success`](../../api/deployments.md#update-a-deployment).
- When a deployment fails, [update the deployment status to `failed`](../../api/deployments.md#update-a-deployment).
-NOTE:
+{{< alert type="note" >}}
+
You can create a [project access token](../../user/project/settings/project_access_tokens.md) for the GitLab API authentication.
+{{< /alert >}}
+
### Example: Track deployments of ArgoCD
You can use [ArgoCD webhook](https://argocd-notifications.readthedocs.io/en/stable/services/webhook/) to send deployment events to GitLab Deployment API.
@@ -82,7 +91,10 @@ Here is an example setup that creates a `success` deployment record in GitLab wh
kubectl patch app <your-app-name> -n argocd -p '{"metadata": {"annotations": {"notifications.argoproj.io/subscribe.on-deployed.gitlab":""}}}' --type merge
```
-NOTE:
+{{< alert type="note" >}}
+
If a deployment wasn't created as expected, you can troubleshoot with [`argocd-notifications` tool](https://argocd-notifications.readthedocs.io/en/stable/troubleshooting/).
For example, `argocd-notifications template notify gitlab-deployment-status <your-app-name> --recipient gitlab:argocd-notifications`
triggers API request immediately and renders an error message from GitLab API server if any.
+
+{{< /alert >}}
diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md
index 479dd6a229ba8455839d8a82d6d0d7621c43b160..09641d6dab751570c51b7b2997091ae56fc117fe 100644
--- a/doc/ci/environments/incremental_rollouts.md
+++ b/doc/ci/environments/incremental_rollouts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Incremental rollouts with GitLab CI/CD
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When rolling out changes to your application, it is possible to release production changes
to only a portion of your Kubernetes pods as a risk mitigation strategy. By releasing
@@ -65,7 +68,7 @@ rollout 10%:
ROLLOUT_PERCENTAGE: 10
```
-After the jobs are built, select **Run** (**{play}**) next to the job's name
+After the jobs are built, select **Run** ({{< icon name="play" >}}) next to the job's name
to release each stage of pods. You can also rollback by running a lower percentage job. Once 100%
is reached, you cannot roll back using this method. To roll back a deployment, see [retry or roll back a deployment](../environments/deployments.md#retry-or-roll-back-a-deployment).
@@ -112,10 +115,13 @@ available, [demonstrating configuration of timed rollouts](https://gitlab.com/gl
## Blue-Green Deployment
-NOTE:
+{{< alert type="note" >}}
+
Teams can leverage an Ingress annotation and [set traffic weight](../../user/project/canary_deployments.md#how-to-change-the-traffic-weight-on-a-canary-ingress-deprecated)
as an alternative approach to the blue-green deployment strategy documented here.
+{{< /alert >}}
+
Also sometimes known as A/B deployment or red-black deployment, this technique is used to reduce
downtime and risk during a deployment. When combined with incremental rollouts, you can
minimize the impact of a deployment causing an issue.
diff --git a/doc/ci/environments/kubernetes_dashboard.md b/doc/ci/environments/kubernetes_dashboard.md
index 4304318ca677e455637c5c871fb6fa16cac49fe5..a0993dcf96ffe2e497c916ac75f6a4cb91e074b6 100644
--- a/doc/ci/environments/kubernetes_dashboard.md
+++ b/doc/ci/environments/kubernetes_dashboard.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dashboard for Kubernetes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [beta](../../policy/development_stages_support.md#beta).
-> - Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2.
-> - Feature flags `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125835) in GitLab 16.2.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431746) to the environment details page in 16.10.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [beta](../../policy/development_stages_support.md#beta).
+- Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2.
+- Feature flags `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125835) in GitLab 16.2.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431746) to the environment details page in 16.10.
+
+{{< /history >}}
Use the dashboard for Kubernetes to understand the status of your clusters with an intuitive visual interface.
The dashboard works with every connected Kubernetes cluster, whether you deployed them
@@ -23,10 +30,14 @@ with CI/CD or GitOps.
## Configure a dashboard
-> - Filtering resources by namespace [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403618) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `kubernetes_namespace_for_environment`. Disabled by default.
-> - Filtering resources by namespace [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127043) in GitLab 16.3. Feature flag `kubernetes_namespace_for_environment` removed.
-> - Selecting the related Flux resource [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128857) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `flux_resource_for_environment`.
-> - Selecting the related Flux resource [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130648) in GitLab 16.4. Feature flag `flux_resource_for_environment` removed.
+{{< history >}}
+
+- Filtering resources by namespace [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403618) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `kubernetes_namespace_for_environment`. Disabled by default.
+- Filtering resources by namespace [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127043) in GitLab 16.3. Feature flag `kubernetes_namespace_for_environment` removed.
+- Selecting the related Flux resource [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128857) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `flux_resource_for_environment`.
+- Selecting the related Flux resource [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130648) in GitLab 16.4. Feature flag `flux_resource_for_environment` removed.
+
+{{< /history >}}
Configure a dashboard to use it for a given environment.
You can configure dashboard for an environment that already exists, or
@@ -36,9 +47,9 @@ Prerequisites:
- A GitLab agent for Kubernetes is [installed](../../user/clusters/agent/install/_index.md) and [`user_access`](../../user/clusters/agent/user_access.md) is configured for the environment's project or its parent group.
-::Tabs
+{{< tabs >}}
-:::TabTitle The environment already exists
+{{< tab title="The environment already exists" >}}
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Operate > Environments**.
@@ -49,7 +60,9 @@ Prerequisites:
1. Optional. From the **Flux resource** dropdown list, select a Flux resource.
1. Select **Save**.
-:::TabTitle The environment doesn't exist
+{{< /tab >}}
+
+{{< tab title="The environment doesn't exist" >}}
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Operate > Environments**.
@@ -60,11 +73,17 @@ Prerequisites:
1. Optional. From the **Flux resource** dropdown list, select a Flux resource.
1. Select **Save**.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure a dashboard for a dynamic environment
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467912) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467912) in GitLab 17.6.
+
+{{< /history >}}
To configure a dashboard for a dynamic environment:
@@ -87,9 +106,13 @@ For more information, see the [CI/CD YAML syntax reference](../yaml/_index.md#en
## View a dashboard
-> - Kubernetes watch API integration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422945) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `k8s_watch_api`. Disabled by default.
-> - Kubernetes watch API integration [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136831) in GitLab 16.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427762) in GitLab 17.1. Feature flag `k8s_watch_api` removed.
+{{< history >}}
+
+- Kubernetes watch API integration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422945) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `k8s_watch_api`. Disabled by default.
+- Kubernetes watch API integration [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136831) in GitLab 16.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427762) in GitLab 17.1. Feature flag `k8s_watch_api` removed.
+
+{{< /history >}}
View a dashboard to see the status of connected clusters.
If the `k8s_watch_api` feature flag is enabled, the status of your
@@ -106,9 +129,13 @@ A list of pods is displayed. Select a pod to view its details.
### Flux sync status
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391581) in GitLab 16.3.
-> - Customizing the name of the Flux resource [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128857) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `flux_resource_for_environment`.
-> - Customizing the name of the Flux resource [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130648) in GitLab 16.4. Feature flag `flux_resource_for_environment` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391581) in GitLab 16.3.
+- Customizing the name of the Flux resource [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128857) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `flux_resource_for_environment`.
+- Customizing the name of the Flux resource [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130648) in GitLab 16.4. Feature flag `flux_resource_for_environment` removed.
+
+{{< /history >}}
You can review the sync status of your Flux deployments from a dashboard.
To display the deployment status, your dashboard must be able to retrieve the `Kustomization` and `HelmRelease` resources,
@@ -129,31 +156,43 @@ A dashboard displays one of the following status badges:
### Trigger Flux reconciliation
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434248) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434248) in GitLab 17.3.
+
+{{< /history >}}
You can manually reconcile your deployment with its Flux resources.
To trigger a reconciliation:
1. On a dashboard, select the sync status badge of a Flux deployment.
-1. Select **Actions** (**{ellipsis_v}**) **> Trigger reconciliation** (**{retry}**).
+1. Select **Actions** ({{< icon name="ellipsis_v" >}}) **> Trigger reconciliation** ({{< icon name="retry" >}}).
### Suspend or resume Flux reconciliation
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/478380) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/478380) in GitLab 17.5.
+
+{{< /history >}}
You can manually suspend or resume your Flux reconciliation from the UI.
To suspend or resume reconciliation:
1. On a dashboard, select the sync status badge of a Flux deployment.
-1. Select **Actions** (**{ellipsis_v}**), then choose one of the following:
- - **Suspend reconciliation** (**{stop}**) to pause the Flux reconciliation.
- - **Resume reconciliation** (**{play}**) to restart the Flux reconciliation.
+1. Select **Actions** ({{< icon name="ellipsis_v" >}}), then choose one of the following:
+ - **Suspend reconciliation** ({{< icon name="stop" >}}) to pause the Flux reconciliation.
+ - **Resume reconciliation** ({{< icon name="play" >}}) to restart the Flux reconciliation.
### View pod logs
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13793) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13793) in GitLab 17.2.
+
+{{< /history >}}
View pod logs when you want to quickly understand and troubleshoot issues across your environments from a configured dashboard. You can view logs for each container in a pod.
@@ -163,27 +202,38 @@ You can also view pod logs from the pod details.
### Delete a pod
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467653) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467653) in GitLab 17.3.
+
+{{< /history >}}
To restart a failed pod, delete it from the Kubernetes dashboard.
To delete a pod:
1. On the **Kubernetes overview** tab, find the pod you want to delete.
-1. Select **Actions** (**{ellipsis_v}**) **> Delete pod** (**{remove}**).
+1. Select **Actions** ({{< icon name="ellipsis_v" >}}) **> Delete pod** ({{< icon name="remove" >}}).
You can also delete a pod from the pod details.
## Detailed dashboard
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11351) in GitLab 16.4, [with a flag](../../administration/feature_flags.md) named `k8s_dashboard`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/424237) in GitLab 16.7 for a subset of users.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11351) in GitLab 16.4, [with a flag](../../administration/feature_flags.md) named `k8s_dashboard`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/424237) in GitLab 16.7 for a subset of users.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
The detailed dashboard provides information about the following Kubernetes resources:
- Pods
diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md
index c9d49498d3b8145200cfbb70241f2eafac3949cd..6e847be8a1e64249bb0b9450b47e47ec06ed304a 100644
--- a/doc/ci/environments/protected_environments.md
+++ b/doc/ci/environments/protected_environments.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Protected environments
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Environments](_index.md) can be used for both testing and
production reasons.
@@ -19,9 +22,12 @@ unauthorized users.
By default, a protected environment ensures that only people with the
appropriate privileges can deploy to it, keeping the environment safe.
-NOTE:
+{{< alert type="note" >}}
+
GitLab administrators can use all environments, including protected environments.
+{{< /alert >}}
+
To protect, update, or unprotect an environment, you need to have at least the
Maintainer role.
@@ -213,8 +219,12 @@ and are protected at the same time.
### Configure group-level memberships
-> - Operators are required to have Owner+ role from the original Maintainer+ role and this role change is introduced from GitLab 15.3 [with a flag](https://gitlab.com/gitlab-org/gitlab/-/issues/369873) named `group_level_protected_environment_settings_permission`. Enabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/369873) in GitLab 15.4.
+{{< history >}}
+
+- Operators are required to have Owner+ role from the original Maintainer+ role and this role change is introduced from GitLab 15.3 [with a flag](https://gitlab.com/gitlab-org/gitlab/-/issues/369873) named `group_level_protected_environment_settings_permission`. Enabled by default.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/369873) in GitLab 15.4.
+
+{{< /history >}}
To maximize the effectiveness of group-level protected environments,
[group-level memberships](../../user/group/_index.md) must be correctly
@@ -260,7 +270,11 @@ To protect a group-level environment, make sure your environments have the corre
#### Using the UI
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325249) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325249) in GitLab 15.1.
+
+{{< /history >}}
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Settings > CI/CD**.
diff --git a/doc/ci/examples/_index.md b/doc/ci/examples/_index.md
index 637c87bf6476018989a21200355537da0a3f72b5..c302b1323f0e8f699fbe2215a8dabdbcea2381bf 100644
--- a/doc/ci/examples/_index.md
+++ b/doc/ci/examples/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab CI/CD examples
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page contains links to a variety of examples that can help you understand how to
implement [GitLab CI/CD](../_index.md) for your specific use case.
@@ -101,9 +104,12 @@ to [the templates list](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/g
### Adding templates to your GitLab installation
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can add custom examples and templates to your instance.
Your GitLab administrator can [designate an instance template repository](../../administration/settings/instance_template_repository.md)
diff --git a/doc/ci/examples/deployment/_index.md b/doc/ci/examples/deployment/_index.md
index b2d401c926fa4406a45cd20e4a1ef274b9d368a2..3d438ee6a8551cef2ce8061b0168c2d5a26ee262 100644
--- a/doc/ci/examples/deployment/_index.md
+++ b/doc/ci/examples/deployment/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using Dpl as a deployment tool
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Dpl](https://github.com/travis-ci/dpl) (pronounced like the letters D-P-L) is a deploy tool made for
continuous deployment that's developed and used by Travis CI, but can also be
diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md
index f7ce61f42134aaf588c2c5172c91bddc3dfebe1d..71275c60ffc2b8307bb8e39dbf15f9889b6e7225 100644
--- a/doc/ci/examples/deployment/composer-npm-deploy.md
+++ b/doc/ci/examples/deployment/composer-npm-deploy.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Running Composer and npm scripts with deployment via SCP in GitLab CI/CD
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This guide covers the building of dependencies of a PHP project while compiling assets via an npm script using [GitLab CI/CD](../../_index.md).
diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/_index.md b/doc/ci/examples/end_to_end_testing_webdriverio/_index.md
index 7bb831f23c3c547434ad0dca45b186d33b954316..54d3ca613f33a43430340f08fd74a43217f9e393 100644
--- a/doc/ci/examples/end_to_end_testing_webdriverio/_index.md
+++ b/doc/ci/examples/end_to_end_testing_webdriverio/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../_index.md'
-remove_date: '2025-04-27'
+redirect_to: ../_index.md
+remove_date: "2025-04-27"
---
<!-- markdownlint-disable -->
diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/_index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/_index.md
index 7bb831f23c3c547434ad0dca45b186d33b954316..54d3ca613f33a43430340f08fd74a43217f9e393 100644
--- a/doc/ci/examples/laravel_with_gitlab_and_envoy/_index.md
+++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../_index.md'
-remove_date: '2025-04-27'
+redirect_to: ../_index.md
+remove_date: "2025-04-27"
---
<!-- markdownlint-disable -->
diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md
index a4d486f32acb13a5399fa4ca15d75443bb92b6ba..62a8dcc880a0b09ad3f4ad036ef2c2a4eca3abfe 100644
--- a/doc/ci/examples/php.md
+++ b/doc/ci/examples/php.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Testing PHP projects
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This guide covers basic building instructions for PHP projects.
diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md
index 6279d59476d68abdda20aec36674b26fffd61dce..5abd774a2979523036c877d16433f1c1972bf939 100644
--- a/doc/ci/examples/semantic-release.md
+++ b/doc/ci/examples/semantic-release.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Publish npm packages to the GitLab package registry using semantic-release
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This guide demonstrates how to automatically publish npm packages to the [GitLab package registry](../../user/packages/npm_registry/_index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release).
diff --git a/doc/ci/gitlab_google_cloud_integration/_index.md b/doc/ci/gitlab_google_cloud_integration/_index.md
index 90aa13595d7f71b72e7270be5f92819d322068b6..5a94d05b5f5d10b20ca9c5b34b3dae3a9edbbf6c 100644
--- a/doc/ci/gitlab_google_cloud_integration/_index.md
+++ b/doc/ci/gitlab_google_cloud_integration/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab and Google Cloud integration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Use the Google Cloud integration to use Google Cloud resources in GitLab projects.
diff --git a/doc/ci/interactive_web_terminal/_index.md b/doc/ci/interactive_web_terminal/_index.md
index 18f82b1b716f2218b30f829d8182746dec0e542e..1b58ceff46013356d5527ace68361909d91aff23 100644
--- a/doc/ci/interactive_web_terminal/_index.md
+++ b/doc/ci/interactive_web_terminal/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Interactive web terminals
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Interactive web terminals give the user access to a terminal in GitLab for
running one-off commands for their CI pipeline. You can think of it like a method for
@@ -16,13 +19,16 @@ shell access to the environment where [GitLab Runner](https://docs.gitlab.com/ru
is deployed, some [security precautions](../../administration/integration/terminal.md#security) were
taken to protect the users.
-NOTE:
+{{< alert type="note" >}}
+
[Instance runners on GitLab.com](../runners/_index.md) do not
provide an interactive web terminal. Follow
[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/24674) for progress on
adding support. For groups and projects hosted on GitLab.com, interactive web
terminals are available when using your own group or project runner.
+{{< /alert >}}
+
## Configuration
Two things need to be configured for the interactive web terminal to work:
@@ -47,20 +53,25 @@ Support for fixing these limitations is tracked in the following issues:
## Debugging a running job
-NOTE:
+{{< alert type="note" >}}
+
Not all executors are
[supported](https://docs.gitlab.com/runner/executors/#compatibility-chart).
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The `docker` executor does not keep running
after the build script is finished. At that point, the terminal automatically
disconnects and does not wait for the user to finish. Follow
[this issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3605) for updates on
improving this behavior.
+{{< /alert >}}
Sometimes, when a job is running, things don't go as you would expect, and it
would be helpful if one can have a shell to aid debugging. When a job is
-running, on the right panel, you can see a `debug` button (**{external-link}**) that opens the terminal
+running, on the right panel, you can see a `debug` button ({{< icon name="external-link" >}}) that opens the terminal
for the current job. Only the person who started a job can debug it.
diff --git a/doc/ci/jobs/_index.md b/doc/ci/jobs/_index.md
index 124f74c9c6455b04d69e92e0316e8a50b8738b27..ca1286fdf8c2ca7608fda457694d00c5b1c7ca65 100644
--- a/doc/ci/jobs/_index.md
+++ b/doc/ci/jobs/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI/CD Jobs
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
CI/CD jobs are the fundamental elements of a [GitLab CI/CD pipeline](../pipelines/_index.md).
Jobs are configured in the `.gitlab-ci.yml` file with a list of commands to execute
@@ -214,14 +217,24 @@ Selecting an individual job shows you its [job log](job_logs.md), and allows you
### View all jobs in a project
-DETAILS:
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
-> - Filtering jobs by job name [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387547) as an [experiment](../../policy/development_stages_support.md) on GitLab.com and GitLab Self-Managed in GitLab 17.3 [with flags](../../administration/feature_flags.md) named `populate_and_use_build_names_table` for the API and `fe_search_build_by_name` for the UI. Disabled by default.
+{{< history >}}
+
+- Filtering jobs by job name [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387547) as an [experiment](../../policy/development_stages_support.md) on GitLab.com and GitLab Self-Managed in GitLab 17.3 [with flags](../../administration/feature_flags.md) named `populate_and_use_build_names_table` for the API and `fe_search_build_by_name` for the UI. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
Filtering jobs by name is an [experiment](../../policy/development_stages_support.md). For more information about the development of this feature, see [issue 387547](https://gitlab.com/gitlab-org/gitlab/-/issues/387547).
To view the full list of jobs that ran in a project:
diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md
index 1e88273993d766df3221de40614a789bb0315bbe..3a3932294be7ee5e36a12dee28b85b5f1167252f 100644
--- a/doc/ci/jobs/ci_job_token.md
+++ b/doc/ci/jobs/ci_job_token.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab CI/CD job token
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When a CI/CD pipeline job is about to run, GitLab generates a unique token and makes it available
to the job as the [`CI_JOB_TOKEN` predefined variable](../variables/predefined_variables.md).
@@ -91,12 +94,16 @@ When the setting is enforced, the CI/CD job token is always restricted to the pr
### Add a group or project to the job token allowlist
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.9. [Deployed behind the `:inbound_ci_scoped_job_token` feature flag](../../user/feature_flags.md), enabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.10.
-> - **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
-> - Adding groups to the job token allowlist [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.0.
-> - **Token Access** section renamed to **Job token permissions**, and [**Limit access _to_ this project** setting renamed to **Authorized groups and projects**](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.2.
-> - **Add project** option [renamed to **Add**](https://gitlab.com/gitlab-org/gitlab/-/issues/470880/) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.9. [Deployed behind the `:inbound_ci_scoped_job_token` feature flag](../../user/feature_flags.md), enabled by default.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.10.
+- **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
+- Adding groups to the job token allowlist [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.0.
+- **Token Access** section renamed to **Job token permissions**, and [**Limit access _to_ this project** setting renamed to **Authorized groups and projects**](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.2.
+- **Add project** option [renamed to **Add**](https://gitlab.com/gitlab-org/gitlab/-/issues/470880/) in GitLab 17.6.
+
+{{< /history >}}
You can add groups or projects to your job token allowlist to allow access to your project's resources
with a job token for authentication. By default, the allowlist of any project only includes itself.
@@ -131,7 +138,11 @@ You can also add a group or project to the allowlist [with the API](../../api/gr
### Limit job token scope for public or internal projects
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/405369) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/405369) in GitLab 16.6.
+
+{{< /history >}}
Projects not in the allowlist can use a job token to authenticate with public or internal projects to:
@@ -158,14 +169,21 @@ To set a feature to be only visible to project members:
### Allow any project to access your project
-> - **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
-> - **Token Access** section renamed to **Job token permissions**, and [**Limit access _to_ this project** setting renamed to **Authorized groups and projects**](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.2.
+{{< history >}}
+
+- **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
+- **Token Access** section renamed to **Job token permissions**, and [**Limit access _to_ this project** setting renamed to **Authorized groups and projects**](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.2.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
It is a security risk to disable the token access limit and allowlist. A malicious user could try to compromise
a pipeline created in an unauthorized project. If the pipeline was created by one of
your maintainers, the job token could be used in an attempt to access your project.
+{{< /alert >}}
+
If you disable the **Limit access _to_ this project** setting, the allowlist is ignored.
Jobs from any project could access your project with a job token if the user that
triggers the pipeline has permission to access your project.
@@ -189,20 +207,30 @@ You can also enable and disable the setting with the [GraphQL](../../api/graphql
### Allow Git push requests to your project repository
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389060) in GitLab 17.2. [with a flag](../../administration/feature_flags.md) named `allow_push_repository_for_job_token`. Disabled by default.
-> - **Token Access** section renamed to **Job token permissions**, and [**Limit access _to_ this project** setting renamed to **Authorized groups and projects**](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389060) in GitLab 17.2. [with a flag](../../administration/feature_flags.md) named `allow_push_repository_for_job_token`. Disabled by default.
+- **Token Access** section renamed to **Job token permissions**, and [**Limit access _to_ this project** setting renamed to **Authorized groups and projects**](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.2.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
Pushing to the project repository by authenticating with a CI/CD job token is still in development
and not yet optimized for performance. If you enable this feature for testing, you must
thoroughly test and implement validation measures to prevent infinite loops of "push" pipelines
triggering more pipelines.
+{{< /alert >}}
+
You can allow Git push requests to your project repository that are authenticated
with a CI/CD job token. When enabled, access is allowed only for the tokens generated
in CI/CD jobs that run in pipelines in your project. This permission is disabled by default.
@@ -255,12 +283,15 @@ Additionally, there are multiple valid methods for passing the job token in the
## Limit your project's job token access (deprecated)
-NOTE:
+{{< alert type="note" >}}
+
The [**Limit access _from_ this project**](#configure-the-job-token-scope-deprecated)
setting is disabled by default for all new projects and is [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/383084)
in GitLab 17.0. Project maintainers or owners should configure the [**Limit access _to_ this project**](#add-a-group-or-project-to-the-job-token-allowlist)
setting instead.
+{{< /alert >}}
+
Control your project's job token scope by creating an allowlist of projects which
can be accessed by your project's job token.
@@ -276,8 +307,12 @@ to make an API request to project `B`, then `B` must be added to the allowlist f
### Configure the job token scope (deprecated)
-> - **Limit CI_JOB_TOKEN access** setting [renamed to **Limit access _from_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
-> - **Token Access** setting [renamed to **Job token permissions**](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.2.
+{{< history >}}
+
+- **Limit CI_JOB_TOKEN access** setting [renamed to **Limit access _from_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
+- **Token Access** setting [renamed to **Job token permissions**](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.2.
+
+{{< /history >}}
Prerequisites:
@@ -294,7 +329,11 @@ To configure the job token scope:
## Job token authentication log
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467292/) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467292/) in GitLab 17.6.
+
+{{< /history >}}
You can track which other projects use a CI/CD job token to authenticate with your project
in an authentication log. To check the log:
diff --git a/doc/ci/jobs/job_artifacts.md b/doc/ci/jobs/job_artifacts.md
index 85a51fad40bdafb6a2b23d6462cab44aadb2c371..1b0b544b45aaa0c8798db476c0a26c2374293248 100644
--- a/doc/ci/jobs/job_artifacts.md
+++ b/doc/ci/jobs/job_artifacts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Job artifacts
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Jobs can output an archive of files and directories. This output is known as a job artifact.
@@ -192,9 +195,13 @@ job:
## View all job artifacts in a project
-> - Interface improvements [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33418) in GitLab 15.6.
-> - Performance improvements [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387765) in GitLab 15.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/407475) in GitLab 16.0. Feature flag `artifacts_management_page` removed.
+{{< history >}}
+
+- Interface improvements [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33418) in GitLab 15.6.
+- Performance improvements [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387765) in GitLab 15.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/407475) in GitLab 16.0. Feature flag `artifacts_management_page` removed.
+
+{{< /history >}}
You can view all artifacts stored in a project from the **Build > Artifacts** page.
This list displays all jobs and their associated artifacts. Expand an entry to access
@@ -210,13 +217,13 @@ You can download or delete individual artifacts from this list.
You can download job artifacts from:
-- Any **Pipelines** list. On the right of the pipeline, select **Download artifacts** (**{download}**).
-- Any **Jobs** list. On the right of the job, select **Download artifacts** (**{download}**).
+- Any **Pipelines** list. On the right of the pipeline, select **Download artifacts** ({{< icon name="download" >}}).
+- Any **Jobs** list. On the right of the job, select **Download artifacts** ({{< icon name="download" >}}).
- A job's detail page. On the right of the page, select **Download**.
-- A merge request **Overview** page. On the right of the latest pipeline, select **Artifacts** (**{download}**).
-- The [**Artifacts**](#view-all-job-artifacts-in-a-project) page. On the right of the job, select **Download** (**{download}**).
+- A merge request **Overview** page. On the right of the latest pipeline, select **Artifacts** ({{< icon name="download" >}}).
+- The [**Artifacts**](#view-all-job-artifacts-in-a-project) page. On the right of the job, select **Download** ({{< icon name="download" >}}).
- The [artifacts browser](#browse-the-contents-of-the-artifacts-archive). On the top of the page,
- select **Download artifacts archive** (**{download}**).
+ select **Download artifacts archive** ({{< icon name="download" >}}).
[Report artifacts](../yaml/artifacts_reports.md) can only be downloaded from the **Pipelines** list
or **Artifacts** page.
@@ -255,9 +262,12 @@ child pipelines have a job with the same name, the job artifacts from the parent
### With a CI/CD job token
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use a [CI/CD job token](ci_job_token.md) to authenticate with the [jobs artifacts API endpoint](../../api/job_artifacts.md)
and fetch artifacts from a different pipeline. You must specify which job to retrieve artifacts from,
@@ -277,9 +287,9 @@ build_submodule:
You can browse the contents of the artifacts from the UI without downloading the artifact locally,
from:
-- Any **Jobs** list. On the right of the job, select **Browse** (**{folder-open}**).
+- Any **Jobs** list. On the right of the job, select **Browse** ({{< icon name="folder-open" >}}).
- A job's detail page. On the right of the page, select **Browse**.
-- The **Artifacts** page. On the right of the job, select **Browse** (**{folder-open}**).
+- The **Artifacts** page. On the right of the job, select **Browse** ({{< icon name="folder-open" >}}).
If [GitLab Pages](../../administration/pages/_index.md) is enabled globally, even if it is disabled in the project settings,
you can preview some artifacts file extensions directly in your browser. If the project is internal or private,
@@ -289,11 +299,11 @@ The following extensions are supported:
| File extension | GitLab.com | Linux package with built-in NGINX |
|----------------|------------------------|-----------------------------------|
-| `.html` | **{check-circle}** Yes | **{check-circle}** Yes |
-| `.json` | **{check-circle}** Yes | **{check-circle}** Yes |
-| `.xml` | **{check-circle}** Yes | **{check-circle}** Yes |
-| `.txt` | **{dotted-circle}** No | **{check-circle}** Yes |
-| `.log` | **{dotted-circle}** No | **{check-circle}** Yes |
+| `.html` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| `.json` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| `.xml` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| `.txt` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| `.log` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
### From a URL
@@ -310,11 +320,14 @@ Replace `<full-project-path>` with a valid project path, you can find it in the
## Delete job log and artifacts
-WARNING:
+{{< alert type="warning" >}}
+
Deleting the job log and artifacts is a destructive action that cannot be reverted. Use with caution.
Deleting certain files, including report artifacts, job logs, and metadata files, affects
GitLab features that use these files as data sources.
+{{< /alert >}}
+
You can delete a job's artifacts and log.
Prerequisites:
@@ -324,14 +337,18 @@ Prerequisites:
To delete a job:
1. Go to a job's detail page.
-1. In the upper-right corner of the job's log, select **Erase job log and artifacts** (**{remove}**).
+1. In the upper-right corner of the job's log, select **Erase job log and artifacts** ({{< icon name="remove" >}}).
You can also delete individual artifacts from the [**Artifacts** page](#bulk-delete-artifacts).
### Bulk delete artifacts
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33348) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `ci_job_artifact_bulk_destroy`. Disabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/398581) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33348) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `ci_job_artifact_bulk_destroy`. Disabled by default.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/398581) in GitLab 16.1.
+
+{{< /history >}}
You can delete multiple artifacts at the same time:
@@ -360,7 +377,11 @@ With this configuration, GitLab adds **artifact 1** as a link to `file.txt` to t
## Keep artifacts from most recent successful jobs
-> - Artifacts for [blocked](https://gitlab.com/gitlab-org/gitlab/-/issues/387087) or [failed](https://gitlab.com/gitlab-org/gitlab/-/issues/266958) pipelines changed to no longer be kept indefinitely in GitLab 16.7.
+{{< history >}}
+
+- Artifacts for [blocked](https://gitlab.com/gitlab-org/gitlab/-/issues/387087) or [failed](https://gitlab.com/gitlab-org/gitlab/-/issues/266958) pipelines changed to no longer be kept indefinitely in GitLab 16.7.
+
+{{< /history >}}
By default artifacts are always kept for successful pipelines for the most recent commit on each ref.
Any [`expire_in`](#with-an-expiry) configuration does not apply to the most recent artifacts.
diff --git a/doc/ci/jobs/job_artifacts_troubleshooting.md b/doc/ci/jobs/job_artifacts_troubleshooting.md
index 15a7551b6222c3d8b399a922691a3516bcce32a2..595ea18263f734ecf4dedc60fbe0e30b4dba4a38 100644
--- a/doc/ci/jobs/job_artifacts_troubleshooting.md
+++ b/doc/ci/jobs/job_artifacts_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting job artifacts
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with [job artifacts](job_artifacts.md), you might encounter the following issues.
@@ -41,7 +44,11 @@ wasn't created.
## Error message `Missing /usr/bin/gitlab-runner-helper. Uploading artifacts is disabled.`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3068) in GitLab 15.2, GitLab Runner uses `RUNNER_DEBUG` instead of `DEBUG`, fixing this issue.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3068) in GitLab 15.2, GitLab Runner uses `RUNNER_DEBUG` instead of `DEBUG`, fixing this issue.
+
+{{< /history >}}
In GitLab 15.1 and earlier, setting a CI/CD variable named `DEBUG` can cause artifact uploads to fail.
diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md
index d7b40476d39d5457267060c90330bf0729ca5bdf..067cfea1a5c71ac2751f4c86273e4b455bc9a70e 100644
--- a/doc/ci/jobs/job_control.md
+++ b/doc/ci/jobs/job_control.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Control how jobs run
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Before a new pipeline starts, GitLab checks the pipeline configuration to determine
which jobs can run in that pipeline. You can configure jobs to run depending on
@@ -56,7 +59,7 @@ To run a manual job, you must have permission to merge to the assigned branch:
1. Go to the pipeline, job, [environment](../environments/deployments.md#configure-manual-deployments),
or deployment view.
-1. Next to the manual job, select **Run** (**{play}**).
+1. Next to the manual job, select **Run** ({{< icon name="play" >}}).
### Specify variables when running manual jobs
@@ -64,7 +67,7 @@ When running manual jobs you can supply additional job specific variables.
You can do this from the job page of the manual job you want to run with
additional variables. To access this page, select the **name** of the manual job in
-the pipeline view, *not* **Run** (**{play}**).
+the pipeline view, *not* **Run** ({{< icon name="play" >}}).
Define CI/CD variables here when you want to alter the execution of a job that uses
[CI/CD variables](../variables/_index.md).
@@ -86,9 +89,12 @@ Users are prompted to confirm the action before the manual job runs, which provi
### Protect manual jobs
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use [protected environments](../environments/protected_environments.md)
to define a list of users authorized to run a manual job. You can authorize only
@@ -157,10 +163,10 @@ timed rollout 10%:
environment: production
```
-To stop the active timer of a delayed job, select **Unschedule** (**{time-out}**).
+To stop the active timer of a delayed job, select **Unschedule** ({{< icon name="time-out" >}}).
This job can no longer be scheduled to run automatically. You can, however, execute the job manually.
-To start a delayed job manually, select **Unschedule** (**{time-out}**) to stop the delay timer and then select **Run** (**{play}**).
+To start a delayed job manually, select **Unschedule** ({{< icon name="time-out" >}}) to stop the delay timer and then select **Run** ({{< icon name="play" >}}).
Soon GitLab Runner starts the job.
## Parallelize large jobs
@@ -191,9 +197,12 @@ test:
You can then go to the **Jobs** tab of a new pipeline build and see your RSpec
job split into three separate jobs.
-WARNING:
+{{< alert type="warning" >}}
+
Test Boosters reports usage statistics to the author.
+{{< /alert >}}
+
### Run a one-dimensional matrix of parallel jobs
To run a job multiple times in parallel in a single pipeline, but with different variable values for each instance of the job,
@@ -298,7 +307,11 @@ Quotes around the `dependencies` entry are required.
## Specify a parallelized job using needs with multiple parallelized jobs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254821) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254821) in GitLab 16.3.
+
+{{< /history >}}
You can use variables defined in [`needs:parallel:matrix`](../yaml/_index.md#needsparallelmatrix) with multiple parallelized jobs.
diff --git a/doc/ci/jobs/job_logs.md b/doc/ci/jobs/job_logs.md
index 7cb7481b2564d36966f9d6c5ddea4516e705917b..4afaa3665d8c1574352d32c137c7d965bd935613 100644
--- a/doc/ci/jobs/job_logs.md
+++ b/doc/ci/jobs/job_logs.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI/CD job logs
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A job log displays the full execution history of a [CI/CD job](_index.md).
@@ -24,7 +27,11 @@ To view detailed information about the job and its log output, scroll through th
## View job logs in full screen mode
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363617) in GitLab 16.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363617) in GitLab 16.7.
+
+{{< /history >}}
You can view the contents of a job log in full screen mode by clicking **Show full screen**.
@@ -32,7 +39,11 @@ To use full screen mode, your web browser must also support it. If your web brow
## Expand and collapse job log sections
-> - Support for output of multi-line command bash shell output [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3486) in GitLab 16.5 behind the [GitLab Runner feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html), `FF_SCRIPT_SECTIONS`.
+{{< history >}}
+
+- Support for output of multi-line command bash shell output [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3486) in GitLab 16.5 behind the [GitLab Runner feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html), `FF_SCRIPT_SECTIONS`.
+
+{{< /history >}}
Job logs are divided into sections that can be collapsed or expanded. Each section displays
the duration.
@@ -75,7 +86,7 @@ In the example above:
of letters, numbers, and the `_`, `.`, or `-` characters.
- `\r\e[0K`: Escape sequence that prevents the section markers from displaying in the
rendered (colored) job log. They are displayed when viewing the raw job log, accessed
- in the upper-right corner of the job log by selecting **Show complete raw** (**{doc-text}**).
+ in the upper-right corner of the job log by selecting **Show complete raw** ({{< icon name="doc-text" >}}).
- `\r`: carriage return (returns the cursor to the start of the line).
- `\e[0K`: ANSI escape code to clear the line from the cursor position to the end of the line.
(`\e[K` alone does not work; the `0` must be included).
@@ -161,12 +172,19 @@ For more details, see [Delete job logs](../../user/storage_management_automation
## Job log timestamps
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/455582) in GitLab 17.1 [with a flag](../../administration/feature_flags.md) named `parse_ci_job_timestamps`. Disabled by default.
+- Feature flag `parse_ci_job_timestamps` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/464785) in GitLab 17.2.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/455582) in GitLab 17.1 [with a flag](../../administration/feature_flags.md) named `parse_ci_job_timestamps`. Disabled by default.
-> - Feature flag `parse_ci_job_timestamps` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/464785) in GitLab 17.2.
+{{< /history >}}
You can generate a timestamp in the [ISO 8601 format](https://www.iso.org/iso-8601-date-and-time-format.html)
for each line in a CI/CD job log. With job log timestamps, you can identify the duration
diff --git a/doc/ci/jobs/job_rules.md b/doc/ci/jobs/job_rules.md
index eafb89a2b35048a445ded04c83fb8c81988b8970..01625ebfa337e0553cecc231763d1e89fa18d212 100644
--- a/doc/ci/jobs/job_rules.md
+++ b/doc/ci/jobs/job_rules.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Specify when jobs run with `rules`
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use [`rules`](../yaml/_index.md#rules) to include or exclude jobs in pipelines.
@@ -65,13 +68,16 @@ job:
- If the pipeline is a scheduled pipeline, the job is **not** added to the pipeline.
- In **all other cases**, the job is added to the pipeline, with `when: on_success`.
-WARNING:
+{{< alert type="warning" >}}
+
If you use a `when` clause as the final rule (not including `when: never`), two
simultaneous pipelines may start. Both push pipelines and merge request pipelines can
be triggered by the same event (a push to the source branch for an open merge request).
See how to [prevent duplicate pipelines](#avoid-duplicate-pipelines)
for more details.
+{{< /alert >}}
+
### Run jobs for scheduled pipelines
You can configure a job to be executed only when the pipeline has been
@@ -440,8 +446,12 @@ Additionally:
### Store a regular expression in a variable
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35438) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `ci_fix_rules_if_comparison_with_regexp_variable`, disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/359740) and feature flag `ci_fix_rules_if_comparison_with_regexp_variable` removed in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35438) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `ci_fix_rules_if_comparison_with_regexp_variable`, disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/359740) and feature flag `ci_fix_rules_if_comparison_with_regexp_variable` removed in GitLab 15.1.
+
+{{< /history >}}
Variables on the right side of `=~` and `!~` expressions are evaluated as regular expressions.
The regular expression must be enclosed in forward slashes (`/`). For example:
diff --git a/doc/ci/jobs/job_troubleshooting.md b/doc/ci/jobs/job_troubleshooting.md
index be2f36532a0f8c34b68c68715e4d4c6d3f84537e..ac57fff8f880a8e6bf8b8c3cb7778df119410f1b 100644
--- a/doc/ci/jobs/job_troubleshooting.md
+++ b/doc/ci/jobs/job_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting jobs
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with jobs, you might encounter the following issues.
@@ -166,9 +169,12 @@ The configuration can be added to:
## Job using `resource_group` gets stuck
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If a job using [`resource_group`](../yaml/_index.md#resource_group) gets stuck, a
GitLab administrator can try run the following commands from the [rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session):
diff --git a/doc/ci/jobs/mobile_devops.md b/doc/ci/jobs/mobile_devops.md
index 6e0d6b8b9e59de52dc0f52ab420e469542308eca..b15bc0d7c0f6bc1caf7fa3ead28a9f149bb34930 100644
--- a/doc/ci/jobs/mobile_devops.md
+++ b/doc/ci/jobs/mobile_devops.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../mobile_devops/_index.md'
-remove_date: '2025-04-24'
+redirect_to: ../mobile_devops/_index.md
+remove_date: "2025-04-24"
---
<!-- markdownlint-disable -->
diff --git a/doc/ci/jobs/ssh_keys.md b/doc/ci/jobs/ssh_keys.md
index c0474bf267ec4f94d78a215580c5c50c961e2286..89ba90c509c57ffa14f5f9ca3a9de9c40b3eeca6 100644
--- a/doc/ci/jobs/ssh_keys.md
+++ b/doc/ci/jobs/ssh_keys.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using SSH keys with GitLab CI/CD
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab does not have built-in support for managing SSH keys in a build
environment (where the GitLab Runner runs).
@@ -174,13 +177,16 @@ at the end of the last line of the SSH key before saving your changes.
If you must connect to multiple servers, all the server host keys
must be collected in the **Value** of the variable, one key per line.
-NOTE:
+{{< alert type="note" >}}
+
By using a file type CI/CD variable instead of `ssh-keyscan` directly inside
`.gitlab-ci.yml`, it has the benefit that you don't have to change `.gitlab-ci.yml`
if the host domain name changes for some reason. Also, the values are predefined
by you, meaning that if the host keys suddenly change, the CI/CD job doesn't fail,
so there's something wrong with the server or the network.
+{{< /alert >}}
+
Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the
[content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor)
above, you must add:
diff --git a/doc/ci/migration/bamboo.md b/doc/ci/migration/bamboo.md
index 841a884e087dc31d396469c2af540a73421fae0e..99e87a5603bec02b9f69523fac0efbde4a82fcad 100644
--- a/doc/ci/migration/bamboo.md
+++ b/doc/ci/migration/bamboo.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from Bamboo
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This migration guide looks at how you can migrate from Atlassian Bamboo to GitLab CI/CD.
The focus is on [Bamboo Specs YAML](https://docs.atlassian.com/bamboo-specs-docs/8.1.12/specs.html?yaml)
diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md
index 822f3e5e4d74ee99830d8955a36f2d1ee6c4b618..2e1f914bd467bdac12f1c93271769e4fb79c5b77 100644
--- a/doc/ci/migration/circleci.md
+++ b/doc/ci/migration/circleci.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from CircleCI
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you are currently using CircleCI, you can migrate your CI/CD pipelines to [GitLab CI/CD](../_index.md),
and start making use of all its powerful features.
diff --git a/doc/ci/migration/examples/jenkins-maven.md b/doc/ci/migration/examples/jenkins-maven.md
index 0c4cba8e23c6e547e20aede67e7725d38c37a24a..b484be70eb092c7a80454efbd83bfa854bc43a38 100644
--- a/doc/ci/migration/examples/jenkins-maven.md
+++ b/doc/ci/migration/examples/jenkins-maven.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrate a Maven build from Jenkins to GitLab CI/CD
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you have a Maven build in Jenkins, you can use a [Java Spring](https://gitlab.com/gitlab-org/project-templates/spring)
project template to migrate to GitLab. The template uses Maven for its underlying dependency management.
diff --git a/doc/ci/migration/github_actions.md b/doc/ci/migration/github_actions.md
index 2ba26d07ce87c5673025b8ef01914af973319171..d12d491d8d70fe53e9adcddb1084bed76beb5226 100644
--- a/doc/ci/migration/github_actions.md
+++ b/doc/ci/migration/github_actions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from GitHub Actions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you're migrating from GitHub Actions to GitLab CI/CD, you are able to create CI/CD
pipelines that replicate and enhance your GitHub Action workflows.
diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md
index 835b5b32d87740d8a3f1b5e50c98e3f0d4a3e488..c92921324c965105bf17c6bd01d6cc4d4ab425ae 100644
--- a/doc/ci/migration/jenkins.md
+++ b/doc/ci/migration/jenkins.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from Jenkins
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you're migrating from Jenkins to GitLab CI/CD, you are able to create CI/CD
pipelines that replicate and enhance your Jenkins workflows.
@@ -731,8 +734,11 @@ Before doing any migration work, you should first:
- You can use the [JenkinsFile Wrapper](https://gitlab.com/gitlab-org/jfr-container-builder/)
to run a complete Jenkins instance inside of a GitLab CI/CD job, including plugins. Use this tool to help ease the transition to GitLab CI/CD, by delaying the migration of less urgent pipelines.
- NOTE:
- The JenkinsFile Wrapper is not packaged with GitLab and falls outside of the scope of support.
+ {{< alert type="note" >}}
+
+The JenkinsFile Wrapper is not packaged with GitLab and falls outside of the scope of support.
For more information, see the [Statement of Support](https://about.gitlab.com/support/statement-of-support/).
+ {{< /alert >}}
+
If you have questions that are not answered here, the [GitLab community forum](https://forum.gitlab.com/) can be a great resource.
diff --git a/doc/ci/migration/plan_a_migration.md b/doc/ci/migration/plan_a_migration.md
index 968bd37d38aa5430a02a547267da4b3d3b927a6d..18ad735966c776d1598e3945b9751b115f277617 100644
--- a/doc/ci/migration/plan_a_migration.md
+++ b/doc/ci/migration/plan_a_migration.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Plan a migration from another tool to GitLab CI/CD
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Before starting a migration from another tool to GitLab CI/CD, you should begin by
developing a migration plan.
diff --git a/doc/ci/migration/teamcity.md b/doc/ci/migration/teamcity.md
index 15b3b019f09fbe0aa33a3c15027f1d8bf3438885..4e26b2efb0efc2d0ae523abc7319dda7c5b72c42 100644
--- a/doc/ci/migration/teamcity.md
+++ b/doc/ci/migration/teamcity.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from TeamCity
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you're migrating from TeamCity to GitLab CI/CD, you can create CI/CD
pipelines that replicate and enhance your TeamCity workflows.
diff --git a/doc/ci/mobile_devops/_index.md b/doc/ci/mobile_devops/_index.md
index 5512caf3fbd63cce082e91fdf610a2736334af61..7b3f7517f58fbdeb4549604be4c70b5f9b309afc 100644
--- a/doc/ci/mobile_devops/_index.md
+++ b/doc/ci/mobile_devops/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Mobile DevOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Build, sign, and release native and cross-platform mobile apps for Android and iOS by using GitLab CI/CD.
GitLab Mobile DevOps provides tools and best practices to automate your mobile app development workflow.
diff --git a/doc/ci/pipeline_editor/_index.md b/doc/ci/pipeline_editor/_index.md
index e0725250e97deaa91046ca72613b5c68f3e577dd..192c6ec3c9fca0fa39d4bd25682d8e60330f60b9 100644
--- a/doc/ci/pipeline_editor/_index.md
+++ b/doc/ci/pipeline_editor/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pipeline editor
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The pipeline editor is the primary place to edit the GitLab CI/CD configuration in
the `.gitlab-ci.yml` file in the root of your repository. To access the editor, go to **Build > Pipeline editor**.
@@ -34,10 +37,13 @@ this section displays a tip to help you fix the problem:
## Lint CI configuration
-NOTE:
+{{< alert type="note" >}}
+
The **Lint** tab is replaced with the **Validate** tab in GitLab 15.3. The lint results are included
in a successful [pipeline simulation](#simulate-a-cicd-pipeline).
+{{< /alert >}}
+
To test the validity of your GitLab CI/CD configuration before committing the changes,
you can use the CI lint tool:
@@ -53,7 +59,11 @@ reflected in the CI lint. It displays the same results as the existing [CI Lint
## Simulate a CI/CD pipeline
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337282) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337282) in GitLab 15.3.
+
+{{< /history >}}
To look for pipeline syntax and logic issues, you can simulate the creation of a
GitLab CI/CD pipeline in the **Validate** tab. A pipeline simulation can help find
@@ -62,11 +72,15 @@ simulations in the [CI Lint tool](../yaml/lint.md#simulate-a-pipeline).
## View included CI/CD configuration
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7064) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `pipeline_editor_file_tree`. Disabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357219) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7064) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `pipeline_editor_file_tree`. Disabled by default.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357219) in GitLab 15.1.
+
+{{< /history >}}
You can review configuration added with the [`include`](../yaml/_index.md#include)
-keyword in the pipeline editor. In the upper-right corner, select the file tree (**{file-tree}**)
+keyword in the pipeline editor. In the upper-right corner, select the file tree ({{< icon name="file-tree" >}})
to see a list of all included configuration files. Selected files open in a new tab
for review.
@@ -87,7 +101,11 @@ each job depends only on the previous stage being completed successfully.
## View full configuration
-> - **View merged YAML** tab [renamed to **Full configuration**](https://gitlab.com/gitlab-org/gitlab/-/issues/377404) in GitLab 16.0.
+{{< history >}}
+
+- **View merged YAML** tab [renamed to **Full configuration**](https://gitlab.com/gitlab-org/gitlab/-/issues/377404) in GitLab 16.0.
+
+{{< /history >}}
To view the fully expanded CI/CD configuration as one combined file, go to the
pipeline editor's **Full configuration** tab. This tab displays an expanded configuration
diff --git a/doc/ci/pipelines/_index.md b/doc/ci/pipelines/_index.md
index ecd5b30da1fa50bdc2095acfb3eb3c4f9b05be0d..1cf8e2d3aa0be7b87763cb9790b5cd3b06c71d9b 100644
--- a/doc/ci/pipelines/_index.md
+++ b/doc/ci/pipelines/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI/CD pipelines
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
CI/CD pipelines are the fundamental component of GitLab CI/CD. Pipelines are configured
in a `.gitlab-ci.yml` file by using [YAML keywords](../yaml/_index.md).
@@ -132,17 +135,24 @@ In this example:
- `DEPLOY_ENVIRONMENT` is pre-filled in the **New pipeline** page with `canary` as the default value,
and the message explains the other options.
-NOTE:
+{{< alert type="note" >}}
+
Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/382857), projects that use [compliance pipelines](../../user/group/compliance_pipelines.md) can have prefilled variables not appear
when running a pipeline manually. To workaround this issue,
[change the compliance pipeline configuration](../../user/group/compliance_pipelines.md#prefilled-variables-are-not-shown).
+{{< /alert >}}
+
#### Configure a list of selectable prefilled variable values
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363660) in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `run_pipeline_graphql`. Disabled by default.
-> - The `options` keyword was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105502) in GitLab 15.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106038) in GitLab 15.7. Feature flag `run_pipeline_graphql` removed.
-> - The variables list sometimes did not populate correctly due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/386245), which was resolved in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363660) in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `run_pipeline_graphql`. Disabled by default.
+- The `options` keyword was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105502) in GitLab 15.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106038) in GitLab 15.7. Feature flag `run_pipeline_graphql` removed.
+- The variables list sometimes did not populate correctly due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/386245), which was resolved in GitLab 15.9.
+
+{{< /history >}}
You can define an array of CI/CD variable values the user can select from when running a pipeline manually.
These values are in a dropdown list in the **New pipeline** page. Add the list of
@@ -196,7 +206,7 @@ For each `var` or `file_var`, a key and value are required.
[Manual jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually),
allow you to require manual interaction before moving forward in the pipeline.
-You can do this straight from the pipeline graph. Select **Run** (**{play}**) to execute that particular job.
+You can do this straight from the pipeline graph. Select **Run** ({{< icon name="play" >}}) to execute that particular job.
For example, your pipeline can start automatically, but require a manual action to
[deploy to production](../environments/deployments.md#configure-manual-deployments).
@@ -207,7 +217,7 @@ In the example below, the `production` stage has a job with a manual action:
#### Start all manual jobs in a stage
If a stage contains only manual jobs, you can start all the jobs at the same time
-by selecting **Run all manual** (**{play}**) above the stage. If the stage contains
+by selecting **Run all manual** ({{< icon name="play" >}}) above the stage. If the stage contains
non-manual jobs, the option is not displayed.
### Skip a pipeline
@@ -231,11 +241,14 @@ Users with the Owner role for a project can delete a pipeline:
Deleting a pipeline does not automatically delete its [child pipelines](downstream_pipelines.md#parent-child-pipelines).
See [issue 39503](https://gitlab.com/gitlab-org/gitlab/-/issues/39503) for more details.
-WARNING:
+{{< alert type="warning" >}}
+
Deleting a pipeline expires all pipeline caches, and deletes all immediately
related objects, such as jobs, logs, artifacts, and triggers.
**This action cannot be undone.**
+{{< /alert >}}
+
### Pipeline security on protected branches
A strict security model is enforced when pipelines are executed on
@@ -267,15 +280,21 @@ page for additional security recommendations for securing your pipelines.
## Trigger a pipeline when an upstream project is rebuilt (deprecated)
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/501460) in GitLab 17.6
and is planned for removal in 19.0. Use [CI/CD jobs with pipeline trigger tokens](../triggers/_index.md#use-a-cicd-job) instead.
This is a breaking change.
+{{< /alert >}}
+
You can set up your project to automatically trigger a pipeline based on tags in a different project.
When a new tag pipeline in the subscribed project finishes, it triggers a pipeline on your project's default branch,
regardless of the tag pipeline's success, failure, or cancellation.
@@ -377,8 +396,12 @@ in the merge request.
### Pipeline details
-> - Pipeline detail view [updated](https://gitlab.com/gitlab-org/gitlab/-/issues/424403) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `new_pipeline_graph`. Disabled by default.
-> - Updated pipeline detail view [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/426902) in GitLab 16.8.
+{{< history >}}
+
+- Pipeline detail view [updated](https://gitlab.com/gitlab-org/gitlab/-/issues/424403) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `new_pipeline_graph`. Disabled by default.
+- Updated pipeline detail view [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/426902) in GitLab 16.8.
+
+{{< /history >}}
Select a pipeline to open the pipeline details page which shows every job in the pipeline.
From this page you can cancel a running pipeline, retry failed jobs, or [delete a pipeline](#delete-a-pipeline).
diff --git a/doc/ci/pipelines/compute_minutes.md b/doc/ci/pipelines/compute_minutes.md
index dbfced340e1cb92d25a1083b6dd0b5a9652ca3d0..bd3ce7f267f0fa619673a17c60a1896c87627c09 100644
--- a/doc/ci/pipelines/compute_minutes.md
+++ b/doc/ci/pipelines/compute_minutes.md
@@ -1,16 +1,23 @@
---
stage: Verify
group: Pipeline Execution
-description: Calculations, quotas, purchase information.
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
+description: Calculations, quotas, purchase information.
title: Compute minutes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" or "compute minutes" in GitLab 16.1.
+- [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" or "compute minutes" in GitLab 16.1.
+
+{{< /history >}}
The amount of time that projects can use to run jobs on [instance runners](../runners/runners_scope.md#instance-runners)
on GitLab.com is limited. This limit is tracked with a compute quota. [Project runners](../runners/runners_scope.md#project-runners)
@@ -43,7 +50,11 @@ In some cases, the quota limit is replaced by one of the following labels:
### View usage quota reports for a group
-> - Displaying instance runners duration per project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355666) in GitLab 15.0.
+{{< history >}}
+
+- Displaying instance runners duration per project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355666) in GitLab 15.0.
+
+{{< /history >}}
Prerequisites:
@@ -62,7 +73,11 @@ subgroups, sorted in descending order of compute usage.
### View usage quota reports for a personal namespace
-> - Displaying instance runners duration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345795) in GitLab 15.0.
+{{< history >}}
+
+- Displaying instance runners duration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345795) in GitLab 15.0.
+
+{{< /history >}}
You can view the compute usage for your personal namespace:
diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md
index 2964b11111e7576bab1d2572d676279b8804dd07..d26a5a7f08f091336b35a06d14cf04cf7fabdfc2 100644
--- a/doc/ci/pipelines/downstream_pipelines.md
+++ b/doc/ci/pipelines/downstream_pipelines.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Downstream pipelines
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A downstream pipeline is any GitLab CI/CD pipeline triggered by another pipeline.
Downstream pipelines run independently and concurrently to the upstream pipeline
@@ -82,9 +85,9 @@ to create a job that triggers a downstream pipeline. This job is called a trigge
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle Parent-child pipeline
+{{< tab title="Parent-child pipeline" >}}
```yaml
trigger_job:
@@ -93,7 +96,9 @@ trigger_job:
- local: path/to/child-pipeline.yml
```
-:::TabTitle Multi-project pipeline
+{{< /tab >}}
+
+{{< tab title="Multi-project pipeline" >}}
```yaml
trigger_job:
@@ -101,7 +106,9 @@ trigger_job:
project: project-group/my-downstream-project
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
After the trigger job starts, the initial status of the job is `pending` while GitLab
attempts to create the downstream pipeline. The trigger job shows `passed` if the
@@ -316,37 +323,49 @@ In the [pipeline details page](_index.md#pipeline-details), downstream pipelines
as a list of cards on the right of the graph. From this view, you can:
- Select a trigger job to see the triggered downstream pipeline's jobs.
-- Select **Expand jobs** **{chevron-lg-right}** on a pipeline card to expand the view
+- Select **Expand jobs** {{< icon name="chevron-lg-right" >}} on a pipeline card to expand the view
with the downstream pipeline's jobs. You can view one downstream pipeline at a time.
- Hover over a pipeline card to have the job that triggered the downstream pipeline highlighted.
### Retry failed and canceled jobs in a downstream pipeline
-> - Retry from graph view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354974) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `downstream_retry_action`. Disabled by default.
-> - Retry from graph view [generally available and feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357406) in GitLab 15.1.
+{{< history >}}
-To retry failed and canceled jobs, select **Retry** (**{retry}**):
+- Retry from graph view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354974) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `downstream_retry_action`. Disabled by default.
+- Retry from graph view [generally available and feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357406) in GitLab 15.1.
+
+{{< /history >}}
+
+To retry failed and canceled jobs, select **Retry** ({{< icon name="retry" >}}):
- From the downstream pipeline's details page.
- On the pipeline's card in the pipeline graph view.
### Recreate a downstream pipeline
-> - Retry trigger job from graph view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367547) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `ci_recreate_downstream_pipeline`. Disabled by default.
-> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/6947) in GitLab 15.11. Feature flag `ci_recreate_downstream_pipeline` removed.
+{{< history >}}
+
+- Retry trigger job from graph view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367547) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `ci_recreate_downstream_pipeline`. Disabled by default.
+- [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/6947) in GitLab 15.11. Feature flag `ci_recreate_downstream_pipeline` removed.
+
+{{< /history >}}
You can recreate a downstream pipeline by retrying its corresponding trigger job. The newly created downstream pipeline replaces the current downstream pipeline in the pipeline graph.
To recreate a downstream pipeline:
-- Select **Run again** (**{retry}**) on the trigger job's card in the pipeline graph view.
+- Select **Run again** ({{< icon name="retry" >}}) on the trigger job's card in the pipeline graph view.
### Cancel a downstream pipeline
-> - Retry from graph view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354974) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `downstream_retry_action`. Disabled by default.
-> - Retry from graph view [generally available and feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357406) in GitLab 15.1.
+{{< history >}}
+
+- Retry from graph view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354974) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `downstream_retry_action`. Disabled by default.
+- Retry from graph view [generally available and feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357406) in GitLab 15.1.
-To cancel a downstream pipeline that is still running, select **Cancel** (**{cancel}**):
+{{< /history >}}
+
+To cancel a downstream pipeline that is still running, select **Cancel** ({{< icon name="cancel" >}}):
- From the downstream pipeline's details page.
- On the pipeline's card in the pipeline graph view.
@@ -408,9 +427,9 @@ In this example:
You can mirror the status of the downstream pipeline in the trigger job
by using [`strategy: depend`](../yaml/_index.md#triggerstrategy):
-::Tabs
+{{< tabs >}}
-:::TabTitle Parent-child pipeline
+{{< tab title="Parent-child pipeline" >}}
```yaml
trigger_job:
@@ -420,7 +439,9 @@ trigger_job:
strategy: depend
```
-:::TabTitle Multi-project pipeline
+{{< /tab >}}
+
+{{< tab title="Multi-project pipeline" >}}
```yaml
trigger_job:
@@ -429,11 +450,17 @@ trigger_job:
strategy: depend
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### View multi-project pipelines in pipeline graphs
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/422282) from GitLab Premium to GitLab Free in 16.8.
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/422282) from GitLab Premium to GitLab Free in 16.8.
+
+{{< /history >}}
After you trigger a multi-project pipeline, the downstream pipeline displays
to the right of the [pipeline graph](_index.md#view-pipelines).
@@ -443,13 +470,16 @@ displays to the right of the mini graph.
## Fetch artifacts from an upstream pipeline
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-::Tabs
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
-:::TabTitle Parent-child pipeline
+{{< /details >}}
+
+{{< tabs >}}
+
+{{< tab title="Parent-child pipeline" >}}
Use [`needs:pipeline:job`](../yaml/_index.md#needspipelinejob) to fetch artifacts from an
upstream pipeline:
@@ -489,7 +519,9 @@ upstream pipeline:
Set `job` to the job in the upstream pipeline that created the artifacts.
-:::TabTitle Multi-project pipeline
+{{< /tab >}}
+
+{{< tab title="Multi-project pipeline" >}}
Use [`needs:project`](../yaml/_index.md#needsproject) to fetch artifacts from an
upstream pipeline:
@@ -532,7 +564,9 @@ upstream pipeline:
- `ref` to the branch.
- `artifacts` to `true`.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Fetch artifacts from an upstream merge request pipeline
@@ -602,9 +636,9 @@ These variables are "trigger variables" for [variable precedence](../variables/_
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle Parent-child pipeline
+{{< tab title="Parent-child pipeline" >}}
```yaml
variables:
@@ -619,7 +653,9 @@ staging:
- local: path/to/child-pipeline.yml
```
-:::TabTitle Multi-project pipeline
+{{< /tab >}}
+
+{{< tab title="Multi-project pipeline" >}}
```yaml
variables:
@@ -632,7 +668,9 @@ staging:
trigger: my-group/my-deployment-project
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
The `ENVIRONMENT` variable is available in every job defined in the downstream pipeline.
@@ -646,9 +684,9 @@ You can stop default CI/CD variables from reaching the downstream pipeline with
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle Parent-child pipeline
+{{< tab title="Parent-child pipeline" >}}
```yaml
variables:
@@ -664,7 +702,9 @@ trigger-job:
- local: path/to/child-pipeline.yml
```
-:::TabTitle Multi-project pipeline
+{{< /tab >}}
+
+{{< tab title="Multi-project pipeline" >}}
```yaml
variables:
@@ -678,7 +718,9 @@ trigger-job:
trigger: my-group/my-project
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
The `DEFAULT_VAR` variable is not available in the triggered pipeline, but `JOB_VAR`
is available.
@@ -689,9 +731,9 @@ To pass information about the upstream pipeline using [predefined CI/CD variable
use interpolation. Save the predefined variable as a new job variable in the trigger
job, which is passed to the downstream pipeline. For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle Parent-child pipeline
+{{< tab title="Parent-child pipeline" >}}
```yaml
trigger-job:
@@ -702,7 +744,9 @@ trigger-job:
- local: path/to/child-pipeline.yml
```
-:::TabTitle Multi-project pipeline
+{{< /tab >}}
+
+{{< tab title="Multi-project pipeline" >}}
```yaml
trigger-job:
@@ -711,7 +755,9 @@ trigger-job:
trigger: my-group/my-project
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
The `UPSTREAM_BRANCH` variable, which contains the value of the upstream pipeline's `$CI_COMMIT_REF_NAME`
predefined CI/CD variable, is available in the downstream pipeline.
@@ -729,9 +775,12 @@ the ones defined in the upstream project take precedence.
### Pass dotenv variables created in a job
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](../variables/_index.md#pass-an-environment-variable-to-another-job).
@@ -779,7 +828,11 @@ are considered trigger variables, which have the [highest precedence](../variabl
## Downstream pipelines for deployments
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369061) in GitLab 16.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369061) in GitLab 16.4.
+
+{{< /history >}}
You can use the [`environment`](../yaml/_index.md#environment) keyword with [`trigger`](../yaml/_index.md#trigger).
You might want to use `environment` from a trigger job if your deployment and application projects are separately managed.
diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md
index b12c3ab9d32acd68620d7e734b6a00403aa15741..0c38642a9cfcc1626be38d251576515a91237f63 100644
--- a/doc/ci/pipelines/merge_request_pipelines.md
+++ b/doc/ci/pipelines/merge_request_pipelines.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Merge request pipelines
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can configure your pipeline to run every time you make changes to the
source branch in a merge request.
@@ -106,13 +109,16 @@ Run pipelines in fork project MRs to ensure that the post-merge pipeline passes
the parent project. Additionally, if you do not trust the fork project's runner,
running the pipeline in the parent project uses the parent project's trusted runners.
-WARNING:
+{{< alert type="warning" >}}
+
Fork merge requests can contain malicious code that tries to steal secrets in the parent project
when the pipeline runs, even before merge. As a reviewer, carefully check the changes
in the merge request before triggering the pipeline. Unless you trigger the pipeline
through the API or the [`/rebase` quick action](../../user/project/quick_actions.md#issues-merge-requests-and-epics),
GitLab shows a warning that you must accept before the pipeline runs. Otherwise, **no warning displays**.
+{{< /alert >}}
+
Prerequisites:
- The parent project's `.gitlab-ci.yml` file must be configured to
@@ -130,17 +136,24 @@ To use the UI to run a pipeline in the parent project for a merge request from a
### Prevent pipelines from fork projects
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325189) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325189) in GitLab 15.3.
+
+{{< /history >}}
To prevent users from running new pipelines for fork projects in the parent project
use [the projects API](../../api/projects.md#edit-a-project) to disable the `ci_allow_fork_pipelines_to_run_in_parent_project`
setting.
-WARNING:
+{{< alert type="warning" >}}
+
Pipelines created before the setting was disabled are not affected and continue to run.
If you rerun a job in an older pipeline, the job uses the same context as when the
pipeline was originally created.
+{{< /alert >}}
+
## Available predefined variables
When you use merge request pipelines, you can use:
diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md
index cf92c841c078928437697a830ae21d89aa67f87c..a5d2ffeff55634204942e5a37829855e2029aeef 100644
--- a/doc/ci/pipelines/merge_trains.md
+++ b/doc/ci/pipelines/merge_trains.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Merge trains
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), the **Start merge train** and **Start merge train when pipeline succeeds** buttons became **Set to auto-merge**. **Remove from merge train** became **Cancel auto-merge**.
-> - Support for [fast-forward](../../user/project/merge_requests/methods/_index.md#fast-forward-merge) and [semi-linear](../../user/project/merge_requests/methods/_index.md#merge-commit-with-semi-linear-history) merge methods [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282442) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `fast_forward_merge_trains_support`. Enabled by default.
-> - [Feature flag `fast_forward_merge_trains_support` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148964#note_1855981445) in GitLab 16.11.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), the **Start merge train** and **Start merge train when pipeline succeeds** buttons became **Set to auto-merge**. **Remove from merge train** became **Cancel auto-merge**.
+- Support for [fast-forward](../../user/project/merge_requests/methods/_index.md#fast-forward-merge) and [semi-linear](../../user/project/merge_requests/methods/_index.md#merge-commit-with-semi-linear-history) merge methods [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282442) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `fast_forward_merge_trains_support`. Enabled by default.
+- [Feature flag `fast_forward_merge_trains_support` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148964#note_1855981445) in GitLab 16.11.
+
+{{< /history >}}
In projects with frequent merges to the default branch, changes in different merge requests
might conflict with each other. Use merge trains to put merge requests in a queue.
@@ -88,7 +95,11 @@ are canceled.
## Enable merge trains
-> - `disable_merge_trains` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/282477) in GitLab 16.5.
+{{< history >}}
+
+- `disable_merge_trains` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/282477) in GitLab 16.5.
+
+{{< /history >}}
Prerequisites:
@@ -130,7 +141,11 @@ Other merge requests can now be added to the train.
## View a merge train
-> - Merge train visualization [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13705) in GitLab 17.3.
+{{< history >}}
+
+- Merge train visualization [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13705) in GitLab 17.3.
+
+{{< /history >}}
You can view the merge train to gain better insight into the order and status of merge requests in the queue.
The merge train details page shows active merge requests in the queue and merged merge requests that were part of the train.
@@ -147,14 +162,18 @@ You also access this view by selecting **View merge train details** from:
- The pipeline widget and system notes on a merge request added to a merge train.
- The pipeline details page for a merge train pipeline.
-You can also remove (**{close}**) a merge request from the merge train details view.
+You can also remove ({{< icon name="close" >}}) a merge request from the merge train details view.
## Add a merge request to a merge train
-> - Auto-merge for merge trains [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10874) in GitLab 17.2 [with a flag](../../administration/feature_flags.md) named `merge_when_checks_pass_merge_train`. Disabled by default.
-> - Auto-merge for merge trains [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/470667) on GitLab.com in GitLab 17.2.
-> - Auto-merge for merge trains [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/470667) by default in GitLab 17.4.
-> - Auto-merge for merge trains [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174357) in GitLab 17.7. Feature flag `merge_when_checks_pass_merge_train` removed.
+{{< history >}}
+
+- Auto-merge for merge trains [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10874) in GitLab 17.2 [with a flag](../../administration/feature_flags.md) named `merge_when_checks_pass_merge_train`. Disabled by default.
+- Auto-merge for merge trains [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/470667) on GitLab.com in GitLab 17.2.
+- Auto-merge for merge trains [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/470667) by default in GitLab 17.4.
+- Auto-merge for merge trains [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174357) in GitLab 17.7. Feature flag `merge_when_checks_pass_merge_train` removed.
+
+{{< /history >}}
Prerequisites:
@@ -187,7 +206,7 @@ You can add the merge request to a merge train again later.
To remove a merge request from a merge train:
- From a merge request, select **Cancel auto-merge**.
-- From the [merge train details](#view-a-merge-train), next to the merge request, select **{close}**.
+- From the [merge train details](#view-a-merge-train), next to the merge request, select {{< icon name="close" >}}.
## Skip the merge train and merge immediately
@@ -202,27 +221,43 @@ When you merge a merge request immediately:
with a new merge train pipeline for each. These new merge train pipelines now contain
the commits added by the merge request that was merged immediately.
-WARNING:
+{{< alert type="warning" >}}
+
Merging immediately can use a lot of CI/CD resources. Use this option
only in critical situations.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The **merge immediately** option may not be available if your project uses the [fast-forward](../../user/project/merge_requests/methods/_index.md#fast-forward-merge)
merge method and the source branch is behind the target branch. See [issue 434070](https://gitlab.com/gitlab-org/gitlab/-/issues/434070) for more details.
+{{< /alert >}}
+
### Allow merge trains to be skipped to merge immediately without restarting merge train pipelines
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414505) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `merge_trains_skip_train`. Disabled by default.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/422111) as an [experiment feature](../../policy/development_stages_support.md) in GitLab 16.10.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414505) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `merge_trains_skip_train`. Disabled by default.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/422111) as an [experiment feature](../../policy/development_stages_support.md) in GitLab 16.10.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is available. To hide the feature,
an administrator can [disable the feature flag](../../administration/feature_flags.md)
named `merge_trains_skip_train`. On GitLab.com and GitLab Dedicated, this feature is available.
+{{< /alert >}}
+
You can allow merge requests to be merged without completely restarting a running merge train.
Use this feature to quickly merge changes that can safely skip the pipeline, for example
minor documentation updates.
@@ -231,13 +266,16 @@ You cannot skip merge trains for fast-forward or semi-linear merge methods. For
Skipping merge trains is an experimental feature. It may change or be removed completely in future releases.
-WARNING:
+{{< alert type="warning" >}}
+
You can use this feature to quickly merge security or bug fixes, but the changes
in the merge request that skipped the train are not verified against
any of the other merge requests in the train. If these other merge train pipelines
complete successfully and merge, there is a risk that the combined changes are incompatible.
The target branch could then require additional work to resolve the new failures.
+{{< /alert >}}
+
Prerequisites:
- You must have the Maintainer role.
diff --git a/doc/ci/pipelines/merged_results_pipelines.md b/doc/ci/pipelines/merged_results_pipelines.md
index f12025acbe7e594f898ea7af858967b45a8b3223..aa32d1d2e9a3c432e4ed030bb88d43f0af85d85a 100644
--- a/doc/ci/pipelines/merged_results_pipelines.md
+++ b/doc/ci/pipelines/merged_results_pipelines.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Merged results pipelines
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91849) in GitLab 15.1, merged results pipelines also run on [Draft merge requests](../../user/project/merge_requests/drafts.md).
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91849) in GitLab 15.1, merged results pipelines also run on [Draft merge requests](../../user/project/merge_requests/drafts.md).
+
+{{< /history >}}
A merged results pipeline runs on the result of the source and target branches merged together.
It is a type of [merge request pipeline](merge_request_pipelines.md).
@@ -46,11 +53,14 @@ Maintainer role:
1. In the **Merge options** section, select **Enable merged results pipelines**.
1. Select **Save changes**.
-WARNING:
+{{< alert type="warning" >}}
+
If you select the checkbox but don't configure your pipeline to use
merge request pipelines, your merge requests may become stuck in an
unresolved state or your pipelines may be dropped.
+{{< /alert >}}
+
## Troubleshooting
### Jobs or pipelines run unexpectedly with `rules:changes:compare_to`
diff --git a/doc/ci/pipelines/mr_pipeline_troubleshooting.md b/doc/ci/pipelines/mr_pipeline_troubleshooting.md
index 0cc9321f1137242c00e46d62ace6205907baaec8..99f84db1d43576c5c36662f7497556246688b4df 100644
--- a/doc/ci/pipelines/mr_pipeline_troubleshooting.md
+++ b/doc/ci/pipelines/mr_pipeline_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Merge request pipeline troubleshooting
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with merge request pipelines, you might encounter the following issues.
diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md
index 858ee666c3041eefdab26900e3dd76b36f9f27ca..a0395536fc7fa05f80b3d972944a21fea4a17e70 100644
--- a/doc/ci/pipelines/pipeline_architectures.md
+++ b/doc/ci/pipelines/pipeline_architectures.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pipeline architecture
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Pipelines are the fundamental building blocks for CI/CD in GitLab. This page documents
some of the important concepts related to them.
diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md
index 7d854f647f71cb6107705afc16e065193108cb11..5ec72468e414470634002355746ff279189fe0ef 100644
--- a/doc/ci/pipelines/pipeline_efficiency.md
+++ b/doc/ci/pipelines/pipeline_efficiency.md
@@ -5,9 +5,12 @@ info: This page is maintained by Developer Relations, author @dnsmichi, see http
title: Pipeline efficiency
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[CI/CD Pipelines](_index.md) are the fundamental building blocks for [GitLab CI/CD](../_index.md).
Making pipelines more efficient helps you save developer time, which:
diff --git a/doc/ci/pipelines/pipeline_security.md b/doc/ci/pipelines/pipeline_security.md
index 53a5d81086ce37e31ffdc42c7dc3c8675f1c0d4f..1ff05abb34dd0285e58bae53976067f8accf9779 100644
--- a/doc/ci/pipelines/pipeline_security.md
+++ b/doc/ci/pipelines/pipeline_security.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pipeline security
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Secrets Management
diff --git a/doc/ci/pipelines/pipeline_types.md b/doc/ci/pipelines/pipeline_types.md
index c34462b54a1e3ed7ba28c6b35140624942ad66c8..68ca8ea52b40e26ae7f323485e093c3043a3e33c 100644
--- a/doc/ci/pipelines/pipeline_types.md
+++ b/doc/ci/pipelines/pipeline_types.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Types of pipelines
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Multiple types of pipelines can run in a project, including:
@@ -65,7 +68,11 @@ For more information, see [merge request pipelines](merge_request_pipelines.md).
## Merged results pipeline
-> - The `merged results` label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132975) in GitLab 16.5.
+{{< history >}}
+
+- The `merged results` label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132975) in GitLab 16.5.
+
+{{< /history >}}
A *merged results pipeline* runs on the result of the source and target branches merged together.
It's a type of merge request pipeline.
diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md
index 17872df6c9086d4a0276ecc235da8fa777172482..030b34a970b453c3bdedec360a345334c1dc61b4 100644
--- a/doc/ci/pipelines/schedules.md
+++ b/doc/ci/pipelines/schedules.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Scheduled pipelines
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use scheduled pipelines to run GitLab CI/CD [pipelines](_index.md) at regular intervals.
@@ -47,7 +50,7 @@ The owner of a pipeline schedule can edit it:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Build > Pipeline schedules**.
-1. Next to the schedule, select **Edit** (**{pencil}**) and fill in the form.
+1. Next to the schedule, select **Edit** ({{< icon name="pencil" >}}) and fill in the form.
The user must have the Developer role or above for the project. If the user is
not the owner of the schedule, they must first [take ownership](#take-ownership)
@@ -61,7 +64,7 @@ the next scheduled time:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Build > Pipeline schedules**.
1. On the right of the list, for
- the pipeline you want to run, select **Run** (**{play}**).
+ the pipeline you want to run, select **Run** ({{< icon name="play" >}}).
You can manually run scheduled pipelines once per minute.
diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md
index c2236c44616a2ebbc307ef26d5ca312c17dcb3f4..24faf5bb682d92bb12971ab3558246e1e54093a4 100644
--- a/doc/ci/pipelines/settings.md
+++ b/doc/ci/pipelines/settings.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Customize pipeline configuration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can customize how pipelines run for your project.
@@ -86,7 +89,11 @@ running job can be canceled before it completes. After a job with
## Prevent outdated deployment jobs
-> - Also preventing outdated manual or retried deployment jobs from running [added](https://gitlab.com/gitlab-org/gitlab/-/issues/363328) in GitLab 15.5.
+{{< history >}}
+
+- Also preventing outdated manual or retried deployment jobs from running [added](https://gitlab.com/gitlab-org/gitlab/-/issues/363328) in GitLab 15.5.
+
+{{< /history >}}
Your project may have multiple concurrent deployment jobs that are
scheduled to run in the same time frame.
@@ -107,11 +114,18 @@ For more information, see [Deployment safety](../environments/deployment_safety.
## Restrict roles that can cancel pipelines or jobs
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137301) in GitLab 16.7.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137301) in GitLab 16.7.
+
+{{< /history >}}
You can customize which roles have permission to cancel pipelines or jobs.
@@ -143,10 +157,13 @@ To customize the path:
- Is on an external site, enter the full URL.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
You cannot use your project's [pipeline editor](../pipeline_editor/_index.md) to
edit CI/CD configuration files in other projects or on an external site.
+{{< /alert >}}
+
### Custom CI/CD configuration file examples
If the CI/CD configuration file is not in the root directory, the path must be relative to it.
@@ -258,12 +275,19 @@ These changes do not apply to projects in an [external integration](../../user/p
## Automatic pipeline cleanup
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/498969) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `ci_delete_old_pipelines`. Disabled by default.
+- [Feature flag `ci_delete_old_pipelines`](https://gitlab.com/gitlab-org/gitlab/-/issues/503153) removed in GitLab 17.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/498969) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `ci_delete_old_pipelines`. Disabled by default.
-> - [Feature flag `ci_delete_old_pipelines`](https://gitlab.com/gitlab-org/gitlab/-/issues/503153) removed in GitLab 17.9.
+{{< /history >}}
Users with the Owner role can set a CI/CD pipeline expiry time to help manage pipeline storage and improve system performance.
The system automatically deletes pipelines that were created before the configured value.
diff --git a/doc/ci/quick_start/_index.md b/doc/ci/quick_start/_index.md
index 0a1fbb952f5392a0efee4cb906bca7b3b5292af7..9903b83046436a4a09b9049f40533fec577d1144 100644
--- a/doc/ci/quick_start/_index.md
+++ b/doc/ci/quick_start/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Create and run your first GitLab CI/CD pipeline'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This tutorial shows you how to configure and run your first CI/CD pipeline in GitLab.
@@ -76,7 +79,7 @@ To create a `.gitlab-ci.yml` file in your project:
1. Select **Code > Repository**.
1. Above the file list, select the branch you want to commit to.
If you're not sure, leave `master` or `main`.
- Then select the plus icon (**{plus}**) and **New file**:
+ Then select the plus icon ({{< icon name="plus" >}}) and **New file**:
diff --git a/doc/ci/quick_start/tutorial.md b/doc/ci/quick_start/tutorial.md
index ccb2b1c0ed81f344b0471e74e3aea08cd6e27302..5549020652068936c6594f571cd9b4062b19ef0e 100644
--- a/doc/ci/quick_start/tutorial.md
+++ b/doc/ci/quick_start/tutorial.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Create a complex pipeline'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This tutorial walks you through configuring a progressively more complex CI/CD pipeline
through small, iterative steps. The pipeline is always fully functional,
@@ -40,7 +43,7 @@ Before adding the pipeline configuration, you must first set up a Docusaurus pro
on GitLab.com:
1. Create a new project under your username (not a group):
- 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+ 1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details:
- In the **Project name** field, enter the name of your project, for example `My Pipeline Tutorial Project`.
@@ -225,9 +228,12 @@ To view your site:
- Make sure **Use unique domain** is off.
- Under **Access pages**, select the link. The URL format should be similar to: `https://<my-username>.gitlab.io/<project-name>`. For more information, see [GitLab Pages default domain names](../../user/project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names).
-NOTE:
+{{< alert type="note" >}}
+
If you need to [use unique domains](../../user/project/pages/_index.md#unique-domains), in `docusaurus.config.js`, set `baseUrl`: to `/`.
+{{< /alert >}}
+
## Add test jobs
Now that the site builds and deploys as expected, you can add tests and linting.
diff --git a/doc/ci/resource_groups/_index.md b/doc/ci/resource_groups/_index.md
index bb41b76463db1e8dfb25684c791e61d762190ffe..62e83d4bdaac61ca2b28709d5c7f579df45a783c 100644
--- a/doc/ci/resource_groups/_index.md
+++ b/doc/ci/resource_groups/_index.md
@@ -6,9 +6,12 @@ description: Control the job concurrency in GitLab CI/CD
title: Resource group
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
By default, pipelines in GitLab CI/CD run concurrently. Concurrency is an important factor to improve
the feedback loop in merge requests, however, there are some situations that
diff --git a/doc/ci/review_apps/_index.md b/doc/ci/review_apps/_index.md
index 3a447e497f7a9b1603bca96a15f1cdd23d4e670d..58cd2d1dfa10fa7f079ae75420aeed5cafeacbd9 100644
--- a/doc/ci/review_apps/_index.md
+++ b/doc/ci/review_apps/_index.md
@@ -5,16 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Review apps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Review apps are a collaboration tool that provide an environment to showcase product changes.
-NOTE:
+{{< alert type="note" >}}
+
If you have a Kubernetes cluster, you can automate this feature in your applications
by using [Auto DevOps](../../topics/autodevops/_index.md).
+{{< /alert >}}
+
Review apps:
- Provide an automatic live preview of changes made in a feature branch by spinning up a dynamic environment for your merge requests.
@@ -183,6 +189,6 @@ After you have the route mapping set up, it takes effect in the following locati
-- In the diff for a comparison or commit, by selecting **View** (**{external-link}**) next to the file.
+- In the diff for a comparison or commit, by selecting **View** ({{< icon name="external-link" >}}) next to the file.
-- In the blob file view, by selecting **View** (**{external-link}**) next to the file.
+- In the blob file view, by selecting **View** ({{< icon name="external-link" >}}) next to the file.
diff --git a/doc/ci/runners/_index.md b/doc/ci/runners/_index.md
index ce3378c6e6b035d2471465f4a722cca6ef0f210c..ee4e450d27c4abdb41ca579c8ce87a0654065bc7 100644
--- a/doc/ci/runners/_index.md
+++ b/doc/ci/runners/_index.md
@@ -43,9 +43,12 @@ Runners can be group, project, or instance runners. GitLab-hosted runners are in
### GitLab-hosted runners
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Dedicated
+
+{{< /details >}}
GitLab-hosted runners are:
@@ -65,9 +68,12 @@ Choose GitLab-hosted runners when:
### Self-managed runners
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Self-managed runners are:
diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md
index ee50c83a77b0760bf523271072067cbf44ec4ef4..3e2a92c3395f9fb156f334c1c6e7384608849cad 100644
--- a/doc/ci/runners/configure_runners.md
+++ b/doc/ci/runners/configure_runners.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configuring runners
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This document describes how to configure runners in the GitLab UI.
@@ -36,7 +39,7 @@ To set the maximum job timeout:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **CI/CD > Runners**.
-1. To the right of the runner, you want to edit, select **Edit** (**{pencil}**).
+1. To the right of the runner, you want to edit, select **Edit** ({{< icon name="pencil" >}}).
1. In the **Maximum job timeout** field, enter a value in seconds. The minimum value is 600 seconds (10 minutes).
1. Select **Save changes**.
@@ -50,7 +53,7 @@ To set the maximum job timeout:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Build > Runners**.
-1. To the right of the runner you want to edit, select **Edit** (**{pencil}**).
+1. To the right of the runner you want to edit, select **Edit** ({{< icon name="pencil" >}}).
1. In the **Maximum job timeout** field, enter a value in seconds. The minimum value is 600 seconds (10 minutes).
1. Select **Save changes**.
@@ -65,7 +68,7 @@ To set the maximum job timeout:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > CI/CD**.
1. Expand **Runners**.
-1. To the right of the runner you want to edit, select **Edit** (**{pencil}**).
+1. To the right of the runner you want to edit, select **Edit** ({{< icon name="pencil" >}}).
1. In the **Maximum job timeout** field, enter a value in seconds. The minimum value is 600 seconds (10 minutes). If not defined, the [job timeout for the project](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) is used instead.
1. Select **Save changes**.
@@ -94,7 +97,11 @@ To set the maximum job timeout:
## Set `script` and `after_script` timeouts
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/4335) in GitLab Runner 16.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/4335) in GitLab Runner 16.4.
+
+{{< /history >}}
To control the amount of time `script` and `after_script` runs before it terminates, specify a timeout value in the `.gitlab-ci.yml` file.
@@ -159,12 +166,15 @@ To work around this issue, ensure that the instance runner settings are consiste
## Reset the runner registration token for a project (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
The option to pass a runner registration token and support for certain configuration arguments was
[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6. They are scheduled for removal
in GitLab 18.0. Use runner authentication tokens instead. For more information, see
[Migrating to the new runner registration workflow](new_creation_workflow.md).
+{{< /alert >}}
+
If you think that a registration token for a project was revealed, you should
reset it. A registration token can be used to register another runner for the project.
That new runner may then be used to obtain the values of secret variables or to clone project code.
@@ -174,7 +184,7 @@ To reset the registration token:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > CI/CD**.
1. Expand **Runners**.
-1. To the right of **New project runner**, select the vertical ellipsis (**{ellipsis_v}**).
+1. To the right of **New project runner**, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. Select **Reset registration token**.
1. Select **Reset token**.
@@ -184,8 +194,12 @@ you use to provision and register new values.
## Authentication token security
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/377902) in GitLab 15.5. Feature flag `enforce_runner_token_expires_at` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/377902) in GitLab 15.5. Feature flag `enforce_runner_token_expires_at` removed.
+
+{{< /history >}}
Each runner uses a [runner authentication token](../../api/runners.md#registration-and-authentication-tokens)
to connect to and authenticate with a GitLab instance.
@@ -256,7 +270,7 @@ Prerequisites:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **CI/CD > Runners**.
-1. To the right of the runner you want to protect, select **Edit** (**{pencil}**).
+1. To the right of the runner you want to protect, select **Edit** ({{< icon name="pencil" >}}).
1. Select the **Protected** checkbox.
1. Select **Save changes**.
@@ -268,7 +282,7 @@ Prerequisites:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Build > Runners**.
-1. To the right of the runner you want to protect, select **Edit** (**{pencil}**).
+1. To the right of the runner you want to protect, select **Edit** ({{< icon name="pencil" >}}).
1. Select the **Protected** checkbox.
1. Select **Save changes**.
@@ -281,7 +295,7 @@ Prerequisites:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > CI/CD**.
1. Expand **Runners**.
-1. To the right of the runner you want to protect, select **Edit** (**{pencil}**).
+1. To the right of the runner you want to protect, select **Edit** ({{< icon name="pencil" >}}).
1. Select the **Protected** checkbox.
1. Select **Save changes**.
@@ -304,7 +318,7 @@ To control the jobs that an instance runner can run:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **CI/CD > Runners**.
-1. To the right of the runner you want to edit, select **Edit** (**{pencil}**).
+1. To the right of the runner you want to edit, select **Edit** ({{< icon name="pencil" >}}).
1. Set the runner to run tagged or untagged jobs:
- To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `rails`.
- To run untagged jobs, select the **Run untagged jobs** checkbox.
@@ -320,7 +334,7 @@ To control the jobs that a group runner can run:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Build > Runners**.
-1. To the right of the runner you want to edit, select **Edit** (**{pencil}**).
+1. To the right of the runner you want to edit, select **Edit** ({{< icon name="pencil" >}}).
1. Set the runner to run tagged or untagged jobs:
- To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `ruby`.
- To run untagged jobs, select the **Run untagged jobs** checkbox.
@@ -337,7 +351,7 @@ To control the jobs that a project runner can run:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > CI/CD**.
1. Expand **Runners**.
-1. To the right of the runner you want to edit, select **Edit** (**{pencil}**).
+1. To the right of the runner you want to edit, select **Edit** ({{< icon name="pencil" >}}).
1. Set the runner to run tagged or untagged jobs:
- To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `ruby`.
- To run untagged jobs, select the **Run untagged jobs** checkbox.
@@ -648,7 +662,11 @@ Where `$REFSPECS` is a value provided to the runner internally by GitLab.
### Sync or exclude specific submodules from CI jobs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/2249) in GitLab Runner 14.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/2249) in GitLab Runner 14.0.
+
+{{< /history >}}
Use the `GIT_SUBMODULE_PATHS` variable to control which submodules have to be synced or updated.
You can set it globally or per-job in the [`variables`](../yaml/_index.md#variables) section.
@@ -669,12 +687,15 @@ The path syntax is the same as [`git submodule`](https://git-scm.com/docs/git-su
GIT_SUBMODULE_PATHS: ":(exclude)submoduleA :(exclude)submoduleB"
```
-WARNING:
+{{< alert type="warning" >}}
+
Git ignores nested paths. To ignore a nested submodule, exclude
the parent submodule and then manually clone it in the job's scripts. For example,
`git clone <repo> --recurse-submodules=':(exclude)nested-submodule'`. Make sure
to wrap the string in single quotes so the YAML can be parsed successfully.
+{{< /alert >}}
+
### Git submodule update flags
Use the `GIT_SUBMODULE_UPDATE_FLAGS` variable to control the behavior of `git submodule update`
@@ -709,14 +730,21 @@ The configuration above results in `git submodule update` being called this way:
git submodule update --init --depth 50 --recursive --remote --jobs 4
```
-WARNING:
+{{< alert type="warning" >}}
+
You should be aware of the implications for the security, stability, and reproducibility of
your builds when using the `--remote` flag. In most cases, it is better to explicitly track
submodule commits as designed, and update them using an auto-remediation/dependency bot.
+{{< /alert >}}
+
### Rewrite submodule URLs to HTTPS
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3198) in GitLab Runner 15.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3198) in GitLab Runner 15.11.
+
+{{< /history >}}
Use the `GIT_SUBMODULE_FORCE_HTTPS` variable to force a rewrite of all Git and SSH submodule URLs to HTTPS.
You can clone submodules that use absolute URLs on the same GitLab instance, even if they were
@@ -765,7 +793,11 @@ You can set it globally or per-job in the [`variables`](../yaml/_index.md#variab
### Git submodule depth
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3651) in GitLab Runner 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3651) in GitLab Runner 15.5.
+
+{{< /history >}}
Use the `GIT_SUBMODULE_DEPTH` variable to specify the depth of fetching and cloning submodules
when [`GIT_SUBMODULE_STRATEGY`](#git-submodule-strategy) is set to either `normal` or `recursive`.
@@ -947,7 +979,11 @@ variables:
## Artifact provenance metadata
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28940) in GitLab Runner 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28940) in GitLab Runner 15.1.
+
+{{< /history >}}
Runners can generate and produce provenance metadata for all build artifacts.
@@ -1178,7 +1214,11 @@ see the [in-toto statement](https://in-toto.io/Statement/v0.1).
## Staging directory
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3403) in GitLab Runner 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3403) in GitLab Runner 15.0.
+
+{{< /history >}}
If you do not want to archive cache and artifacts in the system's default temporary directory, you can specify a different directory.
@@ -1192,7 +1232,11 @@ used, this location is also used as scratch space when archiving.
## Configure `fastzip` to improve performance
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3130) in GitLab Runner 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3130) in GitLab Runner 15.0.
+
+{{< /history >}}
To tune `fastzip`, ensure the [`FF_USE_FASTZIP`](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) flag is enabled.
Then use any of the following environment variables.
diff --git a/doc/ci/runners/git_submodules.md b/doc/ci/runners/git_submodules.md
index d99570ad457a90e5e849949f6daa3bde5b4b10f3..79f2c1409840932f9e4be02fffae698166110fc0 100644
--- a/doc/ci/runners/git_submodules.md
+++ b/doc/ci/runners/git_submodules.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using Git submodules with GitLab CI/CD
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to keep
a Git repository as a subdirectory of another Git repository. You can clone another
@@ -20,7 +23,11 @@ You have multiple options to configure it to work in a GitLab CI/CD job.
### Using absolute URLs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3198) in GitLab Runner 15.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3198) in GitLab Runner 15.11.
+
+{{< /history >}}
For example, your generated `.gitmodules` configuration might look like the following if:
@@ -51,10 +58,13 @@ You do not need to configure additional variables in this case, but you need to
### Using relative URLs
-WARNING:
+{{< alert type="warning" >}}
+
If you use relative URLs, submodules may resolve incorrectly in forking workflows.
Use absolute URLs instead if you expect your project to have forks.
+{{< /alert >}}
+
When your submodule is on the same GitLab server, you can also use relative URLs in
your `.gitmodules` file:
diff --git a/doc/ci/runners/hosted_runners/_index.md b/doc/ci/runners/hosted_runners/_index.md
index d2925dbec3ff3e527f7ec04dec21685170ccaad0..0e5d2ce98251610a87f232870682f6716ef5e50b 100644
--- a/doc/ci/runners/hosted_runners/_index.md
+++ b/doc/ci/runners/hosted_runners/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab-hosted runners
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Dedicated
+
+{{< /details >}}
Use GitLab-hosted runners to run your CI/CD jobs on GitLab.com and GitLab Dedicated.
These runners can build, test, and deploy applications on different environments.
@@ -16,8 +19,11 @@ To create and register your own runners, see [self-managed runners](https://docs
## Hosted runners for GitLab.com
-DETAILS:
-**Offering:** GitLab.com
+{{< details >}}
+
+- Offering: GitLab.com
+
+{{< /details >}}
These runners are fully integrated with GitLab.com and are enabled by default for all projects, with no configuration required.
Your jobs can run on:
@@ -37,9 +43,12 @@ When you use hosted runners:
This means that the available free disk space for your jobs to use is reduced.
- [Untagged](../../yaml/_index.md#tags) jobs run on the `small` Linux x86-64 runner.
-NOTE:
+{{< alert type="note" >}}
+
Jobs handled by hosted runners on GitLab.com time out after 3 hours, regardless of the timeout configured in a project.
+{{< /alert >}}
+
### Security of hosted runners for GitLab.com
The following section provides an overview of the additional built-in layers that harden the security of the GitLab Runner build environment.
@@ -103,8 +112,11 @@ You can find all GitLab Runner breaking changes under [Deprecations and removals
## Hosted runners for GitLab community contributions
-DETAILS:
-**Offering:** GitLab.com
+{{< details >}}
+
+- Offering: GitLab.com
+
+{{< /details >}}
If you want to [contribute to GitLab](https://about.gitlab.com/community/contribute/), jobs are picked up by the
`gitlab-shared-runners-manager-X.gitlab.com` fleet of runners, dedicated for GitLab projects and related community forks.
@@ -116,8 +128,11 @@ As we want to encourage people to contribute, these runners are free of charge.
## Hosted runners for GitLab Dedicated
-DETAILS:
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Offering: GitLab Dedicated
+
+{{< /details >}}
Hosted runners for GitLab Dedicated are created on demand and are fully integrated with your GitLab Dedicated instance.
For more information, see [hosted runners for GitLab Dedicated](../../../administration/dedicated/hosted_runners.md).
diff --git a/doc/ci/runners/hosted_runners/gpu_enabled.md b/doc/ci/runners/hosted_runners/gpu_enabled.md
index 4ed7ecc2b4b63b093ecd40d3b37532fae5abb498..c414014e46ad4c8b50ae718ce77ae1a063d250b0 100644
--- a/doc/ci/runners/hosted_runners/gpu_enabled.md
+++ b/doc/ci/runners/hosted_runners/gpu_enabled.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GPU-enabled hosted runners
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
GitLab provides GPU-enabled hosted runners to accelerate heavy compute workloads for ModelOps
or HPC such as the training or deployment of Large Language Models (LLMs) as part of ModelOps workloads.
diff --git a/doc/ci/runners/hosted_runners/linux.md b/doc/ci/runners/hosted_runners/linux.md
index 75a4120475d9a6c46f7ea51bf67efa7d45d85527..4337017d1ecc0f67d33290f3872ee931feba9d37 100644
--- a/doc/ci/runners/hosted_runners/linux.md
+++ b/doc/ci/runners/hosted_runners/linux.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Hosted runners on Linux
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Hosted runners on Linux for GitLab.com run on Google Cloud Compute Engine. Each job gets a fully isolated, ephemeral virtual machine (VM). The default region is `us-east1`.
@@ -39,12 +42,15 @@ GitLab offers the following machine type for hosted runners on Linux Arm64.
| `saas-linux-medium-arm64` (Premium and Ultimate only) | 4 | 16 GB | 50 GB |
| `saas-linux-large-arm64` (Premium and Ultimate only) | 8 | 32 GB | 100 GB |
-NOTE:
+{{< alert type="note" >}}
+
Users can experience network connectivity issues when they use Docker-in-Docker with hosted runners on Linux
Arm. This issue occurs when the maximum transmission unit (MTU) value in Google Cloud and Docker don't match.
To resolve this issue, set `--mtu=1400` in the client side Docker configuration.
For more details, see [issue 473739](https://gitlab.com/gitlab-org/gitlab/-/issues/473739#workaround).
+{{< /alert >}}
+
## Container images
As runners on Linux are using the `docker+machine` [executor](https://docs.gitlab.com/runner/executors/#docker-machine-executor),
diff --git a/doc/ci/runners/hosted_runners/macos.md b/doc/ci/runners/hosted_runners/macos.md
index 3a63e1734d36b0f78aa29fd89a87cc841beba701..b1bcea52af509019b3a5182784ba1fd75068d765 100644
--- a/doc/ci/runners/hosted_runners/macos.md
+++ b/doc/ci/runners/hosted_runners/macos.md
@@ -5,10 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Hosted runners on macOS
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
+
+{{< /details >}}
Hosted runners on macOS provide an on-demand macOS environment, fully integrated with GitLab [CI/CD](../../_index.md).
You can use these runners to build, test, and deploy apps for the Apple ecosystem (macOS, iOS, watchOS, tvOS).
diff --git a/doc/ci/runners/hosted_runners/windows.md b/doc/ci/runners/hosted_runners/windows.md
index 7fdcdbd5a73511f9f072238f799c3b639f1105a0..41a44d9e3829413deb7d31397bc0bedb01b4140c 100644
--- a/doc/ci/runners/hosted_runners/windows.md
+++ b/doc/ci/runners/hosted_runners/windows.md
@@ -5,10 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Hosted runners on Windows
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
+
+{{< /details >}}
Hosted runners on Windows autoscale by launching virtual machines on
the Google Cloud Platform. This solution uses an
diff --git a/doc/ci/runners/long_polling.md b/doc/ci/runners/long_polling.md
index 4a1a9631afee0a17ad141c524a3b1e7c2ef68d42..06cbccde412cd4759eb3e54b839b5c91ee325528 100644
--- a/doc/ci/runners/long_polling.md
+++ b/doc/ci/runners/long_polling.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Long polling
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
By default, a GitLab Runner polls a GitLab instance for new CI/CD
jobs periodically. The actual polling interval [depends on the `check_interval` and number of runners configured in the runner configuration file](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#how-check_interval-works).
@@ -31,9 +34,9 @@ poll until a new job is ready.
To do this, enable long polling by configuring the GitLab Workhorse long
polling duration (`apiCiLongPollingDuration`):
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -47,7 +50,9 @@ polling duration (`apiCiLongPollingDuration`):
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Enable long polling with the `gitlab.webservice.workhorse.extraArgs` setting.
@@ -72,7 +77,9 @@ Enable long polling with the `gitlab.webservice.workhorse.extraArgs` setting.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -94,7 +101,9 @@ Enable long polling with the `gitlab.webservice.workhorse.extraArgs` setting.
docker compose up -d
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Metrics
diff --git a/doc/ci/runners/new_creation_workflow.md b/doc/ci/runners/new_creation_workflow.md
index 5546358903358582e1512107e887d651e0a0d866..c008152215c2d0e1b6a3f931cfa614df8a75170e 100644
--- a/doc/ci/runners/new_creation_workflow.md
+++ b/doc/ci/runners/new_creation_workflow.md
@@ -5,16 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating to the new runner registration workflow
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the
-sole discretion of GitLab Inc.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="disclaimer" />}}
In GitLab 16.0, we introduced a new runner creation workflow that uses runner authentication tokens to register
runners. The legacy workflow that uses registration tokens is deprecated and will be removed in GitLab 18.0.
@@ -65,11 +63,14 @@ To avoid a broken workflow, you must:
1. Replace the registration token in your runner registration workflow with the
authentication token.
-WARNING:
+{{< alert type="warning" >}}
+
In GitLab 17.0 and later, runner registration tokens are disabled.
To use stored runner registration tokens to register new runners,
you must [enable the tokens](../../administration/settings/continuous_integration.md#allow-runner-registrations-tokens).
+{{< /alert >}}
+
## Using registration tokens after GitLab 17.0
To continue using registration tokens after GitLab 17.0:
@@ -211,10 +212,13 @@ data:
runner-token: "REDACTED"
```
-NOTE:
+{{< alert type="note" >}}
+
If your secret management solution doesn't allow you to set an empty string for `runner-registration-token`,
you can set it to any string - it will be ignored when `runner-token` is present.
+{{< /alert >}}
+
## Known issues
### Pod name is not visible in runner details page
diff --git a/doc/ci/runners/provision_runners_google_cloud.md b/doc/ci/runners/provision_runners_google_cloud.md
index 9b19008583c5f93c6ae280641af5965331f005c4..dcaae56908cd47e8f8f8c36523c126f2dd5e6c30 100644
--- a/doc/ci/runners/provision_runners_google_cloud.md
+++ b/doc/ci/runners/provision_runners_google_cloud.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Provision runners in Google Cloud Compute Engine
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438316) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `google_cloud_support_feature_flag`. This feature is in [beta](../../policy/development_stages_support.md).
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438316) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `google_cloud_support_feature_flag`. This feature is in [beta](../../policy/development_stages_support.md).
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+
+{{< /history >}}
You can create a project or group runner for GitLab.com and provision it on your Google Cloud project.
When you create a runner, the GitLab UI provides on-screen instructions and scripts to automatically provision the runner
diff --git a/doc/ci/runners/runner_fleet_dashboard.md b/doc/ci/runners/runner_fleet_dashboard.md
index dddbf4833711e161e2aac12b2ffbf664bf75102c..0d1a0f5bc1ed713d19e0fbc7ad7483fa32af4a74 100644
--- a/doc/ci/runners/runner_fleet_dashboard.md
+++ b/doc/ci/runners/runner_fleet_dashboard.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Runner fleet dashboard for administrators
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424495) in GitLab 16.6
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424495) in GitLab 16.6
+
+{{< /history >}}
As a GitLab administrator, you can use the runner fleet dashboard to assess the health of your instance runners.
The runner fleet dashboard shows:
@@ -68,19 +75,29 @@ To export compute minutes used by instance runners:
## Enable more CI analytics features with ClickHouse
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11180) as an [experiment](../../policy/development_stages_support.md#experiment) in GitLab 16.7 with [flags](../../administration/feature_flags.md) named `ci_data_ingestion_to_click_house` and `clickhouse_ci_analytics`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/424866) in GitLab 16.10. Feature flags `ci_data_ingestion_to_click_house` and `clickhouse_ci_analytics` removed.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424789) to [beta](../../policy/development_stages_support.md#beta) in GitLab 17.1.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11180) as an [experiment](../../policy/development_stages_support.md#experiment) in GitLab 16.7 with [flags](../../administration/feature_flags.md) named `ci_data_ingestion_to_click_house` and `clickhouse_ci_analytics`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/424866) in GitLab 16.10. Feature flags `ci_data_ingestion_to_click_house` and `clickhouse_ci_analytics` removed.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424789) to [beta](../../policy/development_stages_support.md#beta) in GitLab 17.1.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature is in [beta](../../policy/development_stages_support.md#beta) and subject to change without notice.
For more information, see [epic 11180](https://gitlab.com/groups/gitlab-org/-/epics/11180).
+{{< /alert >}}
+
To enable additional CI analytics features, [configure the ClickHouse integration](../../integration/clickhouse.md).
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
diff --git a/doc/ci/runners/runner_fleet_dashboard_groups.md b/doc/ci/runners/runner_fleet_dashboard_groups.md
index d7aee460ea40307f71829877aeea4e28c182942b..1c1af83c15c9b477bcbfa3c321a35d4583fe3c6c 100644
--- a/doc/ci/runners/runner_fleet_dashboard_groups.md
+++ b/doc/ci/runners/runner_fleet_dashboard_groups.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Runner fleet dashboard for groups
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151640) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `runners_dashboard_for_groups`. Disabled by default.
-> - Feature flag `runners_dashboard_for_groups` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/459052) in GitLab 17.2.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151640) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `runners_dashboard_for_groups`. Disabled by default.
+- Feature flag `runners_dashboard_for_groups` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/459052) in GitLab 17.2.
+
+{{< /history >}}
Users with at least the Maintainer role for a group can use the runner fleet dashboard to assess the health of group runners.
diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md
index 0cbc00eb939d4181afd820de88c8f8404c997d3a..ca7ec6f1321d250c571f9f6191610aaafe19c81f 100644
--- a/doc/ci/runners/runners_scope.md
+++ b/doc/ci/runners/runners_scope.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Manage runners
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab Runner has the following types of runners, which are available based on who you want to have access:
@@ -37,9 +40,13 @@ If you are using GitLab.com:
### Create an instance runner with a runner authentication token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383139) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_admin` [flag](../../administration/feature_flags.md)
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/389269) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383139) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_admin` [flag](../../administration/feature_flags.md)
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/389269) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed.
+
+{{< /history >}}
Prerequisites:
@@ -67,18 +74,24 @@ To create an instance runner:
You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner.
-NOTE:
+{{< alert type="note" >}}
+
The runner authentication token displays in the UI for a limited period of time during registration. After you register the runner,
the authentication token is stored in the `config.toml`.
+{{< /alert >}}
+
### Create an instance runner with a registration token (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
The option to pass a runner registration token and support for certain configuration arguments was
[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6. They are scheduled for removal
in GitLab 18.0. Use runner authentication tokens instead. For more information, see
[Migrating to the new runner registration workflow](new_creation_workflow.md).
+{{< /alert >}}
+
Prerequisites:
- Runner registration tokens must be [enabled](../../administration/settings/continuous_integration.md#allow-runner-registrations-tokens) in the **Admin** area.
@@ -104,8 +117,8 @@ You can pause a runner so that it does not accept jobs from groups and projects
1. Select **CI/CD > Runners**.
1. In the search box, enter the runner description or filter the runner list.
1. In the runner list, to the right of the runner:
- - To pause the runner, select **Pause** (**{pause}**).
- - To resume the runner, select **Resume** (**{play}**).
+ - To pause the runner, select **Pause** ({{< icon name="pause" >}}).
+ - To resume the runner, select **Resume** ({{< icon name="play" >}}).
### Delete instance runners
@@ -123,7 +136,7 @@ To delete a single or multiple instance runners:
1. Select **CI/CD > Runners**.
1. In the search box, enter the runner description or filter the list of runners.
1. Delete the instance runner:
- - To delete a single runner, next to the runner, select **Delete runner** (**{remove}**).
+ - To delete a single runner, next to the runner, select **Delete runner** ({{< icon name="remove" >}}).
- To delete multiple instance runners, select the checkbox for each runner and select **Delete selected**.
- To delete all runners, select the checkbox at the top of the runner list and select **Delete selected**.
1. Select **Permanently delete runner**.
@@ -232,9 +245,13 @@ Group runners process jobs by using a first in, first out queue.
### Create a group runner with a runner authentication token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383143) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_namespace` [flag](../../administration/feature_flags.md). Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/393919) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383143) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_namespace` [flag](../../administration/feature_flags.md). Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/393919) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed.
+
+{{< /history >}}
Prerequisites:
@@ -266,19 +283,29 @@ To create a group runner:
You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner.
-NOTE:
+{{< alert type="note" >}}
+
The runner authentication token displays in the UI for only a short period of time during registration.
+{{< /alert >}}
+
### Create a group runner with a registration token (deprecated)
-> - Path changed from **Settings > CI/CD > Runners**.
+{{< history >}}
+
+- Path changed from **Settings > CI/CD > Runners**.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
The option to pass a runner registration token and support for certain configuration arguments was
[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6. They are scheduled for removal
in GitLab 18.0. Use runner authentication tokens instead. For more information, see
[Migrating to the new runner registration workflow](new_creation_workflow.md).
+{{< /alert >}}
+
Prerequisites:
- Runner registration tokens must be [enabled](#enable-use-of-runner-registration-tokens-in-projects-and-groups) in the top-level group.
@@ -298,7 +325,11 @@ how to [register a runner](https://docs.gitlab.com/runner/register/#register-wit
### View group runners
-> - Ability for users with the Maintainer role to view group runners [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384179) in GitLab 16.4.
+{{< history >}}
+
+- Ability for users with the Maintainer role to view group runners [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384179) in GitLab 16.4.
+
+{{< /history >}}
Prerequisites:
@@ -312,8 +343,12 @@ You can do this for GitLab Self-Managed or for GitLab.com.
#### Filter group runners to show only inherited
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337838/) in GitLab 15.5.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101099) in GitLab 15.5. Feature flag `runners_finder_all_available` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337838/) in GitLab 15.5.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101099) in GitLab 15.5. Feature flag `runners_finder_all_available` removed.
+
+{{< /history >}}
You can choose to show all runners in the list, or show only
those that are inherited from the instance or other groups.
@@ -340,12 +375,16 @@ instance. If you pause a group runner that is used by multiple projects, the run
1. Select **Build > Runners**.
1. In the search box, enter the runner description or filter the runner list.
1. In the runner list, to the right of the runner:
- - To pause the runner, select **Pause** (**{pause}**).
- - To resume the runner, select **Resume** (**{play}**).
+ - To pause the runner, select **Pause** ({{< icon name="pause" >}}).
+ - To resume the runner, select **Resume** ({{< icon name="play" >}}).
### Delete a group runner
-> - Multiple runner deletion [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361721/) in GitLab 15.6.
+{{< history >}}
+
+- Multiple runner deletion [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361721/) in GitLab 15.6.
+
+{{< /history >}}
Prerequisites:
@@ -361,18 +400,25 @@ To delete a single or multiple group runners:
1. Select **Build > Runners**.
1. In the search box, enter the runner description or filter the list of runners.
1. Delete the group runner:
- - To delete a single runner, next to the runner, select **Delete runner** (**{remove}**).
+ - To delete a single runner, next to the runner, select **Delete runner** ({{< icon name="remove" >}}).
- To delete multiple instance runners, select the checkbox for each runner and select **Delete selected**.
- To delete all runners, select the checkbox at the top of the runner list and select **Delete selected**.
1. Select **Permanently delete runner**.
### Clean up stale group runners
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363012) in GitLab 15.1.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363012) in GitLab 15.1.
+
+{{< /history >}}
Prerequisites:
@@ -429,10 +475,13 @@ must be enabled for each project explicitly.
Project runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue.
-NOTE:
+{{< alert type="note" >}}
+
Project runners do not get instance with forked projects automatically.
A fork *does* copy the CI/CD settings of the cloned repository.
+{{< /alert >}}
+
### Project runner ownership
When a runner first connects to a project, that project becomes the runner's owner.
@@ -447,9 +496,13 @@ You cannot unassign a runner from the owner project. Delete the runner instead.
### Create a project runner with a runner authentication token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383143) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_namespace` [flag](../../administration/feature_flags.md). Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/393919) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383143) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_namespace` [flag](../../administration/feature_flags.md). Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/393919) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed.
+
+{{< /history >}}
Prerequisites:
@@ -483,17 +536,23 @@ To create a project runner:
You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner.
-NOTE:
+{{< alert type="note" >}}
+
The runner authentication token displays in the UI for only a short period of time during registration.
+{{< /alert >}}
+
### Create a project runner with a registration token (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
The option to pass a runner registration token and support for certain configuration arguments was
[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6. They are scheduled for removal
in GitLab 18.0. Use runner authentication tokens instead. For more information, see
[Migrating to the new runner registration workflow](new_creation_workflow.md).
+{{< /alert >}}
+
Prerequisites:
- Runner registration tokens must be [enabled](#enable-use-of-runner-registration-tokens-in-projects-and-groups) in the top-level group.
@@ -526,8 +585,8 @@ in the GitLab instance.
1. Expand **Runners**.
1. In the **Assigned project runners** section, find the runner.
1. To the right of the runner:
- - To pause the runner, select **Pause** (**{pause}**), then select **Pause**.
- - To resume the runner, select **Resume** (**{play}**).
+ - To pause the runner, select **Pause** ({{< icon name="pause" >}}), then select **Pause**.
+ - To resume the runner, select **Resume** ({{< icon name="play" >}}).
### Delete a project runner
@@ -591,7 +650,7 @@ To lock or unlock a project runner:
1. Select **Settings > CI/CD**.
1. Expand **Runners**.
1. Find the project runner you want to lock or unlock. Make sure it's enabled. You cannot lock instance or group runners.
-1. Select **Edit** (**{pencil}**).
+1. Select **Edit** ({{< icon name="pencil" >}}).
1. Select the **Lock to current projects** checkbox.
1. Select **Save changes**.
@@ -613,11 +672,18 @@ If a runner contacts the GitLab instance, the connection is recreated.
## View statistics for runner performance
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377963) in GitLab 15.8.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377963) in GitLab 15.8.
+
+{{< /history >}}
As an administrator, you can view runner statistics to learn about the performance of your runner fleet.
@@ -637,11 +703,18 @@ To view runner statistics:
## Determine which runners need to be upgraded
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365078) in GitLab 15.3.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365078) in GitLab 15.3.
+
+{{< /history >}}
The version of GitLab Runner used by your runners should be
[kept up-to-date](https://docs.gitlab.com/runner/#gitlab-runner-versions).
@@ -700,14 +773,21 @@ project.
## Enable use of runner registration tokens in projects and groups
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148557) in GitLab 16.11
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148557) in GitLab 16.11
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
The option to pass a runner registration token and support for certain configuration arguments was
[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6. They are scheduled for removal
in GitLab 18.0. Use runner authentication tokens instead. For more information, see
[Migrating to the new runner registration workflow](new_creation_workflow.md).
+{{< /alert >}}
+
In GitLab 17.0, the use of runner registration tokens is disabled in all GitLab instances.
Prerequisites:
diff --git a/doc/ci/secrets/_index.md b/doc/ci/secrets/_index.md
index 1745a433ae63e26a7a5f808e1ea8f745834f0ebb..619cb0e685858c6a3c59039300ff40f60b158d59 100644
--- a/doc/ci/secrets/_index.md
+++ b/doc/ci/secrets/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using external secrets in CI
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Secrets represent sensitive information your CI job needs to complete work. This
sensitive information can be items like API tokens, database credentials, or private keys.
@@ -47,17 +50,24 @@ is summarized by this diagram:
1. HashiCorp Vault returns the token.
1. Runner reads secrets from the HashiCorp Vault.
-NOTE:
+{{< alert type="note" >}}
+
Read the [Authenticating and Reading Secrets With HashiCorp Vault](hashicorp_vault.md)
tutorial for a version of this feature. It's available to all
subscription levels, supports writing secrets to and deleting secrets from Vault,
and supports multiple secrets engines.
+{{< /alert >}}
+
You must replace the `vault.example.com` URL below with the URL of your Vault server, and `gitlab.example.com` with the URL of your GitLab instance.
## Vault Secrets Engines
-> - `generic` option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366492) in GitLab Runner 16.11.
+{{< history >}}
+
+- `generic` option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366492) in GitLab Runner 16.11.
+
+{{< /history >}}
The Vault Secrets Engines supported by GitLab Runner are:
@@ -117,14 +127,20 @@ To configure your Vault server:
is required. HCP Vault uses the `admin` namespace as the root namespace by default.
For example, `VAULT_NAMESPACE=admin`.
- NOTE:
- Support for providing these values in the user interface [is tracked in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/218677).
+ {{< alert type="note" >}}
+
+Support for providing these values in the user interface [is tracked in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/218677).
+
+ {{< /alert >}}
## Use Vault secrets in a CI job
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
After [configuring your Vault server](#configure-your-vault-server), you can use
the secrets stored in Vault by defining them with the [`vault` keyword](../yaml/_index.md#secretsvault):
@@ -229,11 +245,14 @@ $ vault write auth/jwt/role/myproject-production - <<EOF
EOF
```
-WARNING:
+{{< alert type="warning" >}}
+
Always restrict your roles to a project or namespace by using one of the provided
claims like `project_id` or `namespace_id`. Without these restrictions, any JWT
generated by this GitLab instance may be allowed to authenticate using this role.
+{{< /alert >}}
+
For a full list of ID token JWT claims, read the
[How It Works](hashicorp_vault.md) section of the
[Authenticating and Reading Secrets With HashiCorp Vault](hashicorp_vault.md) tutorial.
diff --git a/doc/ci/secrets/akeyless.md b/doc/ci/secrets/akeyless.md
index abbf3e9f4e081e69301e545f5c0385c51696da0c..d6b62415155ad064c3e9efb22aa82dd4ed6f73b6 100644
--- a/doc/ci/secrets/akeyless.md
+++ b/doc/ci/secrets/akeyless.md
@@ -2,20 +2,29 @@
stage: Software Supply Chain Security
group: Pipeline Security
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
-ignore_in_report: true
title: Use Akeyless secrets in GitLab CI/CD
---
-DETAILS:
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164040) in GitLab 17.4.
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/164040) in GitLab 17.4.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
This feature is an [experiment](../../policy/development_stages_support.md)
and not intended for production use. There is no support available for this feature
and it is subject to removal at any time in accordance to GitLab policy.
+{{< /alert >}}
+
You can use the `secrets:akeyless` keyword to authenticate and retrieve Akeyless secrets.
Prerequisites:
diff --git a/doc/ci/secrets/azure_key_vault.md b/doc/ci/secrets/azure_key_vault.md
index 40d9a098b034a2560c2069b4e17ec8aabfdc6c6f..03ea1e3b108999345685de746de804f221cb0832 100644
--- a/doc/ci/secrets/azure_key_vault.md
+++ b/doc/ci/secrets/azure_key_vault.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Azure Key Vault secrets in GitLab CI/CD
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab and GitLab Runner 16.3. Due to [issue 424746](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) this feature did not work as expected.
-> - [Issue 424746](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) resolved and this feature made generally available in GitLab Runner 16.6.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab and GitLab Runner 16.3. Due to [issue 424746](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) this feature did not work as expected.
+- [Issue 424746](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) resolved and this feature made generally available in GitLab Runner 16.6.
+
+{{< /history >}}
You can use secrets stored in the [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault/)
in your GitLab CI/CD pipelines.
diff --git a/doc/ci/secrets/convert-to-id-tokens.md b/doc/ci/secrets/convert-to-id-tokens.md
index bc80936727f6067b5b260b2fc78003468166bdef..424ce20bcfb7e11d36bdb7e6e6c356d5f3797d0d 100644
--- a/doc/ci/secrets/convert-to-id-tokens.md
+++ b/doc/ci/secrets/convert-to-id-tokens.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Update HashiCorp Vault configuration to use ID Tokens'
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
Starting in Vault 1.17, [JWT auth login requires bound audiences on the role](https://developer.hashicorp.com/vault/docs/upgrading/upgrade-to-1.17.x#jwt-auth-login-requires-bound-audiences-on-the-role)
when the JWT contains an `aud` claim. The `aud` claim can be a single string or a list of strings.
+{{< /alert >}}
+
This tutorial demonstrates how to convert your existing CI/CD secrets configuration to use [ID Tokens](../secrets/id_token_authentication.md).
The `CI_JOB_JWT` variables are deprecated, but updating to ID tokens requires some
diff --git a/doc/ci/secrets/fortanix_dsm_integration.md b/doc/ci/secrets/fortanix_dsm_integration.md
index 7c64c239bd181b709530b52b02ddb18a23215e57..3a6df5a3383c05a448dd88efb3301d9132405ea3 100644
--- a/doc/ci/secrets/fortanix_dsm_integration.md
+++ b/doc/ci/secrets/fortanix_dsm_integration.md
@@ -1,14 +1,17 @@
---
+type: concepts, howto
stage: Software Supply Chain Security
group: Pipeline Security
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
-type: concepts, howto
title: 'Tutorial: Use Fortanix Data Security Manager (DSM) with GitLab'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use Fortanix Data Security Manager (DSM) as your secrets manager for GitLab CI/CD pipelines.
diff --git a/doc/ci/secrets/gcp_secret_manager.md b/doc/ci/secrets/gcp_secret_manager.md
index 9c942a1684121a9906aeda3a795e34ae8e9bc96a..ceb4184daca4121c2e46a5fb28e494fda1cf3e17 100644
--- a/doc/ci/secrets/gcp_secret_manager.md
+++ b/doc/ci/secrets/gcp_secret_manager.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use GCP Secret Manager secrets in GitLab CI/CD
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11739) in GitLab and GitLab Runner 16.8.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11739) in GitLab and GitLab Runner 16.8.
+
+{{< /history >}}
You can use secrets stored in the [Google Cloud (GCP) Secret Manager](https://cloud.google.com/security/products/secret-manager)
in your GitLab CI/CD pipelines.
@@ -102,7 +109,11 @@ job_using_gcp_sm:
### Use secrets from a different GCP project
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/37487) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/37487) in GitLab 17.0.
+
+{{< /history >}}
Secret names in GCP are per-project. By default the secret named in `gcp_secret_manager:name`
is read from the project specified in `GCP_PROJECT_NUMBER`.
diff --git a/doc/ci/secrets/hashicorp_vault.md b/doc/ci/secrets/hashicorp_vault.md
index 65d7af073f509e5b83b2bac69f913db5eedfabf6..e6f57720a0c772e717b9b517a6e64911e990ee5f 100644
--- a/doc/ci/secrets/hashicorp_vault.md
+++ b/doc/ci/secrets/hashicorp_vault.md
@@ -5,19 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use HashiCorp Vault secrets in GitLab CI/CD
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
Authenticating with `CI_JOB_JWT` was [deprecated in GitLab 15.9 and removed in GitLab 17.0](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated).
Use [ID tokens to authenticate with HashiCorp Vault](hashicorp_vault.md#example)
instead, as demonstrated on this page.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Starting in Vault 1.17, [JWT auth login requires bound audiences on the role](https://developer.hashicorp.com/vault/docs/upgrading/upgrade-to-1.17.x#jwt-auth-login-requires-bound-audiences-on-the-role)
when the JWT contains an `aud` claim. The `aud` claim can be a single string or a list of strings.
+{{< /alert >}}
+
This tutorial demonstrates how to authenticate, configure, and read secrets with HashiCorp's Vault from GitLab CI/CD.
## Prerequisites
@@ -30,10 +39,13 @@ To follow along, you must have:
- Access to a running Vault server (at least v1.2.0) to configure authentication and to create roles and policies.
For HashiCorp Vaults, this can be the Open Source or Enterprise version.
-NOTE:
+{{< alert type="note" >}}
+
You must replace the `vault.example.com` URL below with the URL of your Vault server,
and `gitlab.example.com` with the URL of your GitLab instance.
+{{< /alert >}}
+
## How it works
ID tokens are JSON Web Tokens (JWTs) used for OIDC authentication with third-party services.
@@ -118,9 +130,12 @@ To communicate with Vault, you can use either its CLI client or perform API requ
## Example
-WARNING:
+{{< alert type="warning" >}}
+
JWTs are credentials, which can grant access to resources. Be careful where you paste them!
+{{< /alert >}}
+
Let's say you have the passwords for your staging and production databases stored in a Vault server
that is running on `http://vault.example.com:8200`. Your staging password is `pa$$w0rd`
and your production password is `real-pa$$w0rd`.
@@ -277,11 +292,14 @@ configuration:
For the full list of options, see Vault's [Create Role documentation](https://developer.hashicorp.com/vault/api-docs/auth/jwt#create-role).
-WARNING:
+{{< alert type="warning" >}}
+
Always restrict your roles to project or namespace by using one of the provided claims
(for example, `project_id` or `namespace_id`). Otherwise any JWT generated by this instance
may be allowed to authenticate using this role.
+{{< /alert >}}
+
Now, configure the JWT Authentication method:
```shell
diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md
index 00c798126b9c3af4fd9b59f315095685a9671c06..32e002e11333c2317c754be421ee7ee9b6015037 100644
--- a/doc/ci/secrets/id_token_authentication.md
+++ b/doc/ci/secrets/id_token_authentication.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: OpenID Connect (OIDC) Authentication Using ID Tokens
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7.
+
+{{< /history >}}
You can authenticate with third party services using GitLab CI/CD's
[ID tokens](../yaml/_index.md#id_tokens).
diff --git a/doc/ci/secure_files/_index.md b/doc/ci/secure_files/_index.md
index b4d8eeefe68e1385b6154e3a5005bc09945084d8..e0ab7cd9faac98ccf4b1ec0acecd9bbac1e15049 100644
--- a/doc/ci/secure_files/_index.md
+++ b/doc/ci/secure_files/_index.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project-level Secure Files
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) and feature flag `ci_secure_files` removed in GitLab 15.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350748) and feature flag `ci_secure_files` removed in GitLab 15.7.
+
+{{< /history >}}
This feature is part of [Mobile DevOps](../mobile_devops/_index.md) developed by [GitLab Incubation Engineering](https://handbook.gitlab.com/handbook/engineering/development/incubation/).
The feature is still in development, but you can:
@@ -58,11 +65,14 @@ test:
- curl --silent "https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files/-/raw/main/installer" | bash
```
-WARNING:
+{{< alert type="warning" >}}
+
The content of files loaded with the `download-secure-files` tool are not [masked](../variables/_index.md#mask-a-cicd-variable)
in the job log output. Make sure to avoid outputting secure file contents in the job log,
especially when logging output that could contain sensitive information.
+{{< /alert >}}
+
## Security details
Project-level Secure Files are encrypted on upload using the [Lockbox](https://github.com/ankane/lockbox)
diff --git a/doc/ci/services/_index.md b/doc/ci/services/_index.md
index 96745e929f3ccbe4027258847464cb31492aef17..0ec866c9eec388ccb90f887d6637d6f4b19777c1 100644
--- a/doc/ci/services/_index.md
+++ b/doc/ci/services/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Services
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you configure CI/CD, you specify an image, which is used to create the container
where your jobs run. To specify this image, you use the `image` keyword.
@@ -264,7 +267,11 @@ test:
## Available settings for `services`
-> - Introduced in GitLab and GitLab Runner 9.4.
+{{< history >}}
+
+- Introduced in GitLab and GitLab Runner 9.4.
+
+{{< /history >}}
| Setting | Required | GitLab version | Description |
|-----------------------------------|--------------------------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -282,7 +289,11 @@ test:
## Starting multiple services from the same image
-> - Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](../docker/using_docker_images.md#extended-docker-configuration-options).
+{{< history >}}
+
+- Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](../docker/using_docker_images.md#extended-docker-configuration-options).
+
+{{< /history >}}
Before the new extended Docker configuration options, the following configuration
would not work properly:
@@ -315,7 +326,11 @@ in `.gitlab-ci.yml` file.
## Setting a command for the service
-> - Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](../docker/using_docker_images.md#extended-docker-configuration-options).
+{{< history >}}
+
+- Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](../docker/using_docker_images.md#extended-docker-configuration-options).
+
+{{< /history >}}
Let's assume you have a `super/sql:latest` image with some SQL database
in it. You would like to use it as a service for your job. Let's also
@@ -356,7 +371,11 @@ The syntax of `command` is similar to [Dockerfile `CMD`](https://docs.docker.com
## Using aliases as service container names for the Kubernetes executor
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421131) in GitLab and GitLab Runner 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421131) in GitLab and GitLab Runner 17.9.
+
+{{< /history >}}
You can use service aliases as service container names for the Kubernetes executor.
GitLab Runner names containers based on the following conditions:
@@ -518,7 +537,11 @@ time.
## Capturing service container logs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3680) in GitLab Runner 15.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3680) in GitLab Runner 15.6.
+
+{{< /history >}}
Logs generated by applications running in service containers can be captured for subsequent examination and debugging.
View service container logs when a service container starts successfully but causes job failures due to unexpected behavior.
@@ -546,16 +569,22 @@ Any other values result in an error message and effectively disable the feature.
When enabled, logs for all service containers are captured and streamed into the jobs trace log concurrently with
other logs. Logs from each container are prefixed with the container's aliases, and displayed in a different color.
-NOTE:
+{{< alert type="note" >}}
+
To diagnose job failures, you can adjust the logging level in your service container for which you want to capture logs.
The default logging level might not provide sufficient troubleshooting information.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
Enabling `CI_DEBUG_SERVICES` might reveal masked variables. When `CI_DEBUG_SERVICES` is enabled,
service container logs and the CI job's logs are streamed to the job's trace log concurrently. This means that the
service container logs might get inserted into a job's masked log. This would thwart the variable masking mechanism
and result in the masked variable being revealed.
+{{< /alert >}}
+
See [Mask a CI/CD Variable](../variables/_index.md#mask-a-cicd-variable)
## Debug a job locally
diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md
index 43a877df246a6f326940bb4ccc085d3bba5b73d3..ae82dac1d6fd4997022499269af1f87174b44b8e 100644
--- a/doc/ci/services/gitlab.md
+++ b/doc/ci/services/gitlab.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use GitLab as a microservice
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Many applications need to access JSON APIs, so application tests might need access
to APIs too. The following example shows how to use GitLab as a microservice to give
@@ -26,10 +29,13 @@ tests access to the GitLab API.
GITLAB_ROOT_PASSWORD: "password" # to access the api with user root:password
```
-NOTE:
+{{< alert type="note" >}}
+
Variables set in the GitLab UI are not passed down to the service containers.
For more information, see [GitLab CI/CD variables](../variables/_index.md).
+{{< /alert >}}
+
Then, commands in `script` sections in your `.gitlab-ci.yml` file can access the API at `http://gitlab/api/v4`.
For more information about why `gitlab` is used for the `Host`, see
diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md
index c29553221c4842493975ac717ca1cb93da70b13c..03448c304307764a9cd6991ea5c724ab449f2edc 100644
--- a/doc/ci/services/mysql.md
+++ b/doc/ci/services/mysql.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using MySQL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Many applications depend on MySQL as their database, and you may
need it for your tests to run.
@@ -18,10 +21,13 @@ If you want to use a MySQL container, you can use [GitLab Runner](../runners/_in
This example shows you how to set a username and password that GitLab uses to access the MySQL container. If you do not set a username and password, you must use `root`.
-NOTE:
+{{< alert type="note" >}}
+
Variables set in the GitLab UI are not passed down to the service containers.
For more information, see [GitLab CI/CD variables](../variables/_index.md).
+{{< /alert >}}
+
1. To specify a MySQL image, add the following to your `.gitlab-ci.yml` file:
```yaml
@@ -72,11 +78,14 @@ GitLab Runner with the Shell executor.
1. Choose a MySQL root password and type it twice when asked.
- NOTE:
- As a security measure, you can run `mysql_secure_installation` to
+ {{< alert type="note" >}}
+
+As a security measure, you can run `mysql_secure_installation` to
remove anonymous users, drop the test database, and disable remote logins by
the root user.
+ {{< /alert >}}
+
1. Create a user by logging in to MySQL as root:
```shell
diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md
index cef11817b32dbdcc83d5d58255a8c58334859c3c..8c1da0661939f5a452364bbeaaa7c0e14fa75a69 100644
--- a/doc/ci/services/postgres.md
+++ b/doc/ci/services/postgres.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using PostgreSQL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
As many applications depend on PostgreSQL as their database, you
eventually need it in order for your tests to run. Below you are guided how to
@@ -95,10 +98,13 @@ sudo -u postgres psql -d template1
Then create a user (in our case `runner`) which is used by your
application. Change `$password` in the command below to a real strong password.
-NOTE:
+{{< alert type="note" >}}
+
Be sure to not enter `template1=#` in the following commands, as that's part of
the PostgreSQL prompt.
+{{< /alert >}}
+
```shell
template1=# CREATE USER runner WITH PASSWORD '$password' CREATEDB;
```
diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md
index 6d32f599bca62d87f103f47f2a4b747c0f2d04db..02233fd89adb284580d9de5428877a33038fec7b 100644
--- a/doc/ci/services/redis.md
+++ b/doc/ci/services/redis.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using Redis
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
As many applications depend on Redis as their key-value store, you
eventually need it in order for your tests to run. Below you are guided how to
diff --git a/doc/ci/steps/_index.md b/doc/ci/steps/_index.md
index b80b2cdc69842a3663d5f92196d55bb97acbbb66..33a2f70ce702c4232d0cf616d06789cc881c0d25 100644
--- a/doc/ci/steps/_index.md
+++ b/doc/ci/steps/_index.md
@@ -5,10 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI/CD steps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
Steps are reusable units of a job that when composed together replace the `script` used in a GitLab CI/CD job.
While you are not required to use steps, the reusability, composability, testability, and independence
@@ -450,10 +453,13 @@ exec:
- "echo ${PWD}"
```
-NOTE:
+{{< alert type="note" >}}
+
Any dependency required by the executing step should also be installed by the step.
For example, if a step calls `go`, it should first install it.
+{{< /alert >}}
+
##### Return an output
Executable steps return an output by adding a line to the `${{output_file}}` in JSON Line format.
diff --git a/doc/ci/test_cases/_index.md b/doc/ci/test_cases/_index.md
index 1bb7bd208e77af9527ca48fbff1f0ac256a781cb..757528c792c68d0d61ce5351893bc66ebe2c7e08 100644
--- a/doc/ci/test_cases/_index.md
+++ b/doc/ci/test_cases/_index.md
@@ -6,9 +6,12 @@ description: Test cases in GitLab can help your teams create testing scenarios i
title: Test cases
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Test cases in GitLab can help your teams create testing scenarios in their existing development platform.
@@ -21,15 +24,22 @@ while integrating with your development workflows, see
[Streamline Software Development: Integrating Requirements, Testing, and Development Workflows](https://www.youtube.com/watch?v=wbfWM4y2VmM).
<!-- Video published on 2024-02-21 -->
-NOTE:
+{{< alert type="note" >}}
+
[Requirements](../../user/project/requirements/_index.md) and test cases are being
[migrated to work items](https://gitlab.com/groups/gitlab-org/-/epics/5171).
[Issue 323790](https://gitlab.com/gitlab-org/gitlab/-/issues/323790) proposes to link requirements to test cases.
For more information, see [Product Stage Direction - Plan](https://about.gitlab.com/direction/plan/).
+{{< /alert >}}
+
## Create a test case
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -64,7 +74,11 @@ To view a test case:
## Edit a test case
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can edit a test case's title and description.
@@ -77,14 +91,18 @@ Prerequisites:
To edit a test case:
1. [View a test case](#view-a-test-case).
-1. Select **Edit title and description** (**{pencil}**).
+1. Select **Edit title and description** ({{< icon name="pencil" >}}).
1. Edit the test case's title or description.
1. Select **Save changes**.
## Make a test case confidential
-> - Introduced for [new](https://gitlab.com/gitlab-org/gitlab/-/issues/422121) and [existing](https://gitlab.com/gitlab-org/gitlab/-/issues/422120) test cases in GitLab 16.5.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Introduced for [new](https://gitlab.com/gitlab-org/gitlab/-/issues/422121) and [existing](https://gitlab.com/gitlab-org/gitlab/-/issues/422120) test cases in GitLab 16.5.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
If you're working on a test case that contains private information, you can make it confidential.
@@ -102,7 +120,11 @@ or editing an existing one.
## Archive a test case
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
When you want to stop using a test case, you can archive it. You can [reopen an archived test case](#reopen-an-archived-test-case) later.
@@ -120,7 +142,11 @@ To view archived test cases:
## Reopen an archived test case
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
If you decide to start using an archived test case again, you can reopen it.
diff --git a/doc/ci/testing/_index.md b/doc/ci/testing/_index.md
index 2c9cd80b75adff62b43c49df34c542c7fa28bf10..a71f6b027de7153f0a0c1f2e186f51e333302961 100644
--- a/doc/ci/testing/_index.md
+++ b/doc/ci/testing/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Test with GitLab CI/CD and generate reports in merge requests
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use GitLab CI/CD to test the changes included in a feature branch. You can also
display reports or link to important information directly from [merge requests](../../user/project/merge_requests/_index.md).
@@ -27,9 +30,12 @@ display reports or link to important information directly from [merge requests](
## Security Reports
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In addition to the reports listed above, GitLab can do many types of [Security reports](../../user/application_security/_index.md),
generated by scanning and reporting any vulnerabilities found in your project:
diff --git a/doc/ci/testing/accessibility_testing.md b/doc/ci/testing/accessibility_testing.md
index 76ed3757648a8012cf06662ce5e9f3fdf5641a1a..7bfb624697046374f5efb3164b1d0fb8469c8b9c 100644
--- a/doc/ci/testing/accessibility_testing.md
+++ b/doc/ci/testing/accessibility_testing.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Accessibility testing
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If your application offers a web interface, you can use
[GitLab CI/CD](../_index.md) to determine the accessibility
@@ -61,8 +64,11 @@ The `a11y` job in your CI/CD pipeline generates these files:
You can [view job artifacts in your browser](../jobs/job_artifacts.md#download-job-artifacts).
-NOTE:
+{{< alert type="note" >}}
+
The job definition provided by the template does not support Kubernetes.
+{{< /alert >}}
+
You cannot pass configurations into Pa11y via CI configuration.
To change the configuration, edit a copy of the template in your CI file.
diff --git a/doc/ci/testing/browser_performance_testing.md b/doc/ci/testing/browser_performance_testing.md
index 9009fca7b567a4d61a518d764e763ec20cd07073..6fd999563b0b1b067c291a752a5d93fed968ab10 100644
--- a/doc/ci/testing/browser_performance_testing.md
+++ b/doc/ci/testing/browser_performance_testing.md
@@ -5,17 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Browser Performance Testing
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If your application offers a web interface and you're using
[GitLab CI/CD](../_index.md), you can quickly determine the rendering performance
impact of pending code changes in the browser.
-NOTE:
+{{< alert type="note" >}}
+
You can automate this feature in your applications by using [Auto DevOps](../../topics/autodevops/_index.md).
+{{< /alert >}}
+
## Overview
GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source
@@ -47,7 +53,8 @@ between the source and target branches, and shows the information in the merge r
For an example Browser Performance job, see
[Configuring Browser Performance Testing](#configuring-browser-performance-testing).
-NOTE:
+{{< alert type="note" >}}
+
If the Browser Performance report has no data to compare, such as when you add the
Browser Performance job in your `.gitlab-ci.yml` for the very first time,
the Browser Performance report widget doesn't display. It must have run at least
@@ -55,11 +62,17 @@ once on the target branch (`main`, for example), before it displays in a
merge request targeting that branch. Additionally, the widget only displays if the
job ran in the latest pipeline for the Merge request.
+{{< /alert >}}
+
## Configuring Browser Performance Testing
-> - Support for the `SITESPEED_DOCKER_OPTIONS` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134024) in GitLab 16.6.
+{{< history >}}
+
+- Support for the `SITESPEED_DOCKER_OPTIONS` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134024) in GitLab 16.6.
+
+{{< /history >}}
This example shows how to run the [sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/)
on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io)
diff --git a/doc/ci/testing/code_coverage/_index.md b/doc/ci/testing/code_coverage/_index.md
index c829731d1349a0c19038dd917bc5ea216a7bed11..fa1a0eec0c3234f1ed38eadc94e12e1412585ce3 100644
--- a/doc/ci/testing/code_coverage/_index.md
+++ b/doc/ci/testing/code_coverage/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Code coverage
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Configure code coverage to track and visualize how much of your source code is covered by tests. You can:
@@ -56,30 +59,36 @@ Test the regex patterns carefully. Tool output formats can change over time, and
<!-- markdownlint-disable MD056 -->
<!-- Verify regex patterns on docs.gitlab.com as escape characters render differently than in `.md` files rendered via GitLab code browser -->
-::Tabs
+{{< tabs >}}
-:::TabTitle Python and Ruby
+{{< tab title="Python and Ruby" >}}
| Tool | Language | Command | Regex pattern |
|------------|----------|----------------|---------------|
| pytest-cov | Python | `pytest --cov` | `/TOTAL.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/` |
| Simplecov | Ruby | `rspec spec` | `/\(\d+.\d+\%\) covered/` |
-:::TabTitle C/C++ and Rust
+{{< /tab >}}
+
+{{< tab title="C/C++ and Rust" >}}
| Tool | Language | Command | Regex pattern |
|-----------|----------|-------------------|---------------|
| gcovr | C/C++ | `gcovr` | `/^TOTAL.*\s+(\d+\%)$/` |
| tarpaulin | Rust | `cargo tarpaulin` | `/^\d+.\d+% coverage/` |
-:::TabTitle Java and JVM
+{{< /tab >}}
+
+{{< tab title="Java and JVM" >}}
| Tool | Language | Command | Regex pattern |
|-----------|-------------|------------------------------------|---------------|
| JaCoCo | Java/Kotlin | `./gradlew test jacocoTestReport` | `/Total.*?([0-9]{1,3})%/` |
| Scoverage | Scala | `sbt coverage test coverageReport` | `/(?i)total.*? (100(?:\.0+)?\%\|[1-9]?\d(?:\.\d+)?\%)$/` |
-:::TabTitle Node.js
+{{< /tab >}}
+
+{{< tab title="Node.js" >}}
| Tool | Command | Regex pattern |
|------|--------------------------------------|---------------|
@@ -87,21 +96,27 @@ Test the regex patterns carefully. Tool output formats can change over time, and
| nyc | `nyc npm test` | `/All files[^\|]*\|[^\|]*\s+([\d\.]+)/` |
| jest | `jest --ci --coverage` | `/All files[^\|]*\|[^\|]*\s+([\d\.]+)/` |
-:::TabTitle PHP
+{{< /tab >}}
+
+{{< tab title="PHP" >}}
| Tool | Command | Regex pattern |
|---------|------------------------------------------|---------------|
| pest | `pest --coverage --colors=never` | `/Statement coverage[A-Za-z\.*]\s*:\s*([^%]+)/` |
| phpunit | `phpunit --coverage-text --colors=never` | `/^\s*Lines:\s*\d+.\d+\%/` |
-:::TabTitle Go
+{{< /tab >}}
+
+{{< tab title="Go" >}}
| Tool | Command | Regex pattern |
|-------------------|------------------|---------------|
| go test (single) | `go test -cover` | `/coverage: \d+.\d+% of statements/` |
| go test (project) | `go test -coverprofile=cover.profile && go tool cover -func cover.profile` | `/total:\s+\(statements\)\s+\d+.\d+%/` |
-:::TabTitle .NET and PowerShell
+{{< /tab >}}
+
+{{< tab title=".NET and PowerShell" >}}
| Tool | Language | Command | Regex pattern |
|-----------|------------|---------|---------------|
@@ -109,14 +124,18 @@ Test the regex patterns carefully. Tool output formats can change over time, and
| dotnet test ([MSBuild](https://github.com/coverlet-coverage/coverlet/blob/master/Documentation/MSBuildIntegration.md)) | .NET | `dotnet test` | `/Total\s*\|*\s(\d+(?:\.\d+)?)/` |
| Pester | PowerShell | None | `/Covered (\d+\.\d+%)/` |
-:::TabTitle Elixir
+{{< /tab >}}
+
+{{< tab title="Elixir" >}}
| Tool | Command | Regex pattern |
|-------------|--------------------|---------------|
| excoveralls | None | `/\[TOTAL\]\s+(\d+\.\d+)%/` |
| mix | `mix test --cover` | `/\d+.\d+\%\s+\|\s+Total/` |
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
<!-- vale gitlab_base.Spelling = YES -->
<!-- markdownlint-enable MD056 -->
@@ -167,8 +186,12 @@ For language-specific configuration details see:
### Coverage reports from child pipelines
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363301) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_child_pipeline_coverage_reports`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363557) and feature flag `ci_child_pipeline_coverage_reports` removed in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363301) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_child_pipeline_coverage_reports`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363557) and feature flag `ci_child_pipeline_coverage_reports` removed in GitLab 15.2.
+
+{{< /history >}}
Coverage reports generated in child pipelines are included in the parent pipeline's coverage report. For example:
@@ -181,8 +204,11 @@ child_test_pipeline:
## Add a coverage check approval rule
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
You can require specific users or a group to approve merge requests that reduce the project's test coverage.
@@ -227,8 +253,11 @@ To view the code coverage history for a project:
### For a group
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
To view the code coverage history for all projects in a group:
diff --git a/doc/ci/testing/code_coverage/cobertura.md b/doc/ci/testing/code_coverage/cobertura.md
index c9c5ab9cad9125ea31c4cffb14e943f6579dcec6..6b804cabec6fcd953c231b837d0b33c48f8abd98 100644
--- a/doc/ci/testing/code_coverage/cobertura.md
+++ b/doc/ci/testing/code_coverage/cobertura.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Cobertura coverage report
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
For the coverage analysis to work, you have to provide a properly formatted
[Cobertura XML](https://cobertura.github.io/cobertura/) report to
@@ -128,11 +131,14 @@ Automatic class path correction also works for a Java project with:
<class name="com.gitlab.security_products.tests.App" filename="com/gitlab/security_products/tests/App.java" line-rate="0.0" branch-rate="0.0" complexity="6.0">
```
-NOTE:
+{{< alert type="note" >}}
+
Automatic class path correction only works on `source` paths in the format `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`.
The `source` is ignored if the path does not follow this pattern. The parser assumes that the
`filename` of a `class` element contains the full path relative to the project root.
+{{< /alert >}}
+
## Example test coverage configurations
This section provides test coverage configuration examples for different programming languages. You can also see a working example in
diff --git a/doc/ci/testing/code_coverage/jacoco.md b/doc/ci/testing/code_coverage/jacoco.md
index 8d0e862e87d381aee7f858185053b7d73577d7e3..a66050c6fdb43c384aa6e92f780e0afd2a6a189e 100644
--- a/doc/ci/testing/code_coverage/jacoco.md
+++ b/doc/ci/testing/code_coverage/jacoco.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: JaCoCo coverage report
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227345) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `jacoco_coverage_reports`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170513) in GitLab 17.6. Feature flag `jacoco_coverage_reports` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227345) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `jacoco_coverage_reports`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170513) in GitLab 17.6. Feature flag `jacoco_coverage_reports` removed.
+
+{{< /history >}}
[Leave your feedback](https://gitlab.com/gitlab-org/gitlab/-/issues/479804)
diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md
index 248d0f5464316b7a88f2f4b32482792a2eb15428..454e5e7fbc5afaacd783aabeb70de7af0116e900 100644
--- a/doc/ci/testing/code_quality.md
+++ b/doc/ci/testing/code_quality.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Code Quality
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Code Quality helps code authors find and fix problems faster, and frees up time for code reviewers to focus their attention on more nuanced suggestions or comments.
@@ -20,12 +23,12 @@ as shown in the following table:
| Feature | In Free | In Premium | In Ultimate |
|:--------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|
-| [Import Code Quality results from CI/CD jobs](#import-code-quality-results-from-a-cicd-job) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [Use CodeClimate-based scanning](#use-the-built-in-code-quality-cicd-template-deprecated) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [See findings in a merge request widget](#merge-request-widget) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [See findings in a pipeline report](#pipeline-details-view) | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes |
-| [See findings in the merge request changes view](#merge-request-changes-view) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Analyze overall health in a project quality summary view](#project-quality-view) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
+| [Import Code Quality results from CI/CD jobs](#import-code-quality-results-from-a-cicd-job) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [Use CodeClimate-based scanning](#use-the-built-in-code-quality-cicd-template-deprecated) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [See findings in a merge request widget](#merge-request-widget) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [See findings in a pipeline report](#pipeline-details-view) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [See findings in the merge request changes view](#merge-request-changes-view) | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Analyze overall health in a project quality summary view](#project-quality-view) | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
## Scan code for quality violations
@@ -59,10 +62,13 @@ Now, after the pipeline runs, the quality tool's results are [processed and disp
### Use the built-in Code Quality CI/CD template (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](../../update/deprecations.md#codeclimate-based-code-quality-scanning-will-be-removed) in GitLab 17.3 and is planned for removal in 18.0.
[Integrate the results from a supported tool directly](#import-code-quality-results-from-a-cicd-job) instead.
+{{< /alert >}}
+
Code Quality also includes a built-in CI/CD template, `Code-Quality.gitlab-ci.yaml`.
This template runs a scan based on the open source CodeClimate scanning engine.
@@ -81,17 +87,17 @@ The following integrations are available to replace the built-in plugins:
| Plugin | On by default | Replacement |
|--------------|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Duplication | **{check-circle}** Yes | [Integrate PMD Copy/Paste Detector](#pmd-copypaste-detector). |
-| ESLint | **{check-circle}** Yes | [Integrate ESLint](#eslint). |
-| gofmt | **{dotted-circle}** No | [Integrate golangci-lint](#golangci-lint) and enable the [gofmt linter](https://golangci-lint.run/usage/linters#gofmt). |
-| golint | **{dotted-circle}** No | [Integrate golangci-lint](#golangci-lint) and enable one of the included linters that replaces golint. golint is [deprecated and frozen](https://github.com/golang/go/issues/38968). |
-| govet | **{dotted-circle}** No | [Integrate golangci-lint](#golangci-lint). golangci-lint [includes govet by default](https://golangci-lint.run/usage/linters#enabled-by-default). |
-| markdownlint | **{dotted-circle}** No (community-supported) | [Integrate markdownlint-cli2](#markdownlint-cli2). |
-| pep8 | **{dotted-circle}** No | Integrate an alternative Python linter like [Flake8](#flake8), [Pylint](#pylint), or [Ruff](#ruff). |
-| RuboCop | **{dotted-circle}** Yes | [Integrate RuboCop](#rubocop). |
-| SonarPython | **{dotted-circle}** No | Integrate an alternative Python linter like [Flake8](#flake8), [Pylint](#pylint), or [Ruff](#ruff). |
-| Stylelint | **{dotted-circle}** No (community-supported) | [Integrate Stylelint](#stylelint). |
-| SwiftLint | **{dotted-circle}** No | [Integrate SwiftLint](#swiftlint). |
+| Duplication | {{< icon name="check-circle" >}} Yes | [Integrate PMD Copy/Paste Detector](#pmd-copypaste-detector). |
+| ESLint | {{< icon name="check-circle" >}} Yes | [Integrate ESLint](#eslint). |
+| gofmt | {{< icon name="dotted-circle" >}} No | [Integrate golangci-lint](#golangci-lint) and enable the [gofmt linter](https://golangci-lint.run/usage/linters#gofmt). |
+| golint | {{< icon name="dotted-circle" >}} No | [Integrate golangci-lint](#golangci-lint) and enable one of the included linters that replaces golint. golint is [deprecated and frozen](https://github.com/golang/go/issues/38968). |
+| govet | {{< icon name="dotted-circle" >}} No | [Integrate golangci-lint](#golangci-lint). golangci-lint [includes govet by default](https://golangci-lint.run/usage/linters#enabled-by-default). |
+| markdownlint | {{< icon name="dotted-circle" >}} No (community-supported) | [Integrate markdownlint-cli2](#markdownlint-cli2). |
+| pep8 | {{< icon name="dotted-circle" >}} No | Integrate an alternative Python linter like [Flake8](#flake8), [Pylint](#pylint), or [Ruff](#ruff). |
+| RuboCop | {{< icon name="dotted-circle" >}} Yes | [Integrate RuboCop](#rubocop). |
+| SonarPython | {{< icon name="dotted-circle" >}} No | Integrate an alternative Python linter like [Flake8](#flake8), [Pylint](#pylint), or [Ruff](#ruff). |
+| Stylelint | {{< icon name="dotted-circle" >}} No (community-supported) | [Integrate Stylelint](#stylelint). |
+| SwiftLint | {{< icon name="dotted-circle" >}} No | [Integrate SwiftLint](#swiftlint). |
## View Code Quality results
@@ -114,9 +120,12 @@ full report available in the **Pipeline** details view.
### Merge request changes view
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Code Quality results display in the merge request **Changes** view. Lines containing Code Quality
issues are marked by a symbol beside the gutter. Select the symbol to see the list of issues, then select an issue to see its details.
@@ -125,9 +134,12 @@ issues are marked by a symbol beside the gutter. Select the symbol to see the li
### Pipeline details view
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The full list of Code Quality violations generated by a pipeline is shown in the **Code Quality**
tab of the pipeline's details page. The pipeline details view displays all Code Quality findings
@@ -137,12 +149,19 @@ that were found on the branch it was run on.
### Project quality view
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72724) in GitLab 14.5 [with a flag](../../administration/feature_flags.md) named `project_quality_summary_page`. This feature is in [beta](../../policy/development_stages_support.md). Disabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72724) in GitLab 14.5 [with a flag](../../administration/feature_flags.md) named `project_quality_summary_page`. This feature is in [beta](../../policy/development_stages_support.md). Disabled by default.
+{{< /history >}}
The project quality view displays an overview of the code quality findings. The view can be found under **Analyze > CI/CD analytics**, and requires [`project_quality_summary_page`](../../user/feature_flags.md) feature flag to be enabled for this particular project.
diff --git a/doc/ci/testing/code_quality_codeclimate_scanning.md b/doc/ci/testing/code_quality_codeclimate_scanning.md
index f56b123507fbd35fd85457e3eeb579822bfb8668..7df7266043fcd4d4a1ec9d5013e00ae81644b56e 100644
--- a/doc/ci/testing/code_quality_codeclimate_scanning.md
+++ b/doc/ci/testing/code_quality_codeclimate_scanning.md
@@ -7,14 +7,20 @@ title: Configure CodeClimate-based Code Quality scanning (deprecated)
<!--- start_remove The following content will be removed on remove_date: '2025-08-15' -->
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](../../update/deprecations.md#codeclimate-based-code-quality-scanning-will-be-removed) in GitLab 17.3 and is planned for removal in 18.0.
[Integrate the results from a supported tool directly](code_quality.md#import-code-quality-results-from-a-cicd-job) instead. This change is a breaking change.
+{{< /alert >}}
+
Code Quality includes a built-in CI/CD template, `Code-Quality.gitlab-ci.yaml`.
This template runs a scan based on the open source CodeClimate scanning engine.
@@ -54,11 +60,14 @@ To enable Code Quality, either:
Code Quality now runs in pipelines.
-WARNING:
+{{< alert type="warning" >}}
+
On GitLab Self-Managed, if a malicious actor compromises the Code Quality job definition they
could execute privileged Docker commands on the runner host. Having proper access control policies
mitigates this attack vector by allowing access only to trusted actors.
+{{< /alert >}}
+
## Disable CodeClimate-based scanning
The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable
@@ -168,10 +177,13 @@ Both the JSON and HTML files are output as job artifacts. The HTML file is conta
To download the Code Quality report in _only_ HTML format, set `REPORT_FORMAT` to `html`, overriding
the default definition of the `code_quality` job.
-NOTE:
+{{< alert type="note" >}}
+
This does not create a JSON format file, so Code Quality results are not shown in the merge request
widget, pipeline report, or changes view.
+{{< /alert >}}
+
```yaml
include:
- template: Jobs/Code-Quality.gitlab-ci.yml
@@ -514,11 +526,14 @@ entrypoint = ["dockerd"]
name = "docker:20.10.12-dind"
```
-NOTE:
+{{< alert type="note" >}}
+
If you use the [GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html), you can use
the above Kubernetes configuration in the [`config` field](https://docs.gitlab.com/runner/install/kubernetes_helm_chart_configuration.html)
in the `values.yaml` file.
+{{< /alert >}}
+
To ensure that you use the `overlay2` [storage driver](https://docs.docker.com/storage/storagedriver/select-storage-driver/), which offers the best overall performance:
- Specify the `DOCKER_HOST` that the Docker CLI communicates with.
@@ -545,11 +560,14 @@ For OpenShift, you should use the [GitLab Runner Operator](https://docs.gitlab.c
To give the Docker daemon in the service container permissions to initialize its storage,
you must mount the `/var/lib` directory as a volume mount.
-NOTE:
+{{< alert type="note" >}}
+
If you cannot to mount the `/var/lib` directory as a volume mount, you can set `--storage-driver` to `vfs` instead.
If you opt for the `vfs` value, it might have a negative
impact on [performance](https://docs.docker.com/storage/storagedriver/select-storage-driver/).
+{{< /alert >}}
+
To configure permissions for the Docker daemon,
1. Create a file called `config.toml` with the configuration provided below. This configuration will be used to customized GitLab Runner generated `config.toml`:
diff --git a/doc/ci/testing/code_quality_troubleshooting.md b/doc/ci/testing/code_quality_troubleshooting.md
index a392eb19fed2b918d89f2aae74e0ffa15a629ccf..be3bde9ad01737cd48ebe91a093c61a805a3502f 100644
--- a/doc/ci/testing/code_quality_troubleshooting.md
+++ b/doc/ci/testing/code_quality_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Code Quality
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with Code Quality, you might encounter the following issues.
diff --git a/doc/ci/testing/fail_fast_testing.md b/doc/ci/testing/fail_fast_testing.md
index 6bcc4aa9a068a13c62aeccdb0c9658d30e3d35c6..064a3334d176ad73e0860b708c922505cdae1e85 100644
--- a/doc/ci/testing/fail_fast_testing.md
+++ b/doc/ci/testing/fail_fast_testing.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Fail Fast Testing
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
For applications that use RSpec for running tests, we've introduced the `Verify/Failfast`
[template to run subsets of your test suite](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Verify/FailFast.gitlab-ci.yml),
diff --git a/doc/ci/testing/load_performance_testing.md b/doc/ci/testing/load_performance_testing.md
index 911dae55c227392abece468dbba96fb0605b4114..2b87b2fe064c64fc3a835a39b500c54bfdc2dd3a 100644
--- a/doc/ci/testing/load_performance_testing.md
+++ b/doc/ci/testing/load_performance_testing.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Load Performance Testing
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With Load Performance Testing, you can test the impact of any pending code changes
to your application's backend in [GitLab CI/CD](../_index.md).
@@ -43,13 +46,16 @@ The key performance metrics that the merge request widget shows after the test c
- TTFB P95: The 95th percentile for TTFB.
- RPS: The average requests per second (RPS) rate the test was able to achieve.
-NOTE:
+{{< alert type="note" >}}
+
If the Load Performance report has no data to compare, such as when you add the
Load Performance job in your `.gitlab-ci.yml` for the very first time,
the Load Performance report widget doesn't display. It must have run at least
once on the target branch (`main`, for example), before it displays in a
merge request targeting that branch.
+{{< /alert >}}
+
## Configure the Load Performance Testing job
Configuring your Load Performance Testing job can be broken down into several distinct parts:
@@ -90,12 +96,15 @@ testing job in GitLab CI/CD. The easiest way to do this is to use the
[`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml)
template that is included with GitLab.
-NOTE:
+{{< alert type="note" >}}
+
For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual
test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations)
for spec details. The [default shared GitLab.com runners](../runners/hosted_runners/linux.md)
likely have insufficient specs to handle most large k6 tests.
+{{< /alert >}}
+
This template runs the
[k6 Docker container](https://hub.docker.com/r/loadimpact/k6/) in the job and provides several ways to customize the
job.
@@ -119,9 +128,12 @@ An example configuration workflow:
The above example creates a `load_performance` job in your CI/CD pipeline that runs
the k6 test.
-NOTE:
+{{< alert type="note" >}}
+
For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml).
+{{< /alert >}}
+
k6 has [various options](https://k6.io/docs/using-k6/k6-options/reference/) to configure how it runs the tests, such as what throughput (RPS) to run with,
how long the test should run, and so on. Almost all options can be configured in the test itself, but as
you can also pass command line options via the `K6_OPTIONS` variable.
diff --git a/doc/ci/testing/metrics_reports.md b/doc/ci/testing/metrics_reports.md
index 533a02f3b64d6035701dde3a014a95b820347a68..962d1ad67886788638fbd270233332ae1ac10bc9 100644
--- a/doc/ci/testing/metrics_reports.md
+++ b/doc/ci/testing/metrics_reports.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Metrics Reports
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides a lot of great reporting tools for things like [merge requests](../../user/project/merge_requests/_index.md) - [Unit test reports](unit_test_reports.md), [code quality](code_quality.md), and performance tests. While JUnit is a great open framework for tests that "pass" or "fail", it is also important to see other types of metrics from a given change.
diff --git a/doc/ci/testing/test_coverage_visualization/_index.md b/doc/ci/testing/test_coverage_visualization/_index.md
index 623479e437a7c11dbd5ba936abf9a8121750532e..a413a53794f84dc855c9ab057687bae7bc5e690a 100644
--- a/doc/ci/testing/test_coverage_visualization/_index.md
+++ b/doc/ci/testing/test_coverage_visualization/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../code_coverage/_index.md'
-remove_date: '2025-04-30'
+redirect_to: ../code_coverage/_index.md
+remove_date: "2025-04-30"
---
<!-- markdownlint-disable -->
diff --git a/doc/ci/testing/test_coverage_visualization/cobertura.md b/doc/ci/testing/test_coverage_visualization/cobertura.md
index 3c1b46c06175ee09336f065cd5001086aaf51cc2..d104d7ff6f41ab53f477a5460321bc003a2a5d67 100644
--- a/doc/ci/testing/test_coverage_visualization/cobertura.md
+++ b/doc/ci/testing/test_coverage_visualization/cobertura.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../code_coverage/cobertura.md'
-remove_date: '2025-04-30'
+redirect_to: ../code_coverage/cobertura.md
+remove_date: "2025-04-30"
---
<!-- markdownlint-disable -->
diff --git a/doc/ci/testing/test_coverage_visualization/jacoco.md b/doc/ci/testing/test_coverage_visualization/jacoco.md
index 7cd6670c4623352f926080654c5cb2c6d9bd85c7..f5bfac10bfac3dd941b84d7e43212ab9697bf6aa 100644
--- a/doc/ci/testing/test_coverage_visualization/jacoco.md
+++ b/doc/ci/testing/test_coverage_visualization/jacoco.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../code_coverage/jacoco.md'
-remove_date: '2025-04-30'
+redirect_to: ../code_coverage/jacoco.md
+remove_date: "2025-04-30"
---
<!-- markdownlint-disable -->
diff --git a/doc/ci/testing/unit_test_report_examples.md b/doc/ci/testing/unit_test_report_examples.md
index 641f06349a61435bb5f7be46b7587d998aa6d81d..83fe9287d11dbda86aca6d60713a2da775c52656 100644
--- a/doc/ci/testing/unit_test_report_examples.md
+++ b/doc/ci/testing/unit_test_report_examples.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Unit test report examples
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Unit test reports](unit_test_reports.md) can be generated for many languages and packages.
Use these examples as guidelines for configuring your pipeline to generate unit test reports
diff --git a/doc/ci/testing/unit_test_reports.md b/doc/ci/testing/unit_test_reports.md
index 6e4a60cdff407b9fbf062897ab75b064289bc780..19bbd48ed378b6c757366d1a20fd14ffc8f59c95 100644
--- a/doc/ci/testing/unit_test_reports.md
+++ b/doc/ci/testing/unit_test_reports.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Unit test reports
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can configure your [CI/CD pipeline](../pipelines/_index.md) to display unit test results directly in merge requests and pipeline details.
This makes it easier to identify test failures without searching through job logs.
@@ -60,7 +63,11 @@ the error output.
#### Copy failed test names
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91552) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91552) in GitLab 15.2.
+
+{{< /history >}}
You can copy the name and path of failed tests when there are failed tests listed
in the **Test summary** panel. Use name and path to find and rerun the
@@ -73,9 +80,9 @@ the `<file>` attributes for failed tests.
To copy the name of a single failed test:
-1. Expand the **Test summary** panel by selecting **Show test summary details** (**{chevron-lg-down}**).
+1. Expand the **Test summary** panel by selecting **Show test summary details** ({{< icon name="chevron-lg-down" >}}).
1. Select the test you want to review.
-1. Select **Copy test name to rerun locally** (**{copy-to-clipboard}**).
+1. Select **Copy test name to rerun locally** ({{< icon name="copy-to-clipboard" >}}).
### Number of recent failures
diff --git a/doc/ci/triggers/_index.md b/doc/ci/triggers/_index.md
index 676e05b7163fa3388215c65aa9def970a6c232cc..81391632d737782fdfd88ca53e258c383a9b19f5 100644
--- a/doc/ci/triggers/_index.md
+++ b/doc/ci/triggers/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Trigger pipelines by using the API
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To trigger a pipeline for a specific branch or tag, you can use an API call
to the [pipeline triggers API endpoint](../../api/pipeline_triggers.md).
@@ -43,7 +46,8 @@ To create a trigger token:
- You can view and copy the full token for all triggers you have created.
- You can only see the first 4 characters for tokens created by other project members.
-WARNING:
+{{< alert type="warning" >}}
+
It is a security risk to save tokens in plain text in public projects, or store them
in a way that malicious users could access them. A leaked trigger token could be
used to force an unscheduled deployment, attempt to access CI/CD variables,
@@ -51,6 +55,8 @@ or other malicious uses. [Masked CI/CD variables](../variables/_index.md#mask-a-
help improve the security of trigger tokens. For more information about keeping tokens secure,
see the [security considerations](../../security/tokens/_index.md#security-considerations).
+{{< /alert >}}
+
## Trigger a pipeline
After you [create a pipeline trigger token](#create-a-pipeline-trigger-token), you can use it to trigger
@@ -165,7 +171,7 @@ To revoke a pipeline trigger token:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > CI/CD**.
1. Expand **Pipeline triggers**.
-1. To the left of the trigger token you want to revoke, select **Revoke** (**{remove}**).
+1. To the left of the trigger token you want to revoke, select **Revoke** ({{< icon name="remove" >}}).
A revoked trigger token cannot be added back.
diff --git a/doc/ci/variables/_index.md b/doc/ci/variables/_index.md
index c650153f0a0be82310638a9e76c025165b207ccb..79b6e3535b5316accc41685daba4c1a5298ab65c 100644
--- a/doc/ci/variables/_index.md
+++ b/doc/ci/variables/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab CI/CD variables
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
CI/CD variables are a type of environment variable. You can use them to:
@@ -131,8 +134,12 @@ all variables become available to the pipeline.
### For a project
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7, projects can have a maximum of 200 CI/CD variables.
-> - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/373289) in GitLab 15.9, projects can have a maximum of 8000 CI/CD variables.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7, projects can have a maximum of 200 CI/CD variables.
+- [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/373289) in GitLab 15.9, projects can have a maximum of 8000 CI/CD variables.
+
+{{< /history >}}
You can add CI/CD variables to a project's settings.
@@ -162,8 +169,12 @@ or in [job scripts](#use-cicd-variables-in-job-scripts).
### For a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7, groups can have a maximum of 200 CI/CD variables.
-> - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/373289) in GitLab 15.9, groups can have a maximum of 30000 CI/CD variables.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362227) in GitLab 15.7, groups can have a maximum of 200 CI/CD variables.
+- [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/373289) in GitLab 15.9, groups can have a maximum of 30000 CI/CD variables.
+
+{{< /history >}}
You can make a CI/CD variable available to all projects in a group.
@@ -192,23 +203,29 @@ are recursively inherited.
#### Environment scope
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
To set a group CI/CD variable to only be available for certain environments:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Settings > CI/CD**.
1. Expand **Variables**.
-1. To the right of the variable, select **Edit** (**{pencil}**).
+1. To the right of the variable, select **Edit** ({{< icon name="pencil" >}}).
1. For **Environment scope**, select **All (default)** (`*`), a specific [environment](../environments/_index.md#types-of-environments),
or a wildcard [environment scope](../environments/_index.md#limit-the-environment-scope-of-a-cicd-variable).
### For an instance
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can make a CI/CD variable available to all projects and groups in a GitLab instance.
@@ -281,12 +298,15 @@ valid [secrets file](../../administration/backup_restore/troubleshooting_backup_
### Mask a CI/CD variable
-WARNING:
+{{< alert type="warning" >}}
+
Masking a CI/CD variable is not a guaranteed way to prevent malicious users from
accessing variable values. To ensure security of sensitive information,
consider using [external secrets](../secrets/_index.md) and [file type variables](#use-file-type-cicd-variables)
to prevent commands such as `env`/`printenv` from printing secret variables.
+{{< /alert >}}
+
You can mask a project, group, or instance CI/CD variable so the value of the variable
does not display in job logs. When a masked CI/CD variable would be displayed in a job log,
the value is replaced with `[masked]` to prevent the value from being exposed.
@@ -332,8 +352,12 @@ Different versions of [GitLab Runner](../runners/_index.md) have different maski
### Hide a CI/CD variable
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29674) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `ci_hidden_variables`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165843) in GitLab 17.6. Feature flag `ci_hidden_variables` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29674) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `ci_hidden_variables`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165843) in GitLab 17.6. Feature flag `ci_hidden_variables` removed.
+
+{{< /history >}}
In addition to masking, you can also prevent the value of CI/CD variables from being revealed
in the **CI/CD** settings page. Hiding a variable is only possible when creating a new variable,
@@ -408,11 +432,14 @@ as a `--certificate-authority` option, which accepts a path to a file:
kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM"
```
-WARNING:
+{{< alert type="warning" >}}
+
Be careful when assigning the value of a file variable to another variable in GitLab 15.6 or older.
The other variable takes the content of the file as its value, **not** the path to the file.
In GitLab 15.7 and later, this behavior [was fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/29407) and the other variable now takes the path to the file as the value.
+{{< /alert >}}
+
#### Use a `.gitlab-ci.yml` variable as a file type variable
You cannot set a CI/CD variable [defined in the `.gitlab-ci.yml` file](#define-a-cicd-variable-in-the-gitlab-ciyml-file)
@@ -726,7 +753,11 @@ job:
### Prevent CI/CD variable expansion
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217309) in GitLab 15.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217309) in GitLab 15.7.
+
+{{< /history >}}
Expanded variables treat values with the `$` character as a reference to another variable.
CI/CD variables are expanded by default. To treat variables with a `$` character as raw strings,
@@ -746,7 +777,11 @@ To disable variable expansion for the variable:
## CI/CD variable precedence
-> - Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. [Feature flag removed in GitLab 16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/435727).
+{{< history >}}
+
+- Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. [Feature flag removed in GitLab 16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/435727).
+
+{{< /history >}}
You can use CI/CD variables with the same name in different places, but the values
can overwrite each other. The type of variable and where they are defined determines
@@ -813,9 +848,12 @@ You can specify a pipeline variable when you:
These variables have [higher precedence](#cicd-variable-precedence) and can override
other defined variables, including [predefined variables](predefined_variables.md).
-WARNING:
+{{< alert type="warning" >}}
+
You should avoid overriding predefined variables in most cases, as it can cause the pipeline to behave unexpectedly.
+{{< /alert >}}
+
### Restrict pipeline variables
You can limit who can run pipelines with pipeline variables to specific user roles.
@@ -832,8 +870,12 @@ use this setting for control over the environment the pipeline runs in.
#### Set a minimum role for pipeline variables
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440338) in GitLab 17.1.
-> - For GitLab.com, setting defaults [updated for all new projects in new namespaces](https://gitlab.com/gitlab-org/gitlab/-/issues/502382) to `enabled` for `restrict_user_defined_variables` and `no_one_allowed` for `ci_pipeline_variables_minimum_override_role` in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440338) in GitLab 17.1.
+- For GitLab.com, setting defaults [updated for all new projects in new namespaces](https://gitlab.com/gitlab-org/gitlab/-/issues/502382) to `enabled` for `restrict_user_defined_variables` and `no_one_allowed` for `ci_pipeline_variables_minimum_override_role` in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -977,11 +1019,14 @@ export CI_PROJECT_TITLE="GitLab"
### Enable debug logging
-WARNING:
+{{< alert type="warning" >}}
+
Debug logging can be a serious security risk. The output contains the content of
all variables available to the job. The output is uploaded to the
GitLab server and visible in job logs.
+{{< /alert >}}
+
You can use debug logging to help troubleshoot problems with pipeline configuration
or job scripts. Debug logging exposes job execution details that are usually hidden
by the runner and makes job logs more verbose. It also exposes all variables and secrets
@@ -1083,11 +1128,14 @@ Access to debug logging is restricted to [users with at least the Developer role
- The [`.gitlab-ci.yml` file](#define-a-cicd-variable-in-the-gitlab-ciyml-file).
- The CI/CD variables set in the GitLab UI.
-WARNING:
+{{< alert type="warning" >}}
+
If you add `CI_DEBUG_TRACE` as a local variable to runners, debug logs generate and are visible
to all users with access to job logs. The permission levels are not checked by the runner,
so you should only use the variable in GitLab itself.
+{{< /alert >}}
+
### "argument list too long"
This issue occurs when the combined length of all CI/CD variables defined for a job exceeds the limit imposed by the
diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md
index 5b0bc5398ea811683df8bd90287d1c9eecc21ad9..838c95106e2d6ccce7e7923ea5e7a2d9413cb729 100644
--- a/doc/ci/variables/predefined_variables.md
+++ b/doc/ci/variables/predefined_variables.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Predefined CI/CD variables reference
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Predefined [CI/CD variables](_index.md) are available in every GitLab CI/CD pipeline.
diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md
index 26eff58f647db00b28835494cb4d520f8a6b7a58..a74b1f841ce8f3be5c027eaaa83df538f472e0d4 100644
--- a/doc/ci/variables/where_variables_can_be_used.md
+++ b/doc/ci/variables/where_variables_can_be_used.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Where variables can be used
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
As it's described in the [CI/CD variables](_index.md) documentation, you can
define many different variables. Some of them can be used for all GitLab CI/CD
@@ -24,7 +27,11 @@ There are two places defined variables can be used. On the:
### `.gitlab-ci.yml` file
-> - Support for `CI_ENVIRONMENT_*` variables except `CI_ENVIRONMENT_SLUG` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128694) in GitLab 16.4.
+{{< history >}}
+
+- Support for `CI_ENVIRONMENT_*` variables except `CI_ENVIRONMENT_SLUG` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128694) in GitLab 16.4.
+
+{{< /history >}}
| Definition | Can be expanded? | Expansion place | Description |
|:----------------------------------------------------------------------|:-----------------|:-----------------------|:------------|
diff --git a/doc/ci/yaml/_index.md b/doc/ci/yaml/_index.md
index ea86d412dbc4c6c84bfc423895119e4222fbec1e..4dc238ced98cf169e6006187facac074e59805b8 100644
--- a/doc/ci/yaml/_index.md
+++ b/doc/ci/yaml/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI/CD YAML syntax reference
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This document lists the configuration options for the GitLab `.gitlab-ci.yml` file.
This file is where you define the CI/CD jobs that make up your pipeline.
@@ -93,7 +96,11 @@ or import additional pipeline configuration.
### `default`
-> - Support for `id_tokens` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419750) in GitLab 16.4.
+{{< history >}}
+
+- Support for `id_tokens` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419750) in GitLab 16.4.
+
+{{< /history >}}
You can set global defaults for some keywords. Each default keyword is copied to every job
that doesn't already have it defined. If the job already has a keyword defined, that default
@@ -391,8 +398,12 @@ include:
#### `include:inputs`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a beta feature.
-> - [Made generally available](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/134062) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a beta feature.
+- [Made generally available](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/134062) in GitLab 17.0.
+
+{{< /history >}}
Use `include:inputs` to set the values for input parameters when the included configuration
uses [`spec:inputs`](#specinputs) and is added to the pipeline.
@@ -467,7 +478,11 @@ In this example, if the `INCLUDE_BUILDS` variable is:
### `stages`
-> - Support for nested array of strings [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439451) in GitLab 16.9.
+{{< history >}}
+
+- Support for nested array of strings [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439451) in GitLab 16.9.
+
+{{< /history >}}
Use `stages` to define stages that contain groups of jobs. Use [`stage`](#stage)
in a job to configure the job to run in a specific stage.
@@ -537,9 +552,13 @@ You can use some [predefined CI/CD variables](../variables/predefined_variables.
#### `workflow:auto_cancel:on_new_commit`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412473) in GitLab 16.8 [with a flag](../../administration/feature_flags.md) named `ci_workflow_auto_cancel_on_new_commit`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/434676) in GitLab 16.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/434676) in GitLab 16.10. Feature flag `ci_workflow_auto_cancel_on_new_commit` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412473) in GitLab 16.8 [with a flag](../../administration/feature_flags.md) named `ci_workflow_auto_cancel_on_new_commit`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/434676) in GitLab 16.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/434676) in GitLab 16.10. Feature flag `ci_workflow_auto_cancel_on_new_commit` removed.
+
+{{< /history >}}
Use `workflow:auto_cancel:on_new_commit` to configure the behavior of
the [auto-cancel redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) feature.
@@ -573,8 +592,12 @@ In this example:
#### `workflow:auto_cancel:on_job_failure`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23605) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `auto_cancel_pipeline_on_job_failure`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433163) in GitLab 16.11. Feature flag `auto_cancel_pipeline_on_job_failure` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23605) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `auto_cancel_pipeline_on_job_failure`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433163) in GitLab 16.11. Feature flag `auto_cancel_pipeline_on_job_failure` removed.
+
+{{< /history >}}
Use `workflow:auto_cancel:on_job_failure` to configure which jobs should be canceled as soon as one job fails.
@@ -616,9 +639,13 @@ In this example, if `job2` fails, `job1` is canceled if it is still running and
#### `workflow:name`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372538) in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `pipeline_name`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/376095) in GitLab 15.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/376095) in GitLab 15.8. Feature flag `pipeline_name` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372538) in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `pipeline_name`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/376095) in GitLab 15.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/376095) in GitLab 15.8. Feature flag `pipeline_name` removed.
+
+{{< /history >}}
You can use `name` in `workflow:` to define a name for pipelines.
@@ -792,11 +819,15 @@ When the branch is something else:
#### `workflow:rules:auto_cancel`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436467) in GitLab 16.8 [with a flag](../../administration/feature_flags.md) named `ci_workflow_auto_cancel_on_new_commit`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/434676) in GitLab 16.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/434676) in GitLab 16.10. Feature flag `ci_workflow_auto_cancel_on_new_commit` removed.
-> - `on_job_failure` option for `workflow:rules` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23605) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `auto_cancel_pipeline_on_job_failure`. Disabled by default.
-> - `on_job_failure` option for `workflow:rules` [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433163) in GitLab 16.11. Feature flag `auto_cancel_pipeline_on_job_failure` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436467) in GitLab 16.8 [with a flag](../../administration/feature_flags.md) named `ci_workflow_auto_cancel_on_new_commit`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/434676) in GitLab 16.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/434676) in GitLab 16.10. Feature flag `ci_workflow_auto_cancel_on_new_commit` removed.
+- `on_job_failure` option for `workflow:rules` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23605) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `auto_cancel_pipeline_on_job_failure`. Disabled by default.
+- `on_job_failure` option for `workflow:rules` [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433163) in GitLab 16.11. Feature flag `auto_cancel_pipeline_on_job_failure` removed.
+
+{{< /history >}}
Use `workflow:rules:auto_cancel` to configure the behavior of
the [`workflow:auto_cancel:on_new_commit`](#workflowauto_cancelon_new_commit) or
@@ -847,7 +878,11 @@ with `---`.
### `spec`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a beta feature.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a beta feature.
+
+{{< /history >}}
Add a `spec` section to the header of a YAML file to configure the behavior of a pipeline
when a configuration is added to the pipeline with the `include` keyword.
@@ -897,7 +932,11 @@ scan-website:
##### `spec:inputs:default`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a beta feature.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a beta feature.
+
+{{< /history >}}
Inputs are mandatory when included, unless you set a default value with `spec:inputs:default`.
@@ -938,7 +977,11 @@ In this example:
##### `spec:inputs:description`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415637) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415637) in GitLab 16.5.
+
+{{< /history >}}
Use `description` to give a description to a specific input. The description does
not affect the behavior of the input and is only used to help users of the file
@@ -962,7 +1005,11 @@ title: The pipeline configuration would follow...
##### `spec:inputs:options`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393401) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393401) in GitLab 16.6.
+
+{{< /history >}}
Inputs can use `options` to specify a list of allowed values for an input.
The limit is 50 options per input.
@@ -1000,7 +1047,11 @@ In this example:
##### `spec:inputs:regex`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/410836) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/410836) in GitLab 16.5.
+
+{{< /history >}}
Use `spec:inputs:regex` to specify a regular expression that the input must match.
@@ -1070,7 +1121,11 @@ The following topics explain how to use keywords to configure CI/CD pipelines.
### `after_script`
-> - Running `after_script` commands for canceled jobs [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10158) in GitLab 17.0.
+{{< history >}}
+
+- Running `after_script` commands for canceled jobs [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10158) in GitLab 17.0.
+
+{{< /history >}}
Use `after_script` to define an array of commands to run last, after a job's `before_script` and
`script` sections complete. `after_script` commands also run when:
@@ -1142,7 +1197,7 @@ Use `allow_failure` to determine whether a pipeline should continue running when
- To let the pipeline continue running subsequent jobs, use `allow_failure: true`.
- To stop the pipeline from running subsequent jobs, use `allow_failure: false`.
-When jobs are allowed to fail (`allow_failure: true`) an orange warning (**{status_warning}**)
+When jobs are allowed to fail (`allow_failure: true`) an orange warning ({{< icon name="status_warning" >}})
indicates that a job failed. However, the pipeline is successful and the associated commit
is marked as passed with no warnings.
@@ -1458,13 +1513,20 @@ job:
#### `artifacts:public`
-> - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/322454) in GitLab 15.10. Artifacts created with `artifacts:public` before 15.10 are not guaranteed to remain private after this update.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/294503) in GitLab 16.7. Feature flag `non_public_artifacts` removed.
+{{< history >}}
+
+- [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/322454) in GitLab 15.10. Artifacts created with `artifacts:public` before 15.10 are not guaranteed to remain private after this update.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/294503) in GitLab 16.7. Feature flag `non_public_artifacts` removed.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
`artifacts:public` is now superseded by [`artifacts:access`](#artifactsaccess) which
has more options.
+{{< /alert >}}
+
Use `artifacts:public` to determine whether the job artifacts should be
publicly available.
@@ -1491,7 +1553,11 @@ job:
#### `artifacts:access`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145206) in GitLab 16.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145206) in GitLab 16.11.
+
+{{< /history >}}
Use `artifacts:access` to determine who can access the job artifacts from the GitLab UI
or API. This option does not prevent you from forwarding artifacts to downstream pipelines.
@@ -1654,7 +1720,11 @@ job:
### `cache`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330047) in GitLab 15.0, caches are not shared between protected and unprotected branches.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330047) in GitLab 15.0, caches are not shared between protected and unprotected branches.
+
+{{< /history >}}
Use `cache` to specify a list of files and directories to
cache between jobs. You can only use paths that are in the local working copy.
@@ -1898,15 +1968,22 @@ rspec:
#### `cache:unprotect`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362114) in GitLab 15.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362114) in GitLab 15.8.
+
+{{< /history >}}
Use `cache:unprotect` to set a cache to be shared between [protected](../../user/project/repository/branches/protected.md)
and unprotected branches.
-WARNING:
+{{< alert type="warning" >}}
+
When set to `true`, users without access to protected branches can read and write to
cache keys used by protected branches.
+{{< /alert >}}
+
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default` section](#default).
@@ -2082,9 +2159,12 @@ In this example:
### `dast_configuration`
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the `dast_configuration` keyword to specify a site profile and scanner profile to be used in a
CI/CD configuration. Both profiles must first have been created in the project. The job's stage must
@@ -2317,8 +2397,12 @@ stop_review_app:
#### `environment:auto_stop_in`
-> - CI/CD variable support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365140) in GitLab 15.4.
-> - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/437133) to support `prepare`, `access` and `verify` environment actions in GitLab 17.7.
+{{< history >}}
+
+- CI/CD variable support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365140) in GitLab 15.4.
+- [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/437133) to support `prepare`, `access` and `verify` environment actions in GitLab 17.7.
+
+{{< /history >}}
The `auto_stop_in` keyword specifies the lifetime of the environment. When an environment expires, GitLab
automatically stops it.
@@ -2358,8 +2442,12 @@ Some actions can be used to reset the scheduled stop time for the environment. F
#### `environment:kubernetes`
-> - `agent` keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467912) in GitLab 17.6.
-> - `namespace` and `flux_resource_path` keywords [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/500164) in GitLab 17.7.
+{{< history >}}
+
+- `agent` keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467912) in GitLab 17.6.
+- `namespace` and `flux_resource_path` keywords [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/500164) in GitLab 17.7.
+
+{{< /history >}}
Use the `kubernetes` keyword to configure the [dashboard for Kubernetes](../environments/kubernetes_dashboard.md)
for an environment.
@@ -2525,8 +2613,12 @@ rubocop:
### `hooks`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356850) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/381840) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356850) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/381840) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed.
+
+{{< /history >}}
Use `hooks` to specify lists of commands to execute on the runner
at certain stages of job execution, like before retrieving the Git repository.
@@ -2540,8 +2632,12 @@ at certain stages of job execution, like before retrieving the Git repository.
#### `hooks:pre_get_sources_script`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356850) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/381840) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356850) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/381840) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed.
+
+{{< /history >}}
Use `hooks:pre_get_sources_script` to specify a list of commands to execute on the runner
before cloning the Git repository and any submodules.
@@ -2574,13 +2670,20 @@ job1:
### `identity`
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142054) in GitLab 16.9 [with a flag](../../administration/feature_flags.md) named `google_cloud_support_feature_flag`. This feature is in [beta](../../policy/development_stages_support.md).
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142054) in GitLab 16.9 [with a flag](../../administration/feature_flags.md) named `google_cloud_support_feature_flag`. This feature is in [beta](../../policy/development_stages_support.md).
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+
+{{< /history >}}
This feature is in [beta](../../policy/development_stages_support.md).
@@ -2608,7 +2711,11 @@ job_with_workload_identity:
### `id_tokens`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7.
+
+{{< /history >}}
Use `id_tokens` to create [JSON web tokens (JWT)](https://www.rfc-editor.org/rfc/rfc7519) to authenticate with third party services. All
JWTs created this way support OIDC authentication. The required `aud` sub-keyword is used to configure the `aud` claim for the JWT.
@@ -2741,8 +2848,12 @@ test-job:
#### `image:docker`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27919) in GitLab 16.7. Requires GitLab Runner 16.7 or later.
-> - `user` input option [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137907) in GitLab 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27919) in GitLab 16.7. Requires GitLab Runner 16.7 or later.
+- `user` input option [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137907) in GitLab 16.8.
+
+{{< /history >}}
Use `image:docker` to pass options to the [Docker executor](https://docs.gitlab.com/runner/executors/docker.html)
runner. This keyword does not work with other executor types.
@@ -2777,10 +2888,14 @@ arm-sql-job:
#### `image:pull_policy`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21619) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `ci_docker_image_pull_policy`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.2.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.4. [Feature flag `ci_docker_image_pull_policy`](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) removed.
-> - Requires GitLab Runner 15.1 or later.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21619) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `ci_docker_image_pull_policy`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.2.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.4. [Feature flag `ci_docker_image_pull_policy`](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) removed.
+- Requires GitLab Runner 15.1 or later.
+
+{{< /history >}}
The pull policy that the runner uses to fetch the Docker image.
@@ -2896,7 +3011,11 @@ job2:
### `interruptible`
-> - Support for `trigger` jobs [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138508) in GitLab 16.8.
+{{< history >}}
+
+- Support for `trigger` jobs [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138508) in GitLab 16.8.
+
+{{< /history >}}
Use `interruptible` to configure the [auto-cancel redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines)
feature to cancel a job before it completes if a new pipeline on the same ref starts for a newer commit. If the feature
@@ -3133,9 +3252,12 @@ In this example:
#### `needs:project`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use `needs:project` to download artifacts from up to five jobs in other pipelines.
The artifacts are downloaded from the latest successful specified job for the specified ref.
@@ -3355,7 +3477,11 @@ upstream_status:
#### `needs:parallel:matrix`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254821) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254821) in GitLab 16.3.
+
+{{< /history >}}
Jobs can use [`parallel:matrix`](#parallelmatrix) to run a job multiple times in parallel in a single pipeline,
but with different variable values for each instance of the job.
@@ -3459,9 +3585,13 @@ This directory is exported as an artifact and published with GitLab Pages.
#### `pages:pages.publish`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415821) in GitLab 16.1.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/500000) to allow variables when passed to `publish` property in GitLab 17.9.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/428018) the `publish` property under the `pages` keyword in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415821) in GitLab 16.1.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/500000) to allow variables when passed to `publish` property in GitLab 17.9.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/428018) the `publish` property under the `pages` keyword in GitLab 17.9.
+
+{{< /history >}}
Use `pages.publish` to configure the content directory of a [`pages` job](#pages).
The top-level `publish` keyword is deprecated as of GitLab 17.9 and must now be nested under the `pages` keyword.
@@ -3513,15 +3643,22 @@ pages:
#### `pages:pages.path_prefix`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129534) in GitLab 16.7 as an [experiment](../../policy/development_stages_support.md) [with a flag](../../user/feature_flags.md) named `pages_multiple_versions_setting`, disabled by default.
-> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/422145) in GitLab 17.4.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/507423) to allow periods in GitLab 17.8.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/487161) in GitLab 17.9. Feature flag `pages_multiple_versions_setting` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129534) in GitLab 16.7 as an [experiment](../../policy/development_stages_support.md) [with a flag](../../user/feature_flags.md) named `pages_multiple_versions_setting`, disabled by default.
+- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/422145) in GitLab 17.4.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/507423) to allow periods in GitLab 17.8.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/487161) in GitLab 17.9. Feature flag `pages_multiple_versions_setting` removed.
+
+{{< /history >}}
Use `pages.path_prefix` to configure a path prefix for [parallel deployments](../../user/project/pages/_index.md#parallel-deployments) of GitLab Pages.
@@ -3555,11 +3692,18 @@ In this example, a different pages deployment is created for each branch.
#### `pages:pages.expire_in`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/456478) in GitLab 17.4
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/456478) in GitLab 17.4
+
+{{< /history >}}
Use `expire_in` to specify how long a deployment should be available before
it expires. After the deployment is expired, it's deactivated by a cron
@@ -3600,7 +3744,11 @@ pages:
### `parallel`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336576) in GitLab 15.9, the maximum value for `parallel` is increased from 50 to 200.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336576) in GitLab 15.9, the maximum value for `parallel` is increased from 50 to 200.
+
+{{< /history >}}
Use `parallel` to run a job multiple times in parallel in a single pipeline.
@@ -3640,7 +3788,11 @@ This example creates 5 jobs that run in parallel, named `test 1/5` to `test 5/5`
#### `parallel:matrix`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336576) in GitLab 15.9, the maximum number of permutations is increased from 50 to 200.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336576) in GitLab 15.9, the maximum number of permutations is increased from 50 to 200.
+
+{{< /history >}}
Use `parallel:matrix` to run a job multiple times in parallel in a single pipeline,
but with different variable values for each instance of the job.
@@ -3839,7 +3991,11 @@ job:
#### `release:tag_message`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363024) in GitLab 15.3. Supported by `release-cli` v0.12.0 or later.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363024) in GitLab 15.3. Supported by `release-cli` v0.12.0 or later.
+
+{{< /history >}}
If the tag does not exist, the newly created tag is annotated with the message specified by `tag_message`.
If omitted, a lightweight tag is created.
@@ -4101,9 +4257,13 @@ test:
#### `retry:exit_codes`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/430037) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `ci_retry_on_exit_codes`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/430037) in GitLab 16.11.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/452412) in GitLab 17.5. Feature flag `ci_retry_on_exit_codes` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/430037) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `ci_retry_on_exit_codes`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/430037) in GitLab 16.11.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/452412) in GitLab 17.5. Feature flag `ci_retry_on_exit_codes` removed.
+
+{{< /history >}}
Use `retry:exit_codes` with `retry:max` to retry jobs for only specific failure cases.
`retry:max` is the maximum number of retries, like [`retry`](#retry), and can be
@@ -4317,7 +4477,11 @@ In this example:
##### `rules:changes:paths`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90171) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90171) in GitLab 15.2.
+
+{{< /history >}}
Use `rules:changes` to specify that a job only be added to a pipeline when specific
files are changed, and use `rules:changes:paths` to specify the files.
@@ -4354,9 +4518,13 @@ In this example, both jobs have the same behavior.
##### `rules:changes:compare_to`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293645) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `ci_rules_changes_compare`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366412) in GitLab 15.5. Feature flag `ci_rules_changes_compare` removed.
-> - Support for CI/CD variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369916) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293645) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `ci_rules_changes_compare`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366412) in GitLab 15.5. Feature flag `ci_rules_changes_compare` removed.
+- Support for CI/CD variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369916) in GitLab 17.2.
+
+{{< /history >}}
Use `rules:changes:compare_to` to specify which ref to compare against for changes to the files
listed under [`rules:changes:paths`](#ruleschangespaths).
@@ -4397,8 +4565,12 @@ relative to `refs/heads/branch1` and the pipeline source is a merge request even
#### `rules:exists`
-> - CI/CD variable support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/283881) in GitLab 15.6.
-> - Maximum number of checks against `exists` patterns or file paths [increased](https://gitlab.com/gitlab-org/gitlab/-/issues/227632) from 10,000 to 50,000 in GitLab 17.7.
+{{< history >}}
+
+- CI/CD variable support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/283881) in GitLab 15.6.
+- Maximum number of checks against `exists` patterns or file paths [increased](https://gitlab.com/gitlab-org/gitlab/-/issues/227632) from 10,000 to 50,000 in GitLab 17.7.
+
+{{< /history >}}
Use `exists` to run a job when certain files exist in the repository.
@@ -4459,8 +4631,12 @@ In this example:
##### `rules:exists:paths`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386040) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `ci_support_rules_exists_paths_and_project`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/386040) in GitLab 17.0. Feature flag `ci_support_rules_exists_paths_and_project` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386040) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `ci_support_rules_exists_paths_and_project`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/386040) in GitLab 17.0. Feature flag `ci_support_rules_exists_paths_and_project` removed.
+
+{{< /history >}}
`rules:exists:paths` is the same as using [`rules:exists`](#rulesexists) without
any subkeys. All additional details are the same.
@@ -4499,8 +4675,12 @@ In this example, both jobs have the same behavior.
##### `rules:exists:project`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386040) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `ci_support_rules_exists_paths_and_project`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/386040) in GitLab 17.0. Feature flag `ci_support_rules_exists_paths_and_project` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386040) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `ci_support_rules_exists_paths_and_project`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/386040) in GitLab 17.0. Feature flag `ci_support_rules_exists_paths_and_project` removed.
+
+{{< /history >}}
Use `rules:exists:project` to specify the location in which to search for the files
listed under [`rules:exists:paths`](#rulesexistspaths). Must be used with `rules:exists:paths`.
@@ -4616,8 +4796,12 @@ If the rule matches, then the job is a manual job with `allow_failure: true`.
#### `rules:needs`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31581) in GitLab 16.0 [with a flag](../../user/feature_flags.md) named `introduce_rules_with_needs`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/408871) in GitLab 16.2. Feature flag `introduce_rules_with_needs` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31581) in GitLab 16.0 [with a flag](../../user/feature_flags.md) named `introduce_rules_with_needs`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/408871) in GitLab 16.2. Feature flag `introduce_rules_with_needs` removed.
+
+{{< /history >}}
Use `needs` in rules to update a job's [`needs`](#needs) for specific conditions. When a condition matches a rule, the job's `needs` configuration is completely replaced with the `needs` in the rule.
@@ -4694,7 +4878,11 @@ job:
#### `rules:interruptible`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/194023) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/194023) in GitLab 16.10.
+
+{{< /history >}}
Use `interruptible` in rules to update a job's [`interruptible`](#interruptible) value for specific conditions.
@@ -4723,15 +4911,25 @@ job:
### `run`
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440487) in GitLab 17.3 [with a flag](../../administration/feature_flags.md) named `pipeline_run_keyword`. Disabled by default. Requires GitLab Runner 17.1.
-> - Feature flag `pipeline_run_keyword` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471925) in GitLab 17.5.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440487) in GitLab 17.3 [with a flag](../../administration/feature_flags.md) named `pipeline_run_keyword`. Disabled by default. Requires GitLab Runner 17.1.
+- Feature flag `pipeline_run_keyword` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471925) in GitLab 17.5.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Use `run` to define a series of [steps](../steps/_index.md) to be executed in a job. Each step can be either a script or a predefined step.
You can also provide optional environment variables and inputs.
@@ -4817,9 +5015,12 @@ job2:
### `secrets`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use `secrets` to specify [CI/CD secrets](../secrets/_index.md) to:
@@ -4829,7 +5030,11 @@ Use `secrets` to specify [CI/CD secrets](../secrets/_index.md) to:
#### `secrets:vault`
-> - `generic` engine option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366492) in GitLab Runner 16.11.
+{{< history >}}
+
+- `generic` engine option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366492) in GitLab Runner 16.11.
+
+{{< /history >}}
Use `secrets:vault` to specify secrets provided by a [HashiCorp Vault](https://www.vaultproject.io/).
@@ -4879,7 +5084,11 @@ job:
#### `secrets:gcp_secret_manager`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11739) in GitLab 16.8 and GitLab Runner 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11739) in GitLab 16.8 and GitLab Runner 16.8.
+
+{{< /history >}}
Use `secrets:gcp_secret_manager` to specify secrets provided by [GCP Secret Manager](https://cloud.google.com/security/products/secret-manager).
@@ -4907,7 +5116,11 @@ job:
#### `secrets:azure_key_vault`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab 16.3 and GitLab Runner 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab 16.3 and GitLab Runner 16.3.
+
+{{< /history >}}
Use `secrets:azure_key_vault` to specify secrets provided by a [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault/).
@@ -4967,8 +5180,12 @@ job:
#### `secrets:token`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.8, controlled by the **Limit JSON Web Token (JWT) access** setting.
-> - [Made always available and **Limit JSON Web Token (JWT) access** setting removed](https://gitlab.com/gitlab-org/gitlab/-/issues/366798) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.8, controlled by the **Limit JSON Web Token (JWT) access** setting.
+- [Made always available and **Limit JSON Web Token (JWT) access** setting removed](https://gitlab.com/gitlab-org/gitlab/-/issues/366798) in GitLab 16.0.
+
+{{< /history >}}
Use `secrets:token` to explicitly select a token to use when authenticating with Vault by referencing the token's CI/CD variable.
@@ -5050,8 +5267,12 @@ In this example, GitLab launches two containers for the job:
#### `services:docker`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27919) in GitLab 16.7. Requires GitLab Runner 16.7 or later.
-> - `user` input option [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137907) in GitLab 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27919) in GitLab 16.7. Requires GitLab Runner 16.7 or later.
+- `user` input option [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137907) in GitLab 16.8.
+
+{{< /history >}}
Use `services:docker` to pass options to the Docker executor of a GitLab Runner.
@@ -5086,10 +5307,14 @@ arm-sql-job:
#### `services:pull_policy`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21619) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `ci_docker_image_pull_policy`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.2.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.4. [Feature flag `ci_docker_image_pull_policy`](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) removed.
-> - Requires GitLab Runner 15.1 or later.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21619) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `ci_docker_image_pull_policy`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.2.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.4. [Feature flag `ci_docker_image_pull_policy`](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) removed.
+- Requires GitLab Runner 15.1 or later.
+
+{{< /history >}}
The pull policy that the runner uses to fetch the Docker image.
@@ -5330,7 +5555,11 @@ test:
### `trigger`
-> - Support for `environment` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369061) in GitLab 16.4.
+{{< history >}}
+
+- Support for `environment` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369061) in GitLab 16.4.
+
+{{< /history >}}
Use `trigger` to declare that a job is a "trigger job" which starts a
[downstream pipeline](../pipelines/downstream_pipelines.md) that is either:
@@ -5487,15 +5716,19 @@ successfully complete before starting.
The downstream pipeline can complete successfully without running any optional manual jobs.
- [Blocking manual jobs](../jobs/job_control.md#types-of-manual-jobs) in the downstream pipeline
must run before the trigger job is marked as successful or failed. The trigger job
- shows **pending** (**{status_pending}**) if the downstream pipeline status is
- **waiting for manual action** (**{status_manual}**) due to manual jobs. By default,
+ shows **pending** ({{< icon name="status_pending" >}}) if the downstream pipeline status is
+ **waiting for manual action** ({{< icon name="status_manual" >}}) due to manual jobs. By default,
jobs in later stages do not start until the trigger job completes.
- If the downstream pipeline has a failed job, but the job uses [`allow_failure: true`](#allow_failure),
the downstream pipeline is considered successful and the trigger job shows **success**.
#### `trigger:forward`
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/355572) in GitLab 15.1. [Feature flag `ci_trigger_forward_variables`](https://gitlab.com/gitlab-org/gitlab/-/issues/355572) removed.
+{{< history >}}
+
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/355572) in GitLab 15.1. [Feature flag `ci_trigger_forward_variables`](https://gitlab.com/gitlab-org/gitlab/-/issues/355572) removed.
+
+{{< /history >}}
Use `trigger:forward` to specify what to forward to the downstream pipeline. You can control
what is forwarded to both [parent-child pipelines](../pipelines/downstream_pipelines.md#parent-child-pipelines)
@@ -5632,7 +5865,11 @@ In this example, the script:
#### `manual_confirmation`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18906) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18906) in GitLab 17.1.
+
+{{< /history >}}
Use `manual_confirmation` with [`when: manual`](#when) to define a custom confirmation message for manual jobs.
If there is no manual job defined with `when: manual`, this keyword has no effect.
@@ -5812,7 +6049,11 @@ variables:
#### `variables:options`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105502) in GitLab 15.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105502) in GitLab 15.7.
+
+{{< /history >}}
Use `variables:options` to define an array of values that are [selectable in the UI when running a pipeline manually](../pipelines/_index.md#configure-a-list-of-selectable-prefilled-variable-values).
@@ -5845,10 +6086,14 @@ variables:
### `variables:expand`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353991) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_raw_variables_in_yaml_config`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/375034) in GitLab 15.6.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375034) in GitLab 15.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/375034) in GitLab 15.8. Feature flag `ci_raw_variables_in_yaml_config` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353991) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_raw_variables_in_yaml_config`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/375034) in GitLab 15.6.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375034) in GitLab 15.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/375034) in GitLab 15.8. Feature flag `ci_raw_variables_in_yaml_config` removed.
+
+{{< /history >}}
Use the `expand` keyword to configure a variable to be expandable or not.
@@ -5882,10 +6127,13 @@ variables:
The following keywords are deprecated.
-NOTE:
+{{< alert type="note" >}}
+
These keywords are still usable to ensure backwards compatibility,
but could be scheduled for removal in a future major milestone.
+{{< /alert >}}
+
### Globally-defined `image`, `services`, `cache`, `before_script`, `after_script`
Defining `image`, `services`, `cache`, `before_script`, and `after_script` globally is deprecated.
@@ -5910,11 +6158,14 @@ default:
### `only` / `except`
-NOTE:
+{{< alert type="note" >}}
+
`only` and `except` are deprecated and not being actively developed. These keywords
are still usable to ensure backwards compatibility, but could be scheduled for removal
in a future milestone. To control when to add jobs to pipelines, use [`rules`](#rules) instead.
+{{< /alert >}}
+
You can use `only` and `except` to control when to add jobs to pipelines.
- Use `only` to define when a job runs.
@@ -5922,12 +6173,15 @@ You can use `only` and `except` to control when to add jobs to pipelines.
#### `only:refs` / `except:refs`
-NOTE:
+{{< alert type="note" >}}
+
`only:refs` and `except:refs` are deprecated and not being actively developed. These keywords
are still usable to ensure backwards compatibility, but could be scheduled for removal
in a future milestone. To use refs, regular expressions, or variables to control
when to add jobs to pipelines, use [`rules:if`](#rulesif) instead.
+{{< /alert >}}
+
You can use the `only:refs` and `except:refs` keywords to control when to add jobs to a
pipeline based on branch names or pipeline types.
@@ -6012,12 +6266,15 @@ job2:
#### `only:variables` / `except:variables`
-NOTE:
+{{< alert type="note" >}}
+
`only:variables` and `except:variables` are deprecated and not being actively developed.
These keywords are still usable to ensure backwards compatibility, but could be scheduled
for removal in a future milestone. To use refs, regular expressions, or variables
to control when to add jobs to pipelines, use [`rules:if`](#rulesif) instead.
+{{< /alert >}}
+
You can use the `only:variables` or `except:variables` keywords to control when to add jobs
to a pipeline, based on the status of [CI/CD variables](../variables/_index.md).
@@ -6042,12 +6299,15 @@ deploy:
`only:variables` and `except:variables`
-NOTE:
+{{< alert type="note" >}}
+
`only:changes` and `except:changes` are deprecated and not being actively developed.
These keywords are still usable to ensure backwards compatibility, but could be scheduled
for removal in a future milestone. To use changed files to control when to add a job to a pipeline,
use [`rules:changes`](#ruleschanges) instead.
+{{< /alert >}}
+
Use the `changes` keyword with `only` to run a job, or with `except` to skip a job,
when a Git push event modifies a file.
@@ -6103,13 +6363,16 @@ docker build:
#### `only:kubernetes` / `except:kubernetes`
-NOTE:
+{{< alert type="note" >}}
+
`only:kubernetes` and `except:kubernetes` are deprecated and not being actively developed.
These keywords are still usable to ensure backwards compatibility, but could be scheduled
for removal in a future milestone. To control if jobs are added to the pipeline when
the Kubernetes service is active in the project, use [`rules:if`](#rulesif) with the
[`CI_KUBERNETES_ACTIVE`](../variables/predefined_variables.md) predefined CI/CD variable instead.
+{{< /alert >}}
+
Use `only:kubernetes` or `except:kubernetes` to control if jobs are added to the pipeline
when the Kubernetes service is active in the project.
diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md
index 96e554262d9526fc4ee02dac47e2500d96e0e270..e0a014b64006189d12a093fea50d583dbf14cb05 100644
--- a/doc/ci/yaml/artifacts_reports.md
+++ b/doc/ci/yaml/artifacts_reports.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab CI/CD artifacts reports types
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use [`artifacts:reports`](_index.md#artifactsreports) to:
@@ -28,10 +31,13 @@ pipeline features from each job.
To browse the report output files, ensure you include the [`artifacts:paths`](_index.md#artifactspaths) keyword in your job definition.
-NOTE:
+{{< alert type="note" >}}
+
Combined reports in parent pipelines using [artifacts from child pipelines](_index.md#needspipelinejob) is
not supported. Track progress on adding support in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215725).
+{{< /alert >}}
+
## `artifacts:reports:accessibility`
The `accessibility` report uses [pa11y](https://pa11y.org/) to report on the accessibility impact
@@ -44,7 +50,11 @@ For more information, see [Accessibility testing](../testing/accessibility_testi
## `artifacts:reports:annotations`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38337) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38337) in GitLab 16.3.
+
+{{< /history >}}
The `annotations` report is used to attach auxiliary data to a job.
@@ -93,8 +103,11 @@ The following is an example of what a job annotations report might look like:
## `artifacts:reports:api_fuzzing`
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
The `api_fuzzing` report collects [API Fuzzing bugs](../../user/application_security/api_fuzzing/_index.md)
as artifacts.
@@ -108,8 +121,11 @@ GitLab can display the results of one or more reports in:
## `artifacts:reports:browser_performance`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
The `browser_performance` report collects [Browser Performance Testing metrics](../testing/browser_performance_testing.md)
as an artifact. This artifact is a JSON file output by the [Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance).
@@ -148,7 +164,11 @@ GitLab can display the results of coverage report in the merge request
## `artifacts:reports:codequality`
-> - Multiple reports in diff annotations and full pipeline report [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9014) in GitLab 15.7.
+{{< history >}}
+
+- Multiple reports in diff annotations and full pipeline report [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9014) in GitLab 15.7.
+
+{{< /history >}}
The `codequality` report collects [code quality issues](../testing/code_quality.md). The
collected code quality report uploads to GitLab as an artifact.
@@ -163,8 +183,11 @@ The [`artifacts:expire_in`](_index.md#artifactsexpire_in) value is set to `1 wee
## `artifacts:reports:container_scanning`
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
The `container_scanning` report collects [Container Scanning vulnerabilities](../../user/application_security/container_scanning/_index.md).
The collected Container Scanning report uploads to GitLab as an artifact.
@@ -178,8 +201,11 @@ GitLab can display the results of one or more reports in:
## `artifacts:reports:coverage_fuzzing`
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
The `coverage_fuzzing` report collects [coverage fuzzing bugs](../../user/application_security/coverage_fuzzing/_index.md).
The collected coverage fuzzing report uploads to GitLab as an artifact.
@@ -192,10 +218,17 @@ GitLab can display the results of one or more reports in:
## `artifacts:reports:cyclonedx`
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360766) in GitLab 15.3
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360766) in GitLab 15.3
+
+{{< /history >}}
This report is a Software Bill of Materials describing the components of a project
following the [CycloneDX](https://cyclonedx.org/docs/1.4) protocol format.
@@ -220,8 +253,11 @@ artifacts:
## `artifacts:reports:dast`
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
The `dast` report collects [DAST vulnerabilities](../../user/application_security/dast/_index.md). The collected DAST
report uploads to GitLab as an artifact.
@@ -235,8 +271,11 @@ GitLab can display the results of one or more reports in:
## `artifacts:reports:dependency_scanning`
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
The `dependency_scanning` report collects [Dependency Scanning vulnerabilities](../../user/application_security/dependency_scanning/_index.md).
The collected Dependency Scanning report uploads to GitLab as an artifact.
@@ -315,8 +354,11 @@ concatenate them into a single file. Use either:
## `artifacts:reports:load_performance`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
The `load_performance` report collects [Load Performance Testing metrics](../testing/load_performance_testing.md).
The report is uploaded to GitLab as an artifact.
@@ -328,8 +370,11 @@ GitLab cannot display the combined results of multiple `load_performance` report
## `artifacts:reports:metrics`
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
The `metrics` report collects [Metrics](../testing/metrics_reports.md). The collected Metrics report uploads to GitLab as an
artifact.
@@ -339,8 +384,11 @@ GitLab can display the results of one or more reports in the merge request
## `artifacts:reports:requirements`
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
The `requirements` report collects `requirements.json` files. The collected Requirements report uploads to GitLab as an
artifact and existing [requirements](../../user/project/requirements/_index.md) are marked as Satisfied.
@@ -352,17 +400,27 @@ GitLab can display the results of one or more reports in the
## `artifacts:reports:repository_xray` (deprecated)
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432235) in GitLab 16.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432235) in GitLab 16.7.
+
+{{< /history >}}
The `repository_xray` report collects information about your repository for use by GitLab Duo Code Suggestions.
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/500146) in GitLab 17.6
and is planned for removal in 18.0. Use [Enable Repository X-Ray](../../user/project/repository/code_suggestions/repository_xray.md#enable-repository-x-ray) instead.
+{{< /alert >}}
+
<!--- end_remove -->
## `artifacts:reports:sast`
diff --git a/doc/ci/yaml/ci_job_log_timestamps.md b/doc/ci/yaml/ci_job_log_timestamps.md
index e0f0b5442c7482e193dfb03065bce0371aab8f14..c50d7512cc033e6bd3a4875f31c9702fbfe04903 100644
--- a/doc/ci/yaml/ci_job_log_timestamps.md
+++ b/doc/ci/yaml/ci_job_log_timestamps.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../jobs/job_logs.md#job-log-timestamps'
-remove_date: '2025-01-24'
+redirect_to: ../jobs/job_logs.md#job-log-timestamps
+remove_date: "2025-01-24"
---
<!-- markdownlint-disable -->
diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md
index 5776f7388358d946a77f7b4cbe709060e82b6c39..61d94e1d2e3082878e438b803161018b5dfc3afd 100644
--- a/doc/ci/yaml/includes.md
+++ b/doc/ci/yaml/includes.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use CI/CD configuration from other files
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use [`include`](_index.md#include) to include external YAML files in your CI/CD jobs.
@@ -433,7 +436,11 @@ this issue.
## Use `rules` with `include`
-> - Support for `needs` job dependency [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345377) in GitLab 15.11.
+{{< history >}}
+
+- Support for `needs` job dependency [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345377) in GitLab 15.11.
+
+{{< /history >}}
You can use [`rules`](_index.md#rules) with `include` to conditionally include other configuration files.
@@ -446,8 +453,12 @@ these keywords:
### `include` with `rules:if`
-> - Support for `when: never` and `when:always` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348146) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `ci_support_include_rules_when_never`. Disabled by default.
-> - Support for `when: never` and `when:always` [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/414517) in GitLab 16.2. Feature flag `ci_support_include_rules_when_never` removed.
+{{< history >}}
+
+- Support for `when: never` and `when:always` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348146) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `ci_support_include_rules_when_never`. Disabled by default.
+- Support for `when: never` and `when:always` [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/414517) in GitLab 16.2. Feature flag `ci_support_include_rules_when_never` removed.
+
+{{< /history >}}
Use [`rules:if`](_index.md#rulesif) to conditionally include other configuration files
based on the status of CI/CD variables. For example:
@@ -476,8 +487,12 @@ test:
### `include` with `rules:exists`
-> - Support for `when: never` and `when:always` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348146) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `ci_support_include_rules_when_never`. Disabled by default.
-> - Support for `when: never` and `when:always` [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/414517) in GitLab 16.2. Feature flag `ci_support_include_rules_when_never` removed.
+{{< history >}}
+
+- Support for `when: never` and `when:always` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348146) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `ci_support_include_rules_when_never`. Disabled by default.
+- Support for `when: never` and `when:always` [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/414517) in GitLab 16.2. Feature flag `ci_support_include_rules_when_never` removed.
+
+{{< /history >}}
Use [`rules:exists`](_index.md#rulesexists) to conditionally include other configuration files
based on the existence of files. For example:
@@ -552,7 +567,11 @@ include:
### `include` with `rules:changes`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342209) in GitLab 16.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342209) in GitLab 16.4.
+
+{{< /history >}}
Use [`rules:changes`](_index.md#ruleschanges) to conditionally include other configuration files
based on changed files. For example:
diff --git a/doc/ci/yaml/inputs.md b/doc/ci/yaml/inputs.md
index 95f62b000501a06ed5159b6101242726c3361089..ff5040e4313141719c44b85bacf159ae8b94d392 100644
--- a/doc/ci/yaml/inputs.md
+++ b/doc/ci/yaml/inputs.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Define inputs for configuration added with `include`
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a beta feature.
-> - [Made generally available](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/134062) in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a beta feature.
+- [Made generally available](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/134062) in GitLab 17.0.
+
+{{< /history >}}
Use inputs to increase the flexibility of CI/CD configuration files that are designed
to be reused.
@@ -167,7 +174,11 @@ test_job:
#### Array type
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407176) in GitLab 16.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407176) in GitLab 16.11.
+
+{{< /history >}}
The content of the items in an array type can be any valid YAML map, sequence, or scalar. More complex YAML features
like [`!reference`](yaml_optimization.md#reference-tags) cannot be used.
@@ -207,7 +218,11 @@ spec:
## Set input values when using `include`
-> - `include:with` [renamed to `include:inputs`](https://gitlab.com/gitlab-org/gitlab/-/issues/406780) in GitLab 16.0.
+{{< history >}}
+
+- `include:with` [renamed to `include:inputs`](https://gitlab.com/gitlab-org/gitlab/-/issues/406780) in GitLab 16.0.
+
+{{< /history >}}
Use [`include:inputs`](_index.md#includeinputs) to set the values for the parameters
when the included configuration is added to the pipeline.
@@ -257,9 +272,9 @@ You can pass inputs to [downstream pipelines](../pipelines/downstream_pipelines.
if the downstream pipeline's configuration file uses [`spec:inputs`](#define-input-parameters-with-specinputs).
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle Parent-child pipeline
+{{< tab title="Parent-child pipeline" >}}
```yaml
trigger-job:
@@ -273,7 +288,9 @@ trigger-job:
- if: $CI_PIPELINE_SOURCE == 'merge_request_event'
```
-:::TabTitle Multi-project pipeline
+{{< /tab >}}
+
+{{< tab title="Multi-project pipeline" >}}
```yaml
trigger-job:
@@ -288,7 +305,9 @@ trigger-job:
- if: $CI_PIPELINE_SOURCE == 'merge_request_event'
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Include the same file multiple times
@@ -484,7 +503,11 @@ my-other-job:
## Specify functions to manipulate input values
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409462) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409462) in GitLab 16.3.
+
+{{< /history >}}
You can specify predefined functions in the interpolation block to manipulate the input value.
The format supported is the following:
@@ -520,7 +543,11 @@ In this example, assuming the input uses the default value and `$MY_VAR` is an u
#### `expand_vars`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387632) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387632) in GitLab 16.5.
+
+{{< /history >}}
Use `expand_vars` to expand [CI/CD variables](../variables/_index.md) in the input value.
@@ -546,7 +573,11 @@ would expand to `test my value`.
#### `truncate`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409462) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409462) in GitLab 16.3.
+
+{{< /history >}}
Use `truncate` to shorten the interpolated value. For example:
diff --git a/doc/ci/yaml/lint.md b/doc/ci/yaml/lint.md
index ef2e7184e495b3a4f01d661bcfcbd52126dd72c1..32bf2f01f4eea248ef027d18dfc744de624edf7c 100644
--- a/doc/ci/yaml/lint.md
+++ b/doc/ci/yaml/lint.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Validate GitLab CI/CD configuration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the CI Lint tool to check the validity of GitLab CI/CD configuration.
You can validate the syntax from a `.gitlab-ci.yml` file or any other sample CI/CD configuration.
diff --git a/doc/ci/yaml/needs.md b/doc/ci/yaml/needs.md
index 09e01725fc0b81a70230b7d60d52c813515476b7..b4f4e9c6ddbe21bd8aca724265ea5e76786ba820 100644
--- a/doc/ci/yaml/needs.md
+++ b/doc/ci/yaml/needs.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Make jobs start earlier with `needs`
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use the [`needs`](_index.md#needs) keyword to create dependencies between jobs
in a pipeline. Jobs run as soon as their dependencies are met, regardless of the pipeline's `stages`
diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md
index 67839fbe8ff163c4adbe58303d43d3a5d7f5966c..0da94a80268de01d3524cfd88f9c5fcbfe6d24df 100644
--- a/doc/ci/yaml/script.md
+++ b/doc/ci/yaml/script.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Scripts and job logs
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use special syntax in [`script`](_index.md#script) sections to:
@@ -97,8 +100,12 @@ job2:
## Skip `after_script` commands if a job is canceled
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10158) in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `ci_canceling_status`. Enabled by default. Requires GitLab Runner version 16.11.1.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/460285) in GitLab 17.3. Feature flag `ci_canceling_status` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10158) in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `ci_canceling_status`. Enabled by default. Requires GitLab Runner version 16.11.1.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/460285) in GitLab 17.3. Feature flag `ci_canceling_status` removed.
+
+{{< /history >}}
[`after_script`](_index.md) commands run if a job is canceled while the `before_script`
or `script` section of that job are running.
@@ -129,13 +136,16 @@ job1:
You can split long commands into multiline commands to improve readability with
`|` (literal) and `>` (folded) [YAML multiline block scalar indicators](https://yaml-multiline.info/).
-WARNING:
+{{< alert type="warning" >}}
+
If multiple commands are combined into one command string, only the last command's
failure or success is reported.
[Failures from earlier commands are ignored due to a bug](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25394).
To work around this, run each command as a separate `script` item, or add an `exit 1`
command to each command string.
+{{< /alert >}}
+
You can use the `|` (literal) YAML multiline block scalar indicator to write
commands over multiple lines in the `script` section of a job description.
Each line is treated as a separate command.
diff --git a/doc/ci/yaml/signing_examples.md b/doc/ci/yaml/signing_examples.md
index baf6ca196e831b6e08f885a98f9e0f4fde0efe43..cebea0138908fdecb3117b3162bb867fea91dd99 100644
--- a/doc/ci/yaml/signing_examples.md
+++ b/doc/ci/yaml/signing_examples.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Sigstore for keyless signing and verification
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
The [Sigstore](https://www.sigstore.dev/) project provides a CLI called
[Cosign](https://docs.sigstore.dev/quickstart/quickstart-cosign/) which can be used for keyless signing of container images built
diff --git a/doc/ci/yaml/workflow.md b/doc/ci/yaml/workflow.md
index 4c70199471efb62720ab4446b36df2a79afe0c2d..87adeda1fdd8e621a210fe57c2696b95fed0b14f 100644
--- a/doc/ci/yaml/workflow.md
+++ b/doc/ci/yaml/workflow.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab CI/CD `workflow` keyword
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the [`workflow`](_index.md#workflow) keyword to control when pipelines are created.
@@ -160,11 +163,14 @@ build-job:
## `workflow:rules` templates (Deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
The `workflow:rules` templates were [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/456394)
in GitLab 17.0 and are planned for removal in 18.0. This change is a breaking change.
To configure `workflow:rules` in your pipeline, add the keyword explicitly. See the examples above for options.
+{{< /alert >}}
+
GitLab provides templates that set up `workflow: rules`
for common scenarios. These templates help prevent duplicate pipelines.
diff --git a/doc/ci/yaml/yaml_optimization.md b/doc/ci/yaml/yaml_optimization.md
index 08fcb21e122cd1ec1ddb18e99ae8f8765a65edc5..386617cd3df4c4872a394f46c6e113e75db3826a 100644
--- a/doc/ci/yaml/yaml_optimization.md
+++ b/doc/ci/yaml/yaml_optimization.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Optimize GitLab CI/CD configuration files
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can reduce complexity and duplicated configuration in your GitLab CI/CD configuration
files by using:
@@ -168,7 +171,11 @@ You can see that the hidden jobs are conveniently used as templates, and
### YAML anchors for scripts
-> - Support for anchors with the [`stages`](../yaml/_index.md#stages) keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439451) in GitLab 16.9.
+{{< history >}}
+
+- Support for anchors with the [`stages`](../yaml/_index.md#stages) keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439451) in GitLab 16.9.
+
+{{< /history >}}
You can use [YAML anchors](#anchors) with [script](_index.md#script), [`before_script`](_index.md#before_script),
and [`after_script`](_index.md#after_script) to use predefined commands in multiple jobs:
@@ -440,7 +447,11 @@ There's a [known issue](../debugging.md#config-should-be-an-array-of-hashes-erro
### Nest `!reference` tags in `script`, `before_script`, and `after_script`
-> - Support for `!reference` with the [`stages`](_index.md#stages) keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439451) in GitLab 16.9.
+{{< history >}}
+
+- Support for `!reference` with the [`stages`](_index.md#stages) keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439451) in GitLab 16.9.
+
+{{< /history >}}
You can nest `!reference` tags up to 10 levels deep in `script`, `before_script`, and `after_script` sections. Use nested tags to define reusable sections when building more complex scripts. For example:
diff --git a/doc/cloud_seed/_index.md b/doc/cloud_seed/_index.md
index 07e9f6fa122fbd95443eb00f9d6944b2dad8c1c9..3023436f398cb1076881a43f9602732aa88f2177 100644
--- a/doc/cloud_seed/_index.md
+++ b/doc/cloud_seed/_index.md
@@ -2,16 +2,22 @@
stage: none
group: unassigned
info: This is a GitLab Incubation Engineering program. No technical writer assigned to this group.
-ignore_in_report: true
title: Cloud Seed
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371332) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `google_cloud`. Disabled by default.
-> - [Enabled on GitLab Self-Managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100545) in GitLab 15.5.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371332) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `google_cloud`. Disabled by default.
+- [Enabled on GitLab Self-Managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100545) in GitLab 15.5.
+
+{{< /history >}}
Cloud Seed is an open-source program led
by [GitLab Incubation Engineering](https://handbook.gitlab.com/handbook/engineering/development/incubation/) in collaboration with
diff --git a/doc/development/_index.md b/doc/development/_index.md
index 4d5cb38d634db48e3e5d792f77940b5ae0f79f28..7c07c7c877086237ccdb7ac6b5bc3e612bbc4462 100644
--- a/doc/development/_index.md
+++ b/doc/development/_index.md
@@ -2,7 +2,7 @@
stage: none
group: unassigned
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Development Guidelines: learn how to contribute to GitLab."
+description: 'Development Guidelines: learn how to contribute to GitLab.'
title: Contribute to development
---
diff --git a/doc/development/activitypub/_index.md b/doc/development/activitypub/_index.md
index 86b6218f14a6ec1be3a84de7564d177097d8e65a..8815c4ad99a02a0a2ae3a2a39ccceb8b8a16b58b 100644
--- a/doc/development/activitypub/_index.md
+++ b/doc/development/activitypub/_index.md
@@ -1,22 +1,32 @@
---
stage: Create
group: Source Code
-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"
+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
title: ActivityPub
---
-DETAILS:
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127023) in GitLab 16.5 [with two flags](../../administration/feature_flags.md) named `activity_pub` and `activity_pub_project`. Disabled by default. This feature is an [experiment](../../policy/development_stages_support.md).
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127023) in GitLab 16.5 [with two flags](../../administration/feature_flags.md) named `activity_pub` and `activity_pub_project`. Disabled by default. This feature is an [experiment](../../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available,
an administrator can [enable the feature flags](../../administration/feature_flags.md)
named `activity_pub` and `activity_pub_project`.
On GitLab.com and GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
+{{< /alert >}}
+
Usage of ActivityPub in GitLab is governed by the
[GitLab Testing Agreement](https://handbook.gitlab.com/handbook/legal/testing-agreement/).
diff --git a/doc/development/activitypub/actors/_index.md b/doc/development/activitypub/actors/_index.md
index 15de07d9c9505de8751a011ff84ccd7d1bcf289e..5c8f632308d42bbe6bcd1919ce7d2687615922c8 100644
--- a/doc/development/activitypub/actors/_index.md
+++ b/doc/development/activitypub/actors/_index.md
@@ -1,22 +1,32 @@
---
stage: Create
group: Source Code
-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"
+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
title: Implement an ActivityPub actor
---
-DETAILS:
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127023) in GitLab 16.5 [with two flags](../../../administration/feature_flags.md) named `activity_pub` and `activity_pub_project`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127023) in GitLab 16.5 [with two flags](../../../administration/feature_flags.md) named `activity_pub` and `activity_pub_project`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available,
an administrator can [enable the feature flags](../../../administration/feature_flags.md)
named `activity_pub` and `activity_pub_project`.
On GitLab.com and GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
+{{< /alert >}}
+
This feature requires two feature flags:
- `activity_pub`: Enables or disables all ActivityPub-related features.
diff --git a/doc/development/activitypub/actors/releases.md b/doc/development/activitypub/actors/releases.md
index d0cef637fcbffc0c5f9fc7edfb4530a340d23cf3..05e3da1fec7842014b5148d575b19ab0a61db54c 100644
--- a/doc/development/activitypub/actors/releases.md
+++ b/doc/development/activitypub/actors/releases.md
@@ -1,22 +1,32 @@
---
stage: Create
group: Source Code
-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"
+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
title: Activities for following releases actor
---
-DETAILS:
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127023) in GitLab 16.5 [with two flags](../../../administration/feature_flags.md) named `activity_pub` and `activity_pub_project`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127023) in GitLab 16.5 [with two flags](../../../administration/feature_flags.md) named `activity_pub` and `activity_pub_project`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available,
an administrator can [enable the feature flags](../../../administration/feature_flags.md)
named `activity_pub` and `activity_pub_project`.
On GitLab.com and GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
+{{< /alert >}}
+
This feature requires two feature flags:
- `activity_pub`: Enables or disables all ActivityPub-related features.
diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md
index 579fa9a7d8689539d304fc7bdeba43ecdeb09086..121b915881729e9acdd4b50411900cbc5d94abe6 100644
--- a/doc/development/adding_service_component.md
+++ b/doc/development/adding_service_component.md
@@ -53,9 +53,12 @@ The first iteration should be to add the ability to connect and use the service
The first iteration should be opt-in, either through the `gitlab.yml` configuration or through [feature flags](feature_flags/_index.md). For these types of services it is often necessary to [bundle the service and its dependencies with GitLab](#bundling-a-service-with-gitlab) as part of the initial integration.
-NOTE:
+{{< alert type="note" >}}
+
[ActionCable](https://docs.gitlab.com/omnibus/settings/actioncable.html) is an example of a service that has been added this way.
+{{< /alert >}}
+
## Bundling a service with GitLab
Code shipped with GitLab needs to use a license approved by the Legal team. See the list of [existing approved licenses](https://handbook.gitlab.com/handbook/engineering/open-source/#using-open-source-software).
diff --git a/doc/development/advanced_search.md b/doc/development/advanced_search.md
index 4866a6db31abe5f288248b6ec216b516f5ec4d54..297e78e0ea9c979da287c343080b6d4050f1cc44 100644
--- a/doc/development/advanced_search.md
+++ b/doc/development/advanced_search.md
@@ -75,10 +75,13 @@ source of security bugs so pay close attention to them!
### Architecture
-NOTE:
+{{< alert type="note" >}}
+
We are migrating away from this architecture pattern in
[this epic](https://gitlab.com/groups/gitlab-org/-/epics/13873).
+{{< /alert >}}
+
The traditional setup, provided by `elasticsearch-rails`, is to communicate through its internal proxy classes.
Developers would write model-specific logic in a module for the model to include in (for example, `SnippetsSearch`).
The `__elasticsearch__` methods would return a proxy object, for example:
@@ -391,9 +394,12 @@ New scopes must be added to the following constants:
- `ALLOWED_SCOPES` in `Gitlab::Search::AbuseDetection`
- `search_tab_ability_map` method in `Search::Navigation`. Override in the EE version if needed
-NOTE:
+{{< alert type="note" >}}
+
Global search can be disabled for a scope. You can do the following changes for disabling global search:
+{{< /alert >}}
+
1. Add an application setting named `global_search_SCOPE_enabled` that defaults to `true` under the `search` jsonb accessor in [`app/models/application_setting.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/application_setting.rb).
1. Add an entry in JSON schema validator file [`app/validators/json_schemas/application_setting_search.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/validators/json_schemas/application_setting_search.json)
1. Add the setting checkbox in the Admin UI by creating an entry in `global_search_settings_checkboxes` method in [`ApplicationSettingsHelper`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/helpers/application_settings_helper.rb`).
@@ -743,9 +749,12 @@ Requires `source_branch` field. Query with `source_branch` or `not_source_branch
Requires `current_user`, `group_ids`, `traversal_id`, `search_level` fields. Query with `search_level` and
filter on `namespace_visibility_level` based on permissions user has for each group.
-NOTE:
+{{< alert type="note" >}}
+
Examples are shown for a logged in user. The JSON may be different for users with authorizations, admins, external, or anonymous users
+{{< /alert >}}
+
###### global
```json
@@ -914,9 +923,12 @@ Filtering is applied for:
- membership for direct membership to groups and projects or shared membership through direct access to a group
- any feature access levels passed through `features`
-NOTE:
+{{< alert type="note" >}}
+
Examples are shown for a logged in user. The JSON may be different for users with authorizations, admins, external, or anonymous users
+{{< /alert >}}
+
###### global
```json
@@ -1224,9 +1236,12 @@ Create the following MRs and have them reviewed by a member of the Global Search
## Zero-downtime reindexing with multiple indices
-NOTE:
+{{< alert type="note" >}}
+
This is not applicable yet as multiple indices functionality is not fully implemented.
+{{< /alert >}}
+
Currently GitLab can only handle a single version of setting. Any setting/schema changes would require reindexing everything from scratch. Since reindexing can take a long time, this can cause search functionality downtime.
To avoid downtime, GitLab is working to support multiple indices that
diff --git a/doc/development/ai_features/_index.md b/doc/development/ai_features/_index.md
index b510b5c1485f62c678e4193c1a6b78e5287ce1d4..3c65031d5b635f8064465dec53d4533b80a04796 100644
--- a/doc/development/ai_features/_index.md
+++ b/doc/development/ai_features/_index.md
@@ -169,11 +169,14 @@ related to [cloud licensing](https://about.gitlab.com/pricing/licensing-faq/clou
This is the configuration that all self-managed customers use who do not self-host the AI gateway
but rely on our cloud-hosted AI gateway instances instead.
-NOTE:
+{{< alert type="note" >}}
+
This setup is challenging. There is [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/463341)
for discussing how to make it easier to test the customersDot integration locally.
Until that is addressed, this setup process is time-consuming.
+{{< /alert >}}
+
If you need to get customersDot working for your local GitLab Rails instance for
any reason, reach out to `#s_fulfillment_engineering` in Slack. For questions around the integration of CDot with other systems to deliver AI use cases, reach out to `#g_cloud_connector`.
assistance.
@@ -286,9 +289,12 @@ to send the response.
The API requests to AI providers are handled in a background job. We therefore do not keep the request alive and the Frontend needs to match the request to the response from the subscription.
-WARNING:
+{{< alert type="warning" >}}
+
Determining the right response to a request can cause problems when only `userId` and `resourceId` are used. For example, when two AI features use the same `userId` and `resourceId` both subscriptions will receive the response from each other. To prevent this interference, we introduced the `clientSubscriptionId`.
+{{< /alert >}}
+
To match a response on the `aiCompletionResponse` subscription, you can provide a `clientSubscriptionId` to the `aiAction` mutation.
- The `clientSubscriptionId` should be unique per feature and within a page to not interfere with other AI features. We recommend to use a `UUID`.
diff --git a/doc/development/ai_features/actions.md b/doc/development/ai_features/actions.md
index ec2c03d02f18892ee40f2408f87c837b404b1261..5dcc148546efb25013e784d9c809841693b20a68 100644
--- a/doc/development/ai_features/actions.md
+++ b/doc/development/ai_features/actions.md
@@ -197,9 +197,12 @@ What needs to be included in the code:
- [Example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/policies/ee/global_policy.rb#L222-222) of policy not connected to the particular resource.
- [Example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/policies/ee/issue_policy.rb#L25-25) of policy connected to the particular resource.
-NOTE:
+{{< alert type="note" >}}
+
For more information, see [the GitLab AI gateway documentation](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/gitlab_ai_gateway.md#optional-enable-authentication-and-authorization-in-ai-gateway) about authentication and authorization in AI gateway.
+{{< /alert >}}
+
If your Duo feature involves an autonomous agent, you should use
[composite identity](composite_identity.md) authorization.
diff --git a/doc/development/ai_features/duo_chat.md b/doc/development/ai_features/duo_chat.md
index 460f10ed3fd4b910a6b530d66ea5b5070bcf9be7..a0fdda45bc32c627a6d1bd1ae8ca63b9d0ba2017 100644
--- a/doc/development/ai_features/duo_chat.md
+++ b/doc/development/ai_features/duo_chat.md
@@ -244,10 +244,13 @@ LangSmith integration works with any tools, including [Prompt Library](https://g
### Use tracing with LangSmith
-NOTE:
+{{< alert type="note" >}}
+
Tracing is available in Development and Testing environment only.
It's not available in Production environment.
+{{< /alert >}}
+
1. Access [LangSmith](https://smith.langchain.com/) and create an account
1. Optional: [Create an Access Request](https://gitlab.com/gitlab-com/team-member-epics/access-requests/-/issues/new?issuable_template=Individual_Bulk_Access_Request) to be added to the GitLab organization in LangSmith.
1. Create [an API key](https://docs.smith.langchain.com/#create-an-api-key) (be careful where you create API key - they can be created in personal namespace or in GL namespace).
@@ -504,9 +507,12 @@ Please, see the video ([internal link](https://drive.google.com/file/d/1X6CARf0g
### (Deprecated) Issue and epic experiments
-NOTE:
+{{< alert type="note" >}}
+
This section is deprecated in favor of the [development seed file](testing_and_validation.md#seed-project-and-group-resources-for-testing-and-evaluation).
+{{< /alert >}}
+
If you would like to use the evaluation framework (as described [here](https://gitlab.com/gitlab-org/modelops/ai-model-validation-and-research/ai-evaluation/prompt-library/-/blob/main/doc/how-to/run_duo_chat_eval.md?ref_type=heads#evaluation-on-issueepic))
you can import the required groups and projects using this Rake task:
@@ -522,9 +528,12 @@ desired.
#### (Deprecated) Epic and issue fixtures
-NOTE:
+{{< alert type="note" >}}
+
This section is deprecated in favor of the [development seed file](testing_and_validation.md#seed-project-and-group-resources-for-testing-and-evaluation).
+{{< /alert >}}
+
The fixtures are the replicas of the _public_ issues and epics from projects and groups _owned by_ GitLab.
The internal notes were excluded when they were sampled. The fixtures have been committed into the canonical `gitlab` repository.
See [the snippet](https://gitlab.com/gitlab-org/gitlab/-/snippets/3613745) used to create the fixtures.
diff --git a/doc/development/ai_features/model_migration.md b/doc/development/ai_features/model_migration.md
index 786c9cefca219d310c2da88bf233315c963d1734..dfe9857e8c80e1b8ed840f3b9ba4b1f2f1ef60ca 100644
--- a/doc/development/ai_features/model_migration.md
+++ b/doc/development/ai_features/model_migration.md
@@ -48,9 +48,12 @@ Several factors can impact migration timelines:
- Communicate conservative timelines externally while working to deliver faster
- Prioritize system stability over speed of deployment
-NOTE:
+{{< alert type="note" >}}
+
While some migrations can technically be completed quickly, we typically plan for longer timelines to ensure proper testing and staged rollouts. This approach helps maintain system stability and reliability.
+{{< /alert >}}
+
## Scope
Applicable to all AI model-related teams at GitLab. We currently support using Anthropic and Google Vertex models. Support for AWS Bedrock models is proposed in [issue 498119](https://gitlab.com/gitlab-org/gitlab/-/issues/498119).
@@ -89,9 +92,12 @@ Before starting a model migration:
- Ensure you have access to testing environments and monitoring tools
- Complete model evaluation using the [Prompt Library](https://gitlab.com/gitlab-org/modelops/ai-model-validation-and-research/ai-evaluation/prompt-library/-/blob/main/doc/how-to/run_duo_chat_eval.md)
-NOTE:
+{{< alert type="note" >}}
+
Documentation of model changes is crucial for tracking the impact of migrations and helping with future troubleshooting. Always create an issue to track these changes before beginning the migration process.
+{{< /alert >}}
+
## Migration Tasks
### Migration Tasks for Anthropic Model
@@ -112,9 +118,12 @@ Note: While we're moving toward AI gateway holding the prompts, feature flag imp
For implementing feature flags, refer to our [Feature Flags Development Guidelines](../feature_flags/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
Feature flag implementations will affect self-hosted cloud-connected customers. These customers won't receive the model upgrade until the feature flag is removed from the AI gateway codebase, as they won't have access to the new GitLab release.
+{{< /alert >}}
+
### Model Selection Implementation
The model selection logic should be implemented in:
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
index c060bc43788e543136e08b7c8d5717774d1e6069..102a5bf0e180e18e23c9fc218ab6ba4ef9320650 100644
--- a/doc/development/api_graphql_styleguide.md
+++ b/doc/development/api_graphql_styleguide.md
@@ -378,9 +378,9 @@ This is summarized in the following table:
| Field purpose | Use `GraphQL::Types::ID`? |
|---------------|---------------------------|
-| Full path | **{check-circle}** Yes |
-| Database ID | **{dotted-circle}** No |
-| IID | **{dotted-circle}** No |
+| Full path | {{< icon name="check-circle" >}} Yes |
+| Database ID | {{< icon name="dotted-circle" >}} No |
+| IID | {{< icon name="dotted-circle" >}} No |
### `markdown_field`
@@ -419,9 +419,12 @@ This can be overridden by passing a `description:` argument.
### Connection types
-NOTE:
+{{< alert type="note" >}}
+
For specifics on implementation, see [Pagination implementation](#pagination-implementation).
+{{< /alert >}}
+
GraphQL uses [cursor based pagination](https://graphql.org/learn/pagination/#pagination-and-edges)
to expose collections of items. This provides the clients with a lot
of flexibility while also allowing the backend to use different
@@ -530,11 +533,14 @@ returned per page if no limiting arguments (`first:` or `last:`) are provided by
The `max_page_size` argument can be used to specify a different page size limit
for a connection.
-WARNING:
+{{< alert type="warning" >}}
+
It's better to change the frontend client, or product requirements, to not need large amounts of
records per page than it is to raise the `max_page_size`, as the default is set to ensure
the GraphQL API remains performant.
+{{< /alert >}}
+
For example:
```ruby
@@ -653,7 +659,8 @@ This can be done in a resolver, in the
type, or even in a model method, depending on your preference and
situation.
-NOTE:
+{{< alert type="note" >}}
+
It's recommended that you also [mark the item as an experiment](#mark-schema-items-as-experiments) while it is behind a feature flag.
This signals to consumers of the public GraphQL API that the field is not
meant to be used yet.
@@ -661,6 +668,8 @@ You can also
[change or remove experimental items at any time](#breaking-change-exemptions) without needing to deprecate them. When the flag is removed, "release"
the schema item by removing its `experiment` property to make it public.
+{{< /alert >}}
+
### Descriptions for feature-flagged items
When using a feature flag to toggle the value or behavior of a schema item, the
@@ -817,12 +826,15 @@ change would typically constitute a breaking change.
To continue to support clients using the old Global ID argument, we add a deprecation
to `Gitlab::GlobalId::Deprecations`.
-NOTE:
+{{< alert type="note" >}}
+
If the Global ID is _only_ [exposed as a field](#exposing-global-ids) then we do not need to
deprecate it. We consider the change to the way a Global ID is expressed in a field to be
backwards-compatible. We expect that clients don't parse these values: they are meant to
be treated as opaque tokens, and any structure in them is incidental and not to be relied on.
+{{< /alert >}}
+
**Example scenario:**
This example scenario is based on this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62645).
@@ -893,13 +905,16 @@ The API also accepts these types in the query signature for the argument:
- `PrometheusServiceID`
- `IntegrationsPrometheusID`
-NOTE:
+{{< alert type="note" >}}
+
Although queries that use the old type (`PrometheusServiceID` in this example) are
considered valid and executable by the API, validator tools consider them to be invalid.
They are considered invalid because we are deprecating using a bespoke method outside of the
[`@deprecated` directive](https://spec.graphql.org/June2018/#sec--deprecated), so validators are not
aware of the support.
+{{< /alert >}}
+
The documentation mentions that the old Global ID style is now deprecated.
## Mark schema items as experiments
@@ -912,10 +927,13 @@ An item marked as an experiment is
removed at any time without notice. Mark an item as an experiment when it is subject to
change and not ready for public use.
-NOTE:
+{{< alert type="note" >}}
+
Only mark new items as an experiment. Never mark existing items
as an experiment because they're already public.
+{{< /alert >}}
+
To mark a schema item as an experiment, use the `experiment:` keyword.
You must provide the `milestone:` that introduced the experimental item.
@@ -1971,9 +1989,12 @@ to deliver the messages over websockets.
When a client subscribes to a subscription, we store their query in-memory in Puma workers. Then when the subscription is triggered,
the Puma workers execute the stored GraphQL queries and push the results to the clients.
-NOTE:
+{{< alert type="note" >}}
+
We cannot test subscriptions using GraphiQL, because they require an Action Cable client, which GraphiQL does not support at the moment.
+{{< /alert >}}
+
### Building subscriptions
All fields under `Types::SubscriptionType` are subscriptions that clients can subscribe to. These fields require a subscription class,
@@ -2282,10 +2303,13 @@ resolve(described_class, obj: project, ctx: { current_user: current_user })
### Writing unit tests (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
Avoid writing unit tests if the same thing can be tested with
a full GraphQL request.
+{{< /alert >}}
+
Before creating unit tests, review the following examples:
- [`spec/graphql/resolvers/users_resolver_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/graphql/resolvers/users_resolver_spec.rb)
diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md
index 1578dabfd4ecb581d86d5adf53ac0ffb1033224a..8fba94c7ff4f9695baec71c13a66f7718672d6d8 100644
--- a/doc/development/api_styleguide.md
+++ b/doc/development/api_styleguide.md
@@ -193,10 +193,13 @@ User.create(params) # imagine the user submitted `admin=1`... :)
User.create(declared(params, include_parent_namespaces: false).to_h)
```
-NOTE:
+{{< alert type="note" >}}
+
`declared(params)` return a `Hashie::Mash` object, on which you must
call `.to_h`.
+{{< /alert >}}
+
But we can use `params[key]` directly when we access single elements.
For instance:
diff --git a/doc/development/application_slis/rails_request.md b/doc/development/application_slis/rails_request.md
index a0e412a7b4990ce3ff35d8dae3fb9fdf89590eb6..75623863e73aacc6531e282420974b9aebad23d0 100644
--- a/doc/development/application_slis/rails_request.md
+++ b/doc/development/application_slis/rails_request.md
@@ -5,10 +5,13 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Rails request SLIs (service level indicators)
---
-NOTE:
+{{< alert type="note" >}}
+
This SLI is used for service monitoring. But not for [error budgets for stage groups](../stage_group_observability/_index.md#error-budget)
by default.
+{{< /alert >}}
+
The request Apdex SLI and the error rate SLI are [SLIs defined in the application](_index.md).
The request Apdex measures the duration of successful requests as an indicator for
@@ -254,9 +257,12 @@ specify do
end
```
-WARNING:
+{{< alert type="warning" >}}
+
We can't specify the urgency at the namespace level. The directive is ignored when doing so.
+{{< /alert >}}
+
### Error budget attribution and ownership
This SLI is used for service level monitoring. It feeds into the
diff --git a/doc/development/application_slis/sidekiq_execution.md b/doc/development/application_slis/sidekiq_execution.md
index 5bab52738cca48cfc84656b3a77e2e24866b1929..7aed2fcd07bad311e87ec44679b96eb1c17d9df7 100644
--- a/doc/development/application_slis/sidekiq_execution.md
+++ b/doc/development/application_slis/sidekiq_execution.md
@@ -5,12 +5,19 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Sidekiq execution SLIs (service level indicators)
---
-> - [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/700) in GitLab 16.0. This version of Sidekiq execution SLIs replaces the old version of the SLI where you can now drill down by workers in the [Application SLI Violations dashboard](https://dashboards.gitlab.net/d/general-application-sli-violations/general-application-sli-violations?orgId=1&var-PROMETHEUS_DS=Global&var-environment=gprd&var-stage=main&var-product_stage=All&var-stage_group=All&var-component=sidekiq_execution) for stage groups.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/700) in GitLab 16.0. This version of Sidekiq execution SLIs replaces the old version of the SLI where you can now drill down by workers in the [Application SLI Violations dashboard](https://dashboards.gitlab.net/d/general-application-sli-violations/general-application-sli-violations?orgId=1&var-PROMETHEUS_DS=Global&var-environment=gprd&var-stage=main&var-product_stage=All&var-stage_group=All&var-component=sidekiq_execution) for stage groups.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
This SLI is used for service monitoring. But not for [error budgets for stage groups](../stage_group_observability/_index.md#error-budget)
by default.
+{{< /alert >}}
+
The Sidekiq execution Apdex measures the duration of successful jobs completion as an indicator for
application performance.
diff --git a/doc/development/audit_event_guide/_index.md b/doc/development/audit_event_guide/_index.md
index f2d37dcdf1e0b920df085f3c8da313be66272d13..458a0b4400c49546fb5a6c8e6c7888d82117f76d 100644
--- a/doc/development/audit_event_guide/_index.md
+++ b/doc/development/audit_event_guide/_index.md
@@ -196,7 +196,11 @@ In addition to recording to the database, we also write these events to
## Event type definitions
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367847) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367847) in GitLab 15.4.
+
+{{< /history >}}
All new audit events must have a type definition stored in `config/audit_events/types/` or `ee/config/audit_events/types/` that contains a single source of truth for every auditable event in GitLab.
diff --git a/doc/development/avoiding_required_stops.md b/doc/development/avoiding_required_stops.md
index 0ad8b3e6f86e7359aabe503aaa796cdd4953aba6..009990eccb8855a7ab431caad22dd1b1a293ebb0 100644
--- a/doc/development/avoiding_required_stops.md
+++ b/doc/development/avoiding_required_stops.md
@@ -71,11 +71,14 @@ zero-downtime upgrades. However, the **contract** phase will likely introduce
a required stop when a migration/code change is introduced that requires
that background migrations have completed before running or loading.
-WARNING:
+{{< alert type="warning" >}}
+
If you're considering adding or removing a migration, or introducing code that
assumes that migrations have completed in a given release, first review
the database-related documentation on [required stops](database/required_stops.md).
+{{< /alert >}}
+
#### Examples
- GitLab `12.1`: Introduced a background migration changing `merge_status` in
diff --git a/doc/development/backup_and_restore/backup_gitlab.md b/doc/development/backup_and_restore/backup_gitlab.md
index ef1620cec25fad809eed69e14e69b30d1a7e2af0..2273c627034501338e04807240a0f2d09dc15188 100644
--- a/doc/development/backup_and_restore/backup_gitlab.md
+++ b/doc/development/backup_and_restore/backup_gitlab.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: How GitLab backups work?
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides recommendations for how to create application backups across different installation types and different hosting architectures. We provide simple tools to create a point-in-time application backup, as well as specialized documentation for how to handle complex Cloud-based installation backups.
diff --git a/doc/development/bulk_import.md b/doc/development/bulk_import.md
index 26e4f31788f3d19b1b520b980df32becdd09d123..86e140a8d534b645d252040e3c8cb2aeb20432dd 100644
--- a/doc/development/bulk_import.md
+++ b/doc/development/bulk_import.md
@@ -5,10 +5,13 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Group migration by direct transfer
---
-NOTE:
+{{< alert type="note" >}}
+
To use direct transfer, ensure your GitLab installation is accessible from
[GitLab IP addresses](../user/gitlab_com/_index.md#ip-range) and has a public DNS entry.
+{{< /alert >}}
+
[Group migration by direct transfer](../user/group/import/_index.md) is the
evolution of migrating groups and projects using file exports. The goal is to have an easier way for the user to migrate a whole group,
including projects, from one GitLab instance to another.
diff --git a/doc/development/bulk_imports/contributing.md b/doc/development/bulk_imports/contributing.md
index fa6d3027edfb084ace1f93e5d1cd018861e9a3f1..712552f3f7823612d03ca7d82fd6bb916d6397c2 100644
--- a/doc/development/bulk_imports/contributing.md
+++ b/doc/development/bulk_imports/contributing.md
@@ -13,9 +13,12 @@ At a high level, to add a new relation to the direct transfer importer, you must
1. Add a label for the newly created relation to display in the UI.
1. Ensure sufficient test coverage.
-NOTE:
+{{< alert type="note" >}}
+
To mitigate the risk of introducing bugs and performance issues, newly added relations should be put behind a feature flag.
+{{< /alert >}}
+
## Export from source
There are a few types of relations we export:
@@ -43,10 +46,13 @@ For example, let's say we have a new `Project` association called `documents`. T
#### Add it to `import_export.yml` file
-NOTE:
+{{< alert type="note" >}}
+
Associations listed in this file are imported from top to bottom. If you have an association that is order-dependent, put the dependencies before the
associations that require them. For example, documents must be imported before merge requests, otherwise they are not valid.
+{{< /alert >}}
+
1. Add your association to `tree.project` within the `import_export.yml`.
```diff
@@ -63,10 +69,13 @@ associations that require them. For example, documents must be imported before m
- :user
```
- NOTE:
- If your association is relates to an Enterprise Edition-only feature, add it to the `ee.tree.project` tree at the end of the file so that it is only exported
+ {{< alert type="note" >}}
+
+If your association is relates to an Enterprise Edition-only feature, add it to the `ee.tree.project` tree at the end of the file so that it is only exported
and imported in Enterprise Edition instances of GitLab.
+ {{< /alert >}}
+
If your association doesn't need to include any sub-relations, then this is enough. But if it needs more sub-relations to be included (for example, notes),
you must list them out. Let's say documents can have notes (with award emojis on notes) and award emojis (on documents), which we want to migrate. In this
case, our relation becomes the following:
@@ -281,9 +290,12 @@ We specified:
- `minimum_source_version: '16.11.0'`. Because we introduced `documents` relation for exports in this milestone, it's not available in previous GitLab versions. Therefore
so this pipeline only runs if source version is 16.11 or later.
-NOTE:
+{{< alert type="note" >}}
+
If a relation is deprecated and need only to run the pipeline up to a certain version, we can specify `maximum_source_version` attribute.
+{{< /alert >}}
+
#### Covering a pipeline with tests
Because we already covered the export side with tests, we must do the same for the import side. For the direct transfer importer, each pipeline has a separate spec
diff --git a/doc/development/cached_queries.md b/doc/development/cached_queries.md
index 905f13a486262ee652ad6a18d5e1f73496d5032d..eec62616629fa611882094678b5958b6fe62ad15 100644
--- a/doc/development/cached_queries.md
+++ b/doc/development/cached_queries.md
@@ -92,7 +92,7 @@ below the query. You can see multiple duplicate cached queries in this modal win
-Select the ellipsis (**{ellipsis_h}**) to expand the actual stack trace:
+Select the ellipsis ({{< icon name="ellipsis_h" >}}) to expand the actual stack trace:
```ruby
[
diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md
index 03a0ff3c8c3275c1b9c4e3de0bb8874a497e31d6..ea487a979dddec05f912fbee6370916549c4575e 100644
--- a/doc/development/cascading_settings.md
+++ b/doc/development/cascading_settings.md
@@ -225,7 +225,7 @@ Renders the mount element needed to initialize the JavaScript used to display th
[`initCascadingSettingsLockTooltips`](https://gitlab.com/gitlab-org/gitlab/-/blob/acb2ef4dbbd06f93615e8e6a1c0a78e7ebe20441/app/assets/javascripts/namespaces/cascading_settings/index.js#L4)
-Initializes the JavaScript needed to display the tooltip when hovering over the lock icon (**{lock}**).
+Initializes the JavaScript needed to display the tooltip when hovering over the lock icon ({{< icon name="lock" >}}).
This function should be imported and called in the [page-specific JavaScript](fe_guide/performance.md#page-specific-javascript).
### Put it all together
diff --git a/doc/development/cells/application_settings_analysis.md b/doc/development/cells/application_settings_analysis.md
index 3d7b5d4897751f35e6a4023c6cb356bf15feac17..fd7d91d4038855459afe332648b98f17ba74b4e4 100644
--- a/doc/development/cells/application_settings_analysis.md
+++ b/doc/development/cells/application_settings_analysis.md
@@ -2,8 +2,8 @@
stage: Tenant Scale
group: Cells Infrastructure
info: Analysis of Application Settings for Cells 1.0.
+title: Application Settings analysis
---
-# Application Settings analysis
## Statistics
diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md
index 577d72dea30bbb8c501cbd8fd549b3a34f6a7339..ec48067aaf52b9a5e5f56511f924a13be5f5045f 100644
--- a/doc/development/chaos_endpoints.md
+++ b/doc/development/chaos_endpoints.md
@@ -27,10 +27,13 @@ Currently, there are four endpoints for simulating the following conditions:
For obvious reasons, these endpoints are not enabled by default on `production`.
They are enabled by default on **development** environments.
-WARNING:
+{{< alert type="warning" >}}
+
It is required that you secure access to the chaos endpoints using a secret token.
You should not enable them in production unless you absolutely know what you're doing.
+{{< /alert >}}
+
A secret token can be set through the `GITLAB_CHAOS_SECRET` environment variable.
For example, when using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit)
this can be done with the following command:
diff --git a/doc/development/cicd/_index.md b/doc/development/cicd/_index.md
index febfadc4abea46a6f19295da282d21dc9eb4c6af..9e48d9aa5e07e6bf8f4de9254a0ec076249e2918 100644
--- a/doc/development/cicd/_index.md
+++ b/doc/development/cicd/_index.md
@@ -161,9 +161,12 @@ A job with the `created` state isn't seen by the runner yet. To make it possible
When the runner is connected, it requests the next `pending` job to run by polling the server continuously.
-NOTE:
+{{< alert type="note" >}}
+
API endpoints used by the runner to interact with GitLab are defined in [`lib/api/ci/runner.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/ci/runner.rb)
+{{< /alert >}}
+
After the server receives the request it selects a `pending` job based on the [`Ci::RegisterJobService` algorithm](#ciregisterjobservice), then assigns and sends the job to the runner.
Once all jobs are completed for the current stage, the server "unlocks" all the jobs from the next stage by changing their state to `pending`. These can now be picked by the scheduling algorithm when the runner requests new jobs, and continues like this until all stages are completed.
@@ -197,10 +200,13 @@ There are 3 top level queries that this service uses to gather the majority of t
This list of jobs is then filtered further by matching tags between job and runner tags.
-NOTE:
+{{< alert type="note" >}}
+
If a job contains tags, the runner doesn't pick the job if it does not match **all** the tags.
The runner may have more tags than defined for the job, but not vice-versa.
+{{< /alert >}}
+
Finally if the runner can only pick jobs that are tagged, all untagged jobs are filtered out.
At this point we loop through remaining `pending` jobs and we try to assign the first job that the runner "can pick" based on additional policies. For example, runners marked as `protected` can only pick jobs that run against protected branches (such as production deployments).
@@ -272,7 +278,11 @@ See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16111) for the fu
## Compute quota
-> - [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" and "compute minutes" in GitLab 16.1.
+{{< history >}}
+
+- [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" and "compute minutes" in GitLab 16.1.
+
+{{< /history >}}
This diagram shows how the [Compute quota](../../ci/pipelines/compute_minutes.md)
feature and its components work.
diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md
index 2fe0b7e5e485b550c7f508e44d03fb86f82c117d..5710bb61d367fd1ef377bdcdf3cffde1568405e4 100644
--- a/doc/development/cicd/cicd_reference_documentation_guide.md
+++ b/doc/development/cicd/cicd_reference_documentation_guide.md
@@ -165,9 +165,9 @@ For example:
```markdown
**Related topics**:
-- You can specify a [fallback cache key](../caching/index.md#use-a-fallback-cache-key)
+- You can specify a [fallback cache key](../caching/_index.md#use-a-fallback-cache-key)
to use if the specified `cache:key` is not found.
-- You can [use multiple cache keys](../caching/index.md#use-multiple-caches) in a single job.
-- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more
+- You can [use multiple cache keys](../caching/_index.md#use-multiple-caches) in a single job.
+- See the [common `cache` use cases](../caching/_index.md#common-use-cases-for-caches) for more
`cache:key` examples.
```
diff --git a/doc/development/cicd/components.md b/doc/development/cicd/components.md
index 4dd1da2e3bc42e736d01f0498273c99c3187196b..f79455099f7ac42d14446cf334958651261e3302 100644
--- a/doc/development/cicd/components.md
+++ b/doc/development/cicd/components.md
@@ -40,11 +40,14 @@ to a set of owners before the first version gets published to the catalog.
The `README.md` file in the project repository must indicate the main owners of the project so that
they can be contacted by the wider community if needed.
-NOTE:
+{{< alert type="note" >}}
+
If a set of project owners cannot be guaranteed or the components cannot be dogfooded, we strongly recommend
not creating an official GitLab component project and instead let the wider community fulfill the demand
in the catalog.
+{{< /alert >}}
+
## Development process
1. Create a project under [`gitlab.com/components`](https://gitlab.com/components)
diff --git a/doc/development/cicd/pipeline_wizard.md b/doc/development/cicd/pipeline_wizard.md
index b85a761b11b2e029861b5af79d79be94f40b4180..75ff2052bda220da5aaa8b98dd4d4bb3e7a8f4f7 100644
--- a/doc/development/cicd/pipeline_wizard.md
+++ b/doc/development/cicd/pipeline_wizard.md
@@ -156,11 +156,11 @@ In the root element of the template file, you can define the following propertie
| Name | Required | Type | Description |
|---------------|------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `id` | **{check-circle}** Yes | string | A unique template ID. This ID should follow a namespacing pattern, with a forward slash `/` as separator. Templates committed to GitLab source code should always begin with `gitlab`. For example: `gitlab/my-template` |
-| `title` | **{check-circle}** Yes | string | The page title as displayed to the user. It becomes an `h1` heading above the wizard. |
-| `description` | **{check-circle}** Yes | string | The page description as displayed to the user. |
-| `filename` | **{dotted-circle}** No | string | The name of the file that is being generated. Defaults to `.gitlab-ci.yml`. |
-| `steps` | **{check-circle}** Yes | list | A list of [step definitions](#step-reference). |
+| `id` | {{< icon name="check-circle" >}} Yes | string | A unique template ID. This ID should follow a namespacing pattern, with a forward slash `/` as separator. Templates committed to GitLab source code should always begin with `gitlab`. For example: `gitlab/my-template` |
+| `title` | {{< icon name="check-circle" >}} Yes | string | The page title as displayed to the user. It becomes an `h1` heading above the wizard. |
+| `description` | {{< icon name="check-circle" >}} Yes | string | The page description as displayed to the user. |
+| `filename` | {{< icon name="dotted-circle" >}} No | string | The name of the file that is being generated. Defaults to `.gitlab-ci.yml`. |
+| `steps` | {{< icon name="check-circle" >}} Yes | list | A list of [step definitions](#step-reference). |
### `step` Reference
@@ -171,8 +171,8 @@ Steps include two properties:
| Name | Required | Type | Description |
|------------|------------------------|------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `template` | **{check-circle}** Yes | map | The raw YAML to deep-merge into the final `.gitlab-ci.yml`. This template section can contain variables denoted by a `$` sign that is replaced with the values from the input fields. |
-| `inputs` | **{check-circle}** Yes | list | A list of [input definitions](#input-reference). |
+| `template` | {{< icon name="check-circle" >}} Yes | map | The raw YAML to deep-merge into the final `.gitlab-ci.yml`. This template section can contain variables denoted by a `$` sign that is replaced with the values from the input fields. |
+| `inputs` | {{< icon name="check-circle" >}} Yes | list | A list of [input definitions](#input-reference). |
### `input` Reference
@@ -191,9 +191,9 @@ are dependent on the widget being used:
| Name | Required | Type | Description |
|----------|------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------|
-| `label` | **{check-circle}** Yes | string | The label for the input field. |
-| `widget` | **{check-circle}** Yes | string | The [widget](#widgets) type to use for this input. |
-| `target` | **{dotted-circle}** No | string | The variable name inside the step's template that should be replaced with the value of the input field, for example `$FOO`. |
+| `label` | {{< icon name="check-circle" >}} Yes | string | The label for the input field. |
+| `widget` | {{< icon name="check-circle" >}} Yes | string | The [widget](#widgets) type to use for this input. |
+| `target` | {{< icon name="dotted-circle" >}} No | string | The variable name inside the step's template that should be replaced with the value of the input field, for example `$FOO`. |
### Widgets
@@ -203,14 +203,14 @@ Use as `widget: text`. This inserts a `string` in the YAML file.
| Name | Required | Type | Description |
|-------------------|------------------------|---------|-----------------------|
-| `label` | **{check-circle}** Yes | string | The label for the input field. |
-| `description` | **{dotted-circle}** No | string | Help text related to the input field. |
-| `required` | **{dotted-circle}** No | boolean | Whether or not the user must provide a value before proceeding to the next step. `false` if not defined. |
-| `placeholder` | **{dotted-circle}** No | string | A placeholder for the input field. |
-| `pattern` | **{dotted-circle}** No | string | A regular expression that the user's input must match before they can proceed to the next step. |
-| `invalidFeedback` | **{dotted-circle}** No | string | Help text displayed when the pattern validation fails. |
-| `default` | **{dotted-circle}** No | string | The default value for the field. |
-| `id` | **{dotted-circle}** No | string | The input field ID is usually autogenerated but can be overridden by providing this property. |
+| `label` | {{< icon name="check-circle" >}} Yes | string | The label for the input field. |
+| `description` | {{< icon name="dotted-circle" >}} No | string | Help text related to the input field. |
+| `required` | {{< icon name="dotted-circle" >}} No | boolean | Whether or not the user must provide a value before proceeding to the next step. `false` if not defined. |
+| `placeholder` | {{< icon name="dotted-circle" >}} No | string | A placeholder for the input field. |
+| `pattern` | {{< icon name="dotted-circle" >}} No | string | A regular expression that the user's input must match before they can proceed to the next step. |
+| `invalidFeedback` | {{< icon name="dotted-circle" >}} No | string | Help text displayed when the pattern validation fails. |
+| `default` | {{< icon name="dotted-circle" >}} No | string | The default value for the field. |
+| `id` | {{< icon name="dotted-circle" >}} No | string | The input field ID is usually autogenerated but can be overridden by providing this property. |
#### List
@@ -218,14 +218,14 @@ Use as `widget: list`. This inserts a `list` in the YAML file.
| Name | Required | Type | Description |
|-------------------|------------------------|---------|-----------------------|
-| `label` | **{check-circle}** Yes | string | The label for the input field. |
-| `description` | **{dotted-circle}** No | string | Help text related to the input field. |
-| `required` | **{dotted-circle}** No | boolean | Whether or not the user must provide a value before proceeding to the next step. `false` if not defined. |
-| `placeholder` | **{dotted-circle}** No | string | A placeholder for the input field. |
-| `pattern` | **{dotted-circle}** No | string | A regular expression that the user's input must match before they can proceed to the next step. |
-| `invalidFeedback` | **{dotted-circle}** No | string | Help text displayed when the pattern validation fails. |
-| `default` | **{dotted-circle}** No | list | The default value for the list |
-| `id` | **{dotted-circle}** No | string | The input field ID is usually autogenerated but can be overridden by providing this property. |
+| `label` | {{< icon name="check-circle" >}} Yes | string | The label for the input field. |
+| `description` | {{< icon name="dotted-circle" >}} No | string | Help text related to the input field. |
+| `required` | {{< icon name="dotted-circle" >}} No | boolean | Whether or not the user must provide a value before proceeding to the next step. `false` if not defined. |
+| `placeholder` | {{< icon name="dotted-circle" >}} No | string | A placeholder for the input field. |
+| `pattern` | {{< icon name="dotted-circle" >}} No | string | A regular expression that the user's input must match before they can proceed to the next step. |
+| `invalidFeedback` | {{< icon name="dotted-circle" >}} No | string | Help text displayed when the pattern validation fails. |
+| `default` | {{< icon name="dotted-circle" >}} No | list | The default value for the list |
+| `id` | {{< icon name="dotted-circle" >}} No | string | The input field ID is usually autogenerated but can be overridden by providing this property. |
#### Checklist
@@ -234,13 +234,13 @@ be checked before proceeding to the next step.
| Name | Required | Type | Description |
|---------|------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `title` | **{dotted-circle}** No | string | A title above the checklist items. |
-| `items` | **{dotted-circle}** No | list | A list of items that need to be checked. Each item corresponds to one checkbox, and can be a string or [checklist item](#checklist-item). |
+| `title` | {{< icon name="dotted-circle" >}} No | string | A title above the checklist items. |
+| `items` | {{< icon name="dotted-circle" >}} No | list | A list of items that need to be checked. Each item corresponds to one checkbox, and can be a string or [checklist item](#checklist-item). |
##### Checklist Item
| Name | Required | Type | Description |
|--------|------------------------|---------|-----------------------------------------|
-| `text` | **{check-circle}** Yes | string | A title above the checklist items. |
-| `help` | **{dotted-circle}** No | string | Help text explaining the item. |
-| `id` | **{dotted-circle}** No | string | The input field ID is usually autogenerated but can be overridden by providing this property. |
+| `text` | {{< icon name="check-circle" >}} Yes | string | A title above the checklist items. |
+| `help` | {{< icon name="dotted-circle" >}} No | string | Help text explaining the item. |
+| `id` | {{< icon name="dotted-circle" >}} No | string | The input field ID is usually autogenerated but can be overridden by providing this property. |
diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md
index ec8cf57236aa7f3d28b17434c54f97e9fce6d422..8492c9eab1192bd17ed7fedb9c93f533859a3179 100644
--- a/doc/development/cicd/templates.md
+++ b/doc/development/cicd/templates.md
@@ -5,7 +5,8 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Development guide for GitLab CI/CD templates (Deprecated)
---
-NOTE:
+{{< alert type="note" >}}
+
With the introduction of the [CI/CD Catalog](../../ci/components/_index.md#cicd-catalog),
GitLab is no longer accepting contributions of new CI/CD templates to the codebase. Instead,
we encourage team members to create [CI/CD components](../../ci/components/_index.md)
@@ -16,6 +17,8 @@ If no component exists that matches the CI/CD template yet, consider [creating t
This ensures that template and component functionality remain in sync, aligning with
our new development practices.
+{{< /alert >}}
+
This document explains how to develop [GitLab CI/CD templates](../../ci/examples/_index.md#cicd-templates).
## Requirements for CI/CD templates
diff --git a/doc/development/code_intelligence/_index.md b/doc/development/code_intelligence/_index.md
index a941d8cdd436e634208bf5ac35ba8724f1c90e28..a81194c408216d89741d336df9535e3570c314b2 100644
--- a/doc/development/code_intelligence/_index.md
+++ b/doc/development/code_intelligence/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Review
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Developer documentation for the Code Intelligence feature."
+description: Developer documentation for the Code Intelligence feature.
title: Code intelligence development guidelines
---
diff --git a/doc/development/code_owners/_index.md b/doc/development/code_owners/_index.md
index f89d2460b13cdff60c6e5fc4e47d6a7b5bc48da6..3b5f99ce3997a5c6306eb93b3ae43c85784ada6c 100644
--- a/doc/development/code_owners/_index.md
+++ b/doc/development/code_owners/_index.md
@@ -5,7 +5,11 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Code Owners development guidelines
---
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219916) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219916) in GitLab 15.10.
+
+{{< /history >}}
This document was created to help contributors understand the code design of
[Code Owners](../../user/project/codeowners/_index.md). You should read this
@@ -16,10 +20,13 @@ designed, as code can change often. To understand how a specific part of the
feature works, view the code and the specs. The details here explain how the
major components of the Code Owners feature work.
-NOTE:
+{{< alert type="note" >}}
+
This document should be updated when parts of the codebase referenced in this
document are updated, removed, or new parts are added.
+{{< /alert >}}
+
## Business logic
All of the business logic for code owners is located in the `Gitlab::CodeOwners`
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index 8341be9b46df2608f50383315a1bf3c87efb25f1..7091a2a12254a6d3bbb5eb51bcd1207828d602bd 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -99,9 +99,12 @@ To find a domain expert:
### Reviewer roulette
-NOTE:
+{{< alert type="note" >}}
+
Reviewer roulette is an internal tool for use on GitLab.com, and not available for use on customer installations.
+{{< /alert >}}
+
The [Danger bot](dangerbot.md) randomly picks a reviewer and a maintainer for
each area of the codebase that your merge request seems to touch. It makes
**recommendations** for developer reviewers and you should override it if you think someone else is a better
@@ -583,7 +586,7 @@ For example, when a merge request has both `backend` and `frontend` concerns, yo
You can also use `workflow::ready for review` label. That means that your merge request is ready to be reviewed and any reviewer can pick it. It is recommended to use that label only if there isn't time pressure and make sure the merge request is assigned to a reviewer.
-When re-requesting a review, click the [**Re-request a review** icon](../user/project/merge_requests/reviews/_index.md#re-request-a-review) (**{redo}**) next to the reviewer's name, or use the `/request_review @user` quick action.
+When re-requesting a review, click the [**Re-request a review** icon](../user/project/merge_requests/reviews/_index.md#re-request-a-review) ({{< icon name="redo" >}}) next to the reviewer's name, or use the `/request_review @user` quick action.
This ensures the merge request appears in the reviewer's **Reviews requested** section of their merge request homepage.
When your merge request receives an approval from the first reviewer it can be passed to a maintainer. You should default to choosing a maintainer with [domain expertise](#domain-experts), and otherwise follow the Reviewer Roulette recommendation or use the label `ready for merge`.
@@ -630,9 +633,12 @@ experience, refactors the existing code). Then:
"Looks good to me", or "Just a couple things to address."
- Let the author know if changes are required following your review.
-WARNING:
+{{< alert type="warning" >}}
+
**If the merge request is from a fork, also check the [additional guidelines for community contributions](#community-contributions).**
+{{< /alert >}}
+
### Merging a merge request
Before taking the decision to merge:
@@ -679,9 +685,12 @@ when rebasing from the UI or with the [`/rebase` quick action](../user/project/q
When ready to merge:
-WARNING:
+{{< alert type="warning" >}}
+
**If the merge request is from a fork, also check the [additional guidelines for community contributions](#community-contributions).**
+{{< /alert >}}
+
- Consider using the [Squash and merge](../user/project/merge_requests/squash_and_merge.md)
feature when the merge request has a lot of commits.
When merging code, a maintainer should only use the squash feature if the
@@ -713,10 +722,13 @@ Merge Results against the latest `main` at the time of the pipeline creation.
### Community contributions
-WARNING:
+{{< alert type="warning" >}}
+
**Review all changes thoroughly for malicious code before starting a
[merged results pipeline](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project).**
+{{< /alert >}}
+
When reviewing merge requests added by wider community contributors:
- Pay particular attention to new dependencies and dependency updates, such as Ruby gems and Node packages.
diff --git a/doc/development/code_suggestions/_index.md b/doc/development/code_suggestions/_index.md
index d700888e75b9e7a6e52ce0df323020ea57299b6f..b86397d54dbdd1adb92edc349ff2dc489b1e748b 100644
--- a/doc/development/code_suggestions/_index.md
+++ b/doc/development/code_suggestions/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Creation
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Code Suggestions documentation for developers interested in contributing features or bugfixes."
+description: Code Suggestions documentation for developers interested in contributing features or bugfixes.
title: Code Suggestions development guidelines
---
diff --git a/doc/development/contributing/first_contribution/configure-dev-env-gdk-in-a-box.md b/doc/development/contributing/first_contribution/configure-dev-env-gdk-in-a-box.md
index 76802f419191039bbcc6a1ce4f6d4c0b584026a0..eb42968786cffc20d23bf00f4bbf9ab4c30019f4 100644
--- a/doc/development/contributing/first_contribution/configure-dev-env-gdk-in-a-box.md
+++ b/doc/development/contributing/first_contribution/configure-dev-env-gdk-in-a-box.md
@@ -37,9 +37,12 @@ If you prefer to use GDK locally without a VM, use the steps in [Install the GDK
[View a demo video of this step](https://go.gitlab.com/b54mHb).
-NOTE:
+{{< alert type="note" >}}
+
You might need to modify the system configuration (CPU cores and RAM) before starting the virtual machine.
+{{< /alert >}}
+
1. Start the VM (you can minimize UTM or VirtualBox).
1. In VS Code, select **Terminal > New terminal**, then run a `curl` command to add an SSH key to your local `~/.ssh/config`:
@@ -79,7 +82,7 @@ You might need to modify the system configuration (CPU cores and RAM) before sta
## Shut down GDK
-You can select the power icon (**{power}**) to shut down
+You can select the power icon ({{< icon name="power" >}}) to shut down
the virtual machine, or enter the `shutdown` command in the terminal.
Use the password `debian`:
diff --git a/doc/development/contributing/first_contribution/configure-dev-env-gdk.md b/doc/development/contributing/first_contribution/configure-dev-env-gdk.md
index f87a31731c61aaa55b061bdb463935c01d150f86..8bb9225d815dc693b6ef56ddfd726814ff4266c0 100644
--- a/doc/development/contributing/first_contribution/configure-dev-env-gdk.md
+++ b/doc/development/contributing/first_contribution/configure-dev-env-gdk.md
@@ -59,8 +59,11 @@ To install the GDK:
This script clones the GitLab Development Kit (GDK) repository into a new subdirectory, and sets up necessary dependencies using the `asdf` version manager (including Ruby, Node.js, PostgreSQL, Redis, and more).
- NOTE:
- If you're using another version manager for those dependencies, refer to the [troubleshooting section](#error-no-version-is-set-for-command) to avoid conflicts.
+ {{< alert type="note" >}}
+
+If you're using another version manager for those dependencies, refer to the [troubleshooting section](#error-no-version-is-set-for-command) to avoid conflicts.
+
+ {{< /alert >}}
1. For the message `Where would you like to install the GDK? [./gitlab-development-kit]`,
press <kbd>Enter</kbd> to accept the default location.
@@ -137,11 +140,14 @@ For more advanced troubleshooting, continue to the [Troubleshoot GDK](#troublesh
## Troubleshoot GDK
-NOTE:
+{{< alert type="note" >}}
+
For more advanced troubleshooting, see
the [troubleshooting documentation](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/main/doc/troubleshooting)
and the [#contribute channel on Discord](https://discord.com/channels/778180511088640070/997442331202564176).
+{{< /alert >}}
+
If you encounter issues, go to the `gitlab-development-kit/gitlab`
directory and run `gdk doctor`.
diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md
index 36cc9166e497b5480e43ee22a96ca9c238a9a452..1cbc07b2bf4d2eafe04e378ced4239d610758794 100644
--- a/doc/development/contributing/issue_workflow.md
+++ b/doc/development/contributing/issue_workflow.md
@@ -20,9 +20,12 @@ To submit a bug:
- To report a suspected security vulnerability, follow the
[disclosure process on the GitLab.com website](https://about.gitlab.com/security/disclosure/).
-WARNING:
+{{< alert type="warning" >}}
+
Do **not** create publicly viewable issues for suspected security vulnerabilities.
+{{< /alert >}}
+
### Feature proposals
To create a feature proposal, open an issue in the issue tracker using the
diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md
index 511f24e110135d70117a1be1093263aacffe3bb8..812723de9618f059f0780d52732539e4064d067f 100644
--- a/doc/development/contributing/merge_request_workflow.md
+++ b/doc/development/contributing/merge_request_workflow.md
@@ -236,15 +236,19 @@ requirements.
whether reviewing existing rows should be included as an immediate follow-up task
to the merge request.
- NOTE:
+ {{< alert type="note" >}}
+
There isn't a way to know anything about our customers' data on their
[GitLab Self-Managed instances](../../subscriptions/self_managed/_index.md), so keep
that in mind for any data implications with your merge request.
-1. Consider self-managed functionality and upgrade paths. The change should consider both:
+
+ 1. Consider self-managed functionality and upgrade paths. The change should consider both:
- If additional work needs to be done for self-managed availability, and
- If the change requires a [required stop](../database/required_stops.md) when upgrading GitLab versions.
+ {{< /alert >}}
+
Upgrade stops are sometimes requested when a GitLab code change is dependent
upon a background migration being already complete. Ideally, changes causing required
upgrade stops should be held for the next major release, or
diff --git a/doc/development/cookies.md b/doc/development/cookies.md
index 2e7633ec7569288fa723d915dedc43c9f24dab79..4b612ff349d3960590c988e3a6fef492055000b8 100644
--- a/doc/development/cookies.md
+++ b/doc/development/cookies.md
@@ -15,9 +15,12 @@ Ruby on Rails has cookie setting and retrieval [built-in to ActionController](ht
You can [set cookies with options](https://api.rubyonrails.org/v7.1.3.4/classes/ActionDispatch/Cookies.html) such as `:path` , `:expires`, `:domain` , and `:httponly` . Do not change from the defaults for these options unless it is required for the functionality you are implementing.
-WARNING:
+{{< alert type="warning" >}}
+
[Cookies set by GitLab are unset by default when users log out](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/sessions_controller.rb#L104). If you set a cookie with the `:domain` option, that cookie must be unset using the same `:domain` parameter. Otherwise the browser will not actually clear the cookie, and we risk persisting potentially-sensitive data which should have been cleared.
+{{< /alert >}}
+
## Cookies in Frontend Code
Some of our frontend code sets cookies for persisting data during a session, such as dismissing alerts or sidebar position preferences. We use the [`setCookie` and `getCookie` helpers from `common_utils`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/lib/utils/common_utils.js#L697) to apply reasonable defaults to these cookies.
diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md
index cb314d0a9a8c9a57c7a4b8dc52664ed454430813..8d880f38d071a29d23f3903ba9c86d180ac7b1d9 100644
--- a/doc/development/dangerbot.md
+++ b/doc/development/dangerbot.md
@@ -121,9 +121,12 @@ to revert the change before merging!
#### Adding labels via Danger
-NOTE:
+{{< alert type="note" >}}
+
This is applicable to all the projects that use the [`gitlab-dangerfiles` gem](https://rubygems.org/gems/gitlab-dangerfiles).
+{{< /alert >}}
+
Danger is often used to improve MR hygiene by adding labels. Instead of calling the
API directly in your `Dangerfile`, add the labels to `helper.labels_to_add` array (with `helper.labels_to_add << label`
or `helper.labels_to_add.concat(array_of_labels)`.
diff --git a/doc/development/data_seeder.md b/doc/development/data_seeder.md
index 3bc000a37581c09a214d12772fdb8d8ea4f05be7..eb4bfdfb3e786ff88dff709c0d6ba82947166592 100644
--- a/doc/development/data_seeder.md
+++ b/doc/development/data_seeder.md
@@ -75,10 +75,13 @@ To fetch the password for the GitLab instance that was created, execute the foll
docker exec gitlab cat /etc/gitlab/initial_root_password
```
-NOTE:
+{{< alert type="note" >}}
+
If you receive `cat: /etc/gitlab/initialize_root_password: No such file or directory`,
please wait for a bit for GitLab to boot and try again.
+{{< /alert >}}
+
You can then sign in to `http://localhost:8080/users/sign_in` using the credentials: `root / <Password taken from initial_root_password>`
### Seed the data
@@ -118,9 +121,12 @@ Where `:file` is the file path. (This path reflects relative `.rb`, `.yml`, or `
## Linux package Setup
-WARNING:
+{{< alert type="warning" >}}
+
While it is possible to use the Data Seeder with an Linux package installation, **use caution** if you do this when the instance is being used in a production setting.
+{{< /alert >}}
+
Requires Git v2.26.0 or later.
1. Change the working directory to the GitLab installation:
@@ -457,9 +463,12 @@ projects:
Variables:
-NOTE:
+{{< alert type="note" >}}
+
It is not advised, but you may specify variables with spaces. These variables may be referred back to with underscores.
+{{< /alert >}}
+
### Referencing a variable
Given a YAML seed file:
diff --git a/doc/development/database/add_foreign_key_to_existing_column.md b/doc/development/database/add_foreign_key_to_existing_column.md
index 11147bd2e48403d1db02fd67dc8109a2575b3768..0b26b65e45d4c6f0b513c0b87ed77f1f8e869bc2 100644
--- a/doc/development/database/add_foreign_key_to_existing_column.md
+++ b/doc/development/database/add_foreign_key_to_existing_column.md
@@ -122,9 +122,12 @@ end
Validating the foreign key scans the whole table and makes sure that each relation is correct.
Fortunately, this does not lock the source table (`users`) while running.
-NOTE:
+{{< alert type="note" >}}
+
When using [batched background migrations](batched_background_migrations.md), foreign key validation should happen in the next GitLab release.
+{{< /alert >}}
+
Migration file for validating the foreign key:
```ruby
@@ -215,12 +218,15 @@ add the migration as expected for other installations. The below block
demonstrates how to create the second migration for the previous
asynchronous example.
-WARNING:
+{{< alert type="warning" >}}
+
Verify that the foreign key is valid in production before merging a second
migration with `validate_foreign_key`. If the second migration is deployed
before the validation has been executed, the foreign key is validated
synchronously when the second migration executes.
+{{< /alert >}}
+
```ruby
# in db/post_migrate/
diff --git a/doc/development/database/adding_database_indexes.md b/doc/development/database/adding_database_indexes.md
index 634c481e833aa0e2584a8fc573717271b0ebbb29..e766f6fb807713edb1000bfe280f929dad14ffef 100644
--- a/doc/development/database/adding_database_indexes.md
+++ b/doc/development/database/adding_database_indexes.md
@@ -103,9 +103,12 @@ GitLab enforces a limit of **15 indexes** per table. This limitation:
- Reduces maintenance overhead
- Prevents excessive disk space usage
-NOTE:
+{{< alert type="note" >}}
+
If you need to add an index to a table that already has 15 indexes, consider:
+{{< /alert >}}
+
- Removing unused indexes
- Combining existing indexes
- Using a composite index that can serve multiple query patterns
@@ -172,11 +175,14 @@ Use two MRs to create the index in a post-deployment migration and make the appl
- The second MR makes application code changes. It should merge only after the first MR's
post-deployment migrations are executed on GitLab.com.
-NOTE:
+{{< alert type="note" >}}
+
If you can use a feature flag, you might be able to use a single MR
to make the code changes behind the feature flag. Include the post-deployment migration at the same time.
After the post-deployment migration executes, you can enable the feature flag.
+{{< /alert >}}
+
For GitLab.com, we execute post-deployment migrations throughout a single release through continuous integration:
- At some time `t`, a group of merge requests are merged and ready to deploy.
@@ -534,10 +540,13 @@ def down
end
```
-NOTE:
+{{< alert type="note" >}}
+
`prepare_partitioned_async_index` only creates the indexes for partitions asynchronously. It doesn't attach the partition indexes to the partitioned table.
In the [next step for the partitioned table](#create-the-index-synchronously-for-partitioned-table), `add_concurrent_partitioned_index` will not only add the index synchronously but also attach the partition indexes to the partitioned table.
+{{< /alert >}}
+
### Verify the MR was deployed and the index exists in production
1. Verify that the post-deploy migration was executed on GitLab.com using ChatOps with
diff --git a/doc/development/database/avoiding_downtime_in_migrations.md b/doc/development/database/avoiding_downtime_in_migrations.md
index ef44cb00f0cbb872a5f50de2a4ff1857099f4409..564ac82d3d5bb1a80032b8fdf13b869524cd886b 100644
--- a/doc/development/database/avoiding_downtime_in_migrations.md
+++ b/doc/development/database/avoiding_downtime_in_migrations.md
@@ -62,11 +62,14 @@ to ignore the column and subsequently remove the column ignore (which would resu
In this example, the change to ignore the column went into release `12.5`.
-NOTE:
+{{< alert type="note" >}}
+
Ignoring and dropping columns should not occur simultaneously in the same release. Dropping a column before proper ignoring it in the model can cause problems with zero-downtime migrations,
where the running instances can fail trying to look up for the removed column until the Rails schema cache expires. This can be an issue for self-managed customers whom attempt to follow zero-downtime upgrades,
forcing them to explicit restart all running GitLab instances to re-load the updated schema. To avoid this scenario, first, ignore the column (release M), then, drop it in the next release (release M+1).
+{{< /alert >}}
+
### Dropping the column (release M+1)
Continuing our example, dropping the column goes into a _post-deployment_ migration in release `12.6`:
@@ -309,13 +312,16 @@ Example migration:
Changing column defaults is difficult because of how Rails handles values
that are equal to the default.
-NOTE:
+{{< alert type="note" >}}
+
Rails ignores sending the default values to PostgreSQL when inserting records, if the [partial_inserts](https://gitlab.com/gitlab-org/gitlab/-/blob/55ac06c9083434e6c18e0a2aaf8be5f189ef34eb/config/application.rb#L40) config has been enabled. It leaves this task to
the database. When migrations change the default values of the columns, the running application is unaware
of this change due to the schema cache. The application is then under the risk of accidentally writing
wrong data to the database, especially when deploying the new version of the code
long after we run database migrations.
+{{< /alert >}}
+
If running code ever explicitly writes the old default value of a column, you must follow a multi-step
process to prevent Rails replacing the old default with the new default in INSERT queries that explicitly
specify the old default.
diff --git a/doc/development/database/batched_background_migrations.md b/doc/development/database/batched_background_migrations.md
index 2cd77b54793b19328e7c7854b69bcc8d943788ab..48d3ac01efd5531460e6cb3a9d852e6d7832d0df 100644
--- a/doc/development/database/batched_background_migrations.md
+++ b/doc/development/database/batched_background_migrations.md
@@ -1,7 +1,7 @@
---
stage: Data Access
group: Database Frameworks
-info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines"
+info: 'See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines'
title: Batched background migrations
---
@@ -11,12 +11,17 @@ in our guidelines. For example, you can use batched background
migrations to migrate data that's stored in a single JSON column
to a separate table instead.
-NOTE:
+{{< alert type="note" >}}
+
Batched background migrations replaced the legacy background migrations framework.
Check that documentation in reference to any changes involving that framework.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The batched background migrations framework has ChatOps support. Using ChatOps, GitLab engineers can interact with the batched background migrations present in the system.
+{{< /alert >}}
## When to use batched background migrations
@@ -259,10 +264,13 @@ queue_batched_background_migration(
)
```
-NOTE:
+{{< alert type="note" >}}
+
This helper raises an error if the number of provided job arguments does not match
the number of [job arguments](#use-job-arguments) defined in `JOB_CLASS_NAME`.
+{{< /alert >}}
+
Make sure the newly-created data is either migrated, or
saved in both the old and new version upon creation. Removals in
turn can be handled by defining foreign keys with cascading deletes.
@@ -305,11 +313,14 @@ to future schema changes.
See the below [Examples](#examples) for specific details on what the actual
migration code should be.
-NOTE:
+{{< alert type="note" >}}
+
If the migration is being finalized before one required stop since it was enqueued, an early finalization
error will be raised. If the migration requires to be finalized before one required stop,
use `skip_early_finalization_validation: true` option to skip this check.
+{{< /alert >}}
+
### Deleting batched background migration code
Once a batched background migration has completed, is finalized and has not been [re-queued](#re-queue-batched-background-migrations),
@@ -482,10 +493,13 @@ queue_batched_background_migration(
)
```
-NOTE:
+{{< alert type="note" >}}
+
If the number of defined job arguments does not match the number of job arguments provided when
scheduling the migration, `queue_batched_background_migration` raises an error.
+{{< /alert >}}
+
In this example, `copy_from` returns `name`, and `copy_to` returns `name_convert_to_text`:
```ruby
@@ -570,10 +584,13 @@ as the batching strategy.
end
```
- NOTE:
- For EE migrations that define `scope_to`, ensure the module extends `ActiveSupport::Concern`.
+ {{< alert type="note" >}}
+
+For EE migrations that define `scope_to`, ensure the module extends `ActiveSupport::Concern`.
Otherwise, records are processed without taking the scope into consideration.
+ {{< /alert >}}
+
1. In the post-deployment migration, enqueue the batched background migration:
```ruby
@@ -707,9 +724,12 @@ module Gitlab
end
```
-NOTE:
+{{< alert type="note" >}}
+
[Additional filters](#use-filters) defined with `scope_to` are ignored by `LooseIndexScanBatchingStrategy` and `distinct_each_batch`.
+{{< /alert >}}
+
### Calculate overall time estimation of a batched background migration
It's possible to estimate how long a BBM takes to complete. GitLab already provides an estimation through the `db:gitlabcom-database-testing` pipeline.
@@ -719,15 +739,21 @@ calculate all the singularities around the records being migrated, making furthe
`interval * number of records / max batch size` can be used to determine an approximate estimation of how long the migration takes.
Where `interval` and `max batch size` refer to options defined for the job, and the `total tuple count` is the number of records to be migrated.
-NOTE:
+{{< alert type="note" >}}
+
Estimations may be affected by the [migration optimization mechanism](#migration-optimization).
+{{< /alert >}}
+
### Cleaning up a batched background migration
-NOTE:
+{{< alert type="note" >}}
+
Cleaning up any remaining background migrations must be done in either a major
or minor release. You must not do this in a patch release.
+{{< /alert >}}
+
Because background migrations can take a long time, you can't immediately clean
things up after queueing them. For example, you can't drop a column used in the
migration process, as jobs would fail. You must add a separate _post-deployment_
@@ -765,9 +791,12 @@ creation.
### Execute a particular batch on the database testing pipeline
-NOTE:
+{{< alert type="note" >}}
+
Only [database maintainers](https://gitlab.com/groups/gitlab-org/maintainers/database/-/group_members?with_inherited_permissions=exclude) can view the database testing pipeline artifacts. Ask one for help if you need to use this method.
+{{< /alert >}}
+
Let's assume that a batched background migration failed on a particular batch on GitLab.com and you want to figure out which query failed and why. At the moment, we don't have a good way to retrieve query information (especially the query parameters) and rerunning the entire migration with more logging would be a long process.
Fortunately you can leverage our [database migration pipeline](database_migration_pipeline.md) to rerun a particular batch with additional logging and/or fix to see if it solves the problem.
@@ -907,9 +936,12 @@ end
## Managing
-NOTE:
+{{< alert type="note" >}}
+
BBM management takes place through `chatops` integration, which is limited to GitLab team members only.
+{{< /alert >}}
+
### List batched background migrations
To list the batched background migrations in the system, run this command:
@@ -932,9 +964,12 @@ Output example:
-NOTE:
+{{< alert type="note" >}}
+
ChatOps returns 20 batched background migrations order by `created_at` (DESC).
+{{< /alert >}}
+
### Monitor the progress and status of a batched background migration
To see the status and progress of a specific batched background migration, run this command:
@@ -993,9 +1028,12 @@ Output example:
-NOTE:
+{{< alert type="note" >}}
+
You can pause only `active` batched background migrations.
+{{< /alert >}}
+
### Resume a batched background migration
If you want to resume a batched background migration, you need to run the following command:
@@ -1018,9 +1056,12 @@ Output example:
-NOTE:
+{{< alert type="note" >}}
+
You can resume only `active` batched background migrations
+{{< /alert >}}
+
### Enable or disable background migrations
In extremely limited circumstances, a GitLab administrator can disable either or
@@ -1032,11 +1073,14 @@ both of these [feature flags](../../administration/feature_flags.md):
These flags are enabled by default. Disable them only as a last resort
to limit database operations in special circumstances, like database host maintenance.
-WARNING:
+{{< alert type="warning" >}}
+
Do not disable either of these flags unless you fully understand the ramifications. If you disable
the `execute_background_migrations` or `execute_batched_migrations_on_schedule` feature flag,
GitLab upgrades might fail and data loss might occur.
+{{< /alert >}}
+
## Batched background migrations for EE-only features
All the background migration classes for EE-only features should be present in GitLab FOSS.
@@ -1044,11 +1088,14 @@ For this purpose, create an empty class for GitLab FOSS, and extend it for GitLa
as explained in the guidelines for
[implementing Enterprise Edition features](../ee_features.md#code-in-libgitlabbackground_migration).
-NOTE:
+{{< alert type="note" >}}
+
Background migration classes for EE-only features that use job arguments should define them
in the GitLab FOSS class. Definitions are required to prevent job arguments validation from failing when
migration is scheduled in the GitLab FOSS context.
+{{< /alert >}}
+
You can use the [generator](#generate-a-batched-background-migration) to generate an EE-only migration scaffold by passing
`--ee-only` flag when generating a new batched background migration.
@@ -1191,12 +1238,15 @@ background migration.
end
```
- NOTE:
- Job classes inherit from `BatchedMigrationJob` to ensure they are
+ {{< alert type="note" >}}
+
+Job classes inherit from `BatchedMigrationJob` to ensure they are
correctly handled by the batched migration framework. Any subclass of
`BatchedMigrationJob` is initialized with the necessary arguments to
execute the batch, and a connection to the tracking database.
+ {{< /alert >}}
+
1. Create a database migration that adds a new trigger to the database. Example:
```ruby
@@ -1268,14 +1318,17 @@ background migration.
finalized_by: # version of the migration that ensured this bbm
```
- NOTE:
- When queuing a batched background migration, you need to restrict
+ {{< alert type="note" >}}
+
+When queuing a batched background migration, you need to restrict
the schema to the database where you make the actual changes.
In this case, we are updating `routes` records, so we set
`restrict_gitlab_migration gitlab_schema: :gitlab_main`. If, however,
you need to perform a CI data migration, you would set
`restrict_gitlab_migration gitlab_schema: :gitlab_ci`.
+ {{< /alert >}}
+
After deployment, our application:
- Continues using the data as before.
- Ensures that both existing and new data are migrated.
@@ -1318,11 +1371,14 @@ background migration.
finalized_by: 20231115120912
```
- NOTE:
- If the batched background migration is not finished, the system will
+ {{< alert type="note" >}}
+
+If the batched background migration is not finished, the system will
execute the batched background migration inline. If you don't want
to see this behavior, you need to pass `finalize: false`.
+ {{< /alert >}}
+
If the application does not depend on the data being 100% migrated (for
instance, the data is advisory, and not mission-critical), then you can skip this
final step. This step confirms that the migration is completed, and all of the rows were migrated.
diff --git a/doc/development/database/batching_best_practices.md b/doc/development/database/batching_best_practices.md
index afd1fc20276d97524a5375302b3a5a28e3efba8f..e124ea7a79c59199d9deaec12f2fe27ec66746c2 100644
--- a/doc/development/database/batching_best_practices.md
+++ b/doc/development/database/batching_best_practices.md
@@ -234,9 +234,12 @@ def perform
end
```
-NOTE:
+{{< alert type="note" >}}
+
To avoid parallel processing of records, you might need to wrap the execution with a distributed Redis lock.
+{{< /alert >}}
+
Example Redis lock usage:
```ruby
@@ -260,11 +263,16 @@ Sidekiq jobs can consume substantial database resources. If your job only batche
## Batching strategies
-NOTE:
+{{< alert type="note" >}}
+
To keep the examples easy to follow, we omit the code for limiting the runtime.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Some examples include an optional variable assignment to the `cursor` variable. This is optional step which can be used when implementing the "continue later" mechanism.
+{{< /alert >}}
### Loop-based batching
diff --git a/doc/development/database/clickhouse/clickhouse_within_gitlab.md b/doc/development/database/clickhouse/clickhouse_within_gitlab.md
index 602956dbf99a7bb7c04c700c5ffe98d1629d1f8a..8d1bdaaf0571d306173fa462750e57f0896e2367 100644
--- a/doc/development/database/clickhouse/clickhouse_within_gitlab.md
+++ b/doc/development/database/clickhouse/clickhouse_within_gitlab.md
@@ -7,9 +7,12 @@ title: ClickHouse within GitLab
This document gives a high-level overview of how to develop features using ClickHouse in the GitLab Rails application.
-NOTE:
+{{< alert type="note" >}}
+
Most of the tooling and APIs are considered unstable.
+{{< /alert >}}
+
## GDK setup
### Setup ClickHouse server
@@ -223,9 +226,12 @@ CsvBuilder::Gzip.new(iterator, column_mapping).render do |tempfile|
end
```
-NOTE:
+{{< alert type="note" >}}
+
It's important to test and verify efficient batching of database records from PostgreSQL. Consider using the techniques described in the [Iterating tables in batches](../iterating_tables_in_batches.md).
+{{< /alert >}}
+
## Iterating over tables
You can use the `ClickHouse::Iterator` class for batching over large volumes of data in ClickHouse. The iterator works a bit differently than existing tooling for the PostgreSQL database (see [iterating tables in batches docs](../iterating_tables_in_batches.md)), as the tool does not rely on database indexes and uses fixed size numeric ranges.
diff --git a/doc/development/database/clickhouse/gitlab_activity_data.md b/doc/development/database/clickhouse/gitlab_activity_data.md
index 73f109172abb18d1e736d51a3f02d5b875fbdc00..4c7df3704f4ca88f88f6f08aa691af6b0a35a5e1 100644
--- a/doc/development/database/clickhouse/gitlab_activity_data.md
+++ b/doc/development/database/clickhouse/gitlab_activity_data.md
@@ -104,9 +104,12 @@ Most of the data is written once however, we cannot say that the table is append
### Example queries
-NOTE:
+{{< alert type="note" >}}
+
These queries have been significantly simplified from the actual queries from production.
+{{< /alert >}}
+
Database query for the user's contribution graph:
```sql
diff --git a/doc/development/database/clickhouse/merge_request_analytics.md b/doc/development/database/clickhouse/merge_request_analytics.md
index df3a2f7ff28ee9d666da567db53fad319b511b34..2ff361138d283bf5ab4c2ef909f789f426bae58e 100644
--- a/doc/development/database/clickhouse/merge_request_analytics.md
+++ b/doc/development/database/clickhouse/merge_request_analytics.md
@@ -175,10 +175,13 @@ FROM generateRandom('id UInt64, project_id UInt8, author_id UInt8, milestone_id
LIMIT 1000000;
```
-NOTE:
+{{< alert type="note" >}}
+
Some integer data types were cast as `UInt8` so it is highly probable that they
have same values across different rows.
+{{< /alert >}}
+
The original count query only aggregated data for one month. With ClickHouse, we can
attempt aggregating the data for the whole year.
diff --git a/doc/development/database/clickhouse/tiered_storage.md b/doc/development/database/clickhouse/tiered_storage.md
index a712266e3bbcbe9be5785765f41c9cc0fd77720d..071e9d155f6d72ab64f87316fb268376b1893e2a 100644
--- a/doc/development/database/clickhouse/tiered_storage.md
+++ b/doc/development/database/clickhouse/tiered_storage.md
@@ -5,11 +5,14 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Tiered Storages in ClickHouse
---
-NOTE:
+{{< alert type="note" >}}
+
The MergeTree table engine in ClickHouse supports tiered storage.
See the documentation for [Using Multiple Block Devices for Data Storage](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-multiple-volumes)
for details on setup and further explanation.
+{{< /alert >}}
+
Quoting from the [MergeTree documentation](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-multiple-volumes):
<!-- vale gitlab_base.Simplicity = NO -->
@@ -79,10 +82,13 @@ PARTITION BY toYYYYMM(event_date)
SETTINGS storage_policy = 'move_from_local_disks_to_gcs'
```
-NOTE:
+{{< alert type="note" >}}
+
In this storage policy, the move happens implicitly. It is also possible to keep
_hot_ data on local disks for a fixed period of time and then move them as _cold_.
+{{< /alert >}}
+
This approach is possible with
[Table TTLs](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl),
which are also available with MergeTree table engine.
diff --git a/doc/development/database/database_lab.md b/doc/development/database/database_lab.md
index 1fc8f0a1d6b4e0480b9d1da57084bd5fff046558..7a9888e7ecf7fcd0c273ac6ccc3185e0f9910d18 100644
--- a/doc/development/database/database_lab.md
+++ b/doc/development/database/database_lab.md
@@ -1,10 +1,9 @@
---
+type: reference, howto
stage: Data Access
group: Database Frameworks
-type: reference, howto
-discretionary: yes
-description: Database access for engineers and related parties.
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
+description: Database access for engineers and related parties.
title: Database Lab and Postgres.ai
---
@@ -43,12 +42,15 @@ To access the DLE's services, you can:
For more assistance, use the `#database` Slack channel.
-NOTE:
+{{< alert type="note" >}}
+
If you need only temporary access to a production replica, instead of a Database Lab
clone, follow the runbook procedure for connecting to the
[database console with Teleport](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/teleport/Connect_to_Database_Console_via_Teleport.md).
This procedure is similar to [Rails console access with Teleport](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/teleport/Connect_to_Rails_Console_via_Teleport.md#how-to-use-teleport-to-connect-to-rails-console).
+{{< /alert >}}
+
### Query testing
You can access Database Lab's query analysis features either:
@@ -132,9 +134,12 @@ For information on testing migrations, review our
### Access the console with `psql`
-NOTE:
+{{< alert type="note" >}}
+
You must have `AllFeaturesUser` [`psql` access](#access-database-lab-engine) to access the console with `psql`.
+{{< /alert >}}
+
To access the database lab instances, you must:
- File an [access request](https://handbook.gitlab.com/handbook/it/end-user-services/onboarding-access-requests/access-requests/#individual-or-bulk-access-request).
diff --git a/doc/development/database/dbcheck-migrations-job.md b/doc/development/database/dbcheck-migrations-job.md
index ee4410076292e425a964e582079d0908d606fb42..e4c8feb137776c5590aad07fb029682f02e7aed6 100644
--- a/doc/development/database/dbcheck-migrations-job.md
+++ b/doc/development/database/dbcheck-migrations-job.md
@@ -2,7 +2,7 @@
stage: Data Access
group: Database Frameworks
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-title: 'db:check-migrations job'
+title: db:check-migrations job
---
This job runs on the test stage of a merge request pipeline. It checks:
diff --git a/doc/development/database/dbmigrate_multi_version_upgrade_job.md b/doc/development/database/dbmigrate_multi_version_upgrade_job.md
index 4b6f7e49ef2c81b2630d145f861c685ec6829f55..d3e8bb25282adaa62e28a7a3c9f25a17f58814a7 100644
--- a/doc/development/database/dbmigrate_multi_version_upgrade_job.md
+++ b/doc/development/database/dbmigrate_multi_version_upgrade_job.md
@@ -2,10 +2,14 @@
stage: Data Access
group: Database
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-title: 'db:migrate:multi-version-upgrade job'
+title: db:migrate:multi-version-upgrade job
---
-> - [Introduced](https://gitlab.com/groups/gitlab-org/quality/quality-engineering/-/epics/19) in GitLab 16.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/quality/quality-engineering/-/epics/19) in GitLab 16.11.
+
+{{< /history >}}
This job runs on the test stage of a merge request pipeline. It validates that migrations pass
for multi-version upgrade from the latest [required upgrade stop](../../update/upgrade_paths.md)
diff --git a/doc/development/database/deduplicate_database_records.md b/doc/development/database/deduplicate_database_records.md
index 567387ebc65b4ad743f24c32e1154e813d00a701..8cfe9c41e6ec2a98866e8c69f9202587fc7b0e31 100644
--- a/doc/development/database/deduplicate_database_records.md
+++ b/doc/development/database/deduplicate_database_records.md
@@ -112,9 +112,12 @@ def down
end
```
-NOTE:
+{{< alert type="note" >}}
+
This is a destructive operation with no possibility of rolling back. Make sure that the deduplication logic is tested thoroughly.
+{{< /alert >}}
+
Replacing the old index with a unique index:
```ruby
@@ -133,9 +136,12 @@ Milestone 3:
1. Remove the advisory lock by removing the `prevent_concurrent_inserts` ActiveRecord callback method.
-NOTE:
+{{< alert type="note" >}}
+
This milestone must be after a [required stop](required_stops.md).
+{{< /alert >}}
+
## Deduplicate strategy for large tables
When deduplicating a large table we can move the batching and the deduplication logic into a [batched background migration](batched_background_migrations.md).
@@ -156,5 +162,8 @@ Milestone 3:
1. Replace the existing index with a unique index.
1. Remove the advisory lock by removing the `prevent_concurrent_inserts` ActiveRecord callback method.
-NOTE:
+{{< alert type="note" >}}
+
This milestone must be after a [required stop](required_stops.md).
+
+{{< /alert >}}
diff --git a/doc/development/database/efficient_in_operator_queries.md b/doc/development/database/efficient_in_operator_queries.md
index 97ad57d5a2bd0bbf2d226ce32d010567a761cd2e..baabdfdc62cfd7680e3bea202946a43b2cf7ebc4 100644
--- a/doc/development/database/efficient_in_operator_queries.md
+++ b/doc/development/database/efficient_in_operator_queries.md
@@ -8,11 +8,14 @@ title: Efficient `IN` operator queries
This document describes a technique for building efficient ordered database queries with the `IN`
SQL operator and the usage of a GitLab utility module to help apply the technique.
-NOTE:
+{{< alert type="note" >}}
+
The described technique makes heavy use of
[keyset pagination](pagination_guidelines.md#keyset-pagination).
It's advised to get familiar with the topic first.
+{{< /alert >}}
+
## Motivation
In GitLab, many domain objects like `Issue` live under nested hierarchies of projects and groups.
@@ -51,11 +54,14 @@ ORDER BY "issues"."created_at" ASC,
LIMIT 20
```
-NOTE:
+{{< alert type="note" >}}
+
For pagination, ordering by the `created_at` column is not enough,
we must add the `id` column as a
[tie-breaker](pagination_performance_guidelines.md#tie-breaker-column).
+{{< /alert >}}
+
The execution of the query can be largely broken down into three steps:
1. The database accesses both `namespaces` and `projects` tables
@@ -160,9 +166,12 @@ The technique can only optimize `IN` queries that satisfy the following requirem
- The columns in the `ORDER BY` clause are distinct
(the combination of the columns uniquely identifies one particular row in the table).
-WARNING:
+{{< alert type="warning" >}}
+
This technique does not improve the performance of the `COUNT(*)` queries.
+{{< /alert >}}
+
## The `InOperatorOptimization` module
The `Gitlab::Pagination::Keyset::InOperatorOptimization` module implements utilities for applying a generalized version of
@@ -171,12 +180,15 @@ the efficient `IN` query technique described in the previous section.
To build optimized, ordered `IN` queries that meet [the requirements](#requirements),
use the utility class `QueryBuilder` from the module.
-NOTE:
+{{< alert type="note" >}}
+
The generic keyset pagination module introduced in the merge request
[51481](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51481)
plays a fundamental role in the generalized implementation of the technique
in `Gitlab::Pagination::Keyset::InOperatorOptimization`.
+{{< /alert >}}
+
### Basic usage of `QueryBuilder`
To illustrate a basic usage, we build a query that
@@ -579,9 +591,12 @@ FROM
LIMIT 20
```
-NOTE:
+{{< alert type="note" >}}
+
To make the query efficient, the following columns need to be covered with an index: `project_id`, `issue_type`, `created_at`, and `id`.
+{{< /alert >}}
+
#### Using calculated `ORDER BY` expression
The following example orders epic records by the duration between the creation time and closed
@@ -668,10 +683,13 @@ Ordering records by mixed columns where one or more columns are coming from `JOI
works with limitations. It requires extra configuration via Common Table Expression (CTE). The trick is to use a
non-materialized CTE to act as a "fake" table which exposes all required columns.
-NOTE:
+{{< alert type="note" >}}
+
The query performance might not improve compared to the standard `IN` query. Always
check the query plan.
+{{< /alert >}}
+
Example: order issues by `projects.name, issues.id` within the group hierarchy
The first step is to create a CTE, where all required columns are collected in the `SELECT`
@@ -742,13 +760,16 @@ Gitlab::Pagination::Keyset::Iterator.new(scope: scope, **opts).each_batch(of: 10
end
```
-NOTE:
+{{< alert type="note" >}}
+
The query loads complete database rows from the disk. This may cause increased I/O and slower
database queries. Depending on the use case, the primary key is often only
needed for the batch query to invoke additional statements. For example, `UPDATE` or `DELETE`. The
`id` column is included in the `ORDER BY` columns (`created_at` and `id`) and is already
loaded. In this case, you can omit the `finder_query` parameter.
+{{< /alert >}}
+
Example for loading the `ORDER BY` columns only:
```ruby
@@ -957,10 +978,13 @@ Order the keyset arrays according to the original `ORDER BY` clause with `LIMIT
`UNNEST [] WITH ORDINALITY` table function. The function locates the "lowest" keyset cursor
values and gives us the array position. These cursor values are used to locate the record.
-NOTE:
+{{< alert type="note" >}}
+
At this point, we haven't read anything from the database tables, because we relied on
fast index-only scans.
+{{< /alert >}}
+
| `project_ids` | `created_at_values` | `id_values` |
| ------------- | ------------------- | ----------- |
| 2 | 2020-01-10 | 5 |
@@ -1100,7 +1124,10 @@ Performance comparison for the `gitlab-org` group:
| `IN` query | 240833 | 1.2s | 660ms |
| Optimized `IN` query | 9783 | 450ms | 22ms |
-NOTE:
+{{< alert type="note" >}}
+
Before taking measurements, the group lookup query was executed separately to make
the group data available in the buffer cache. Since it's a frequently called query, it
hits many shared buffers during the query execution in the production environment.
+
+{{< /alert >}}
diff --git a/doc/development/database/insert_into_tables_in_batches.md b/doc/development/database/insert_into_tables_in_batches.md
index dbd2ab75741eabfc45b161e474f1bc77d0c10c98..eb487a4115388f26a93a710a2f9000f1d4ce8dc1 100644
--- a/doc/development/database/insert_into_tables_in_batches.md
+++ b/doc/development/database/insert_into_tables_in_batches.md
@@ -2,10 +2,7 @@
stage: Data Access
group: Database Frameworks
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Sometimes it is necessary to store large amounts of records at once, which can be inefficient
-when iterating collections and performing individual `save`s. With the arrival of `insert_all`
-in Rails 6, which operates at the row level (that is, using `Hash`es), GitLab has added a set
-of APIs that make it safe and simple to insert ActiveRecord objects in bulk."
+description: Sometimes it is necessary to store large amounts of records at once, which can be inefficient when iterating collections and performing individual `save`s. With the arrival of `insert_all` in Rails 6, which operates at the row level (that is, using `Hash`es), GitLab has added a set of APIs that make it safe and simple to insert ActiveRecord objects in bulk.
title: Insert into tables in batches
---
@@ -100,10 +97,13 @@ performance impact this might have on your code. There is a trade-off between th
### Handling duplicate records
-NOTE:
+{{< alert type="note" >}}
+
This parameter applies only to `bulk_insert!`. If you intend to update existing
records, use `bulk_upsert!` instead.
+{{< /alert >}}
+
It may happen that some records you are trying to insert already exist, which would result in
primary key conflicts. There are two ways to address this problem: failing fast by raising an
error or skipping duplicate records. The default behavior of `bulk_insert!` is to fail fast
diff --git a/doc/development/database/iterating_tables_in_batches.md b/doc/development/database/iterating_tables_in_batches.md
index cfbbe9d651ec9be1df0ceaf657ae963ad3667a0a..95d0e7387671284cf97613042ac5dbe4dc0a287c 100644
--- a/doc/development/database/iterating_tables_in_batches.md
+++ b/doc/development/database/iterating_tables_in_batches.md
@@ -106,12 +106,15 @@ end
The query above iterates over the project creators and prints them out without duplications.
-NOTE:
+{{< alert type="note" >}}
+
In case the column is not unique (no unique index definition), calling the `distinct` method on
the relation is necessary. Using not unique column without `distinct` may result in `each_batch`
falling into an endless loop as described in following
[issue](https://gitlab.com/gitlab-org/gitlab/-/issues/285097).
+{{< /alert >}}
+
## `EachBatch` in data migrations
When dealing with data migrations the preferred way to iterate over a large volume of data is using
@@ -254,9 +257,12 @@ the actual table to find the first matching row.
-NOTE:
+{{< alert type="note" >}}
+
The number of scanned rows depends on the data distribution in the table.
+{{< /alert >}}
+
- Best case scenario: the first user was never logged in. The database reads only one row.
- Worst case scenario: all users were logged in at least once. The database reads all rows.
@@ -295,10 +301,13 @@ To address this problem, we have two options:
- Create another, conditional index to cover the new query.
- Replace the index with a more generalized configuration.
-NOTE:
+{{< alert type="note" >}}
+
Having multiple indexes on the same table and on the same columns could be a performance bottleneck
when writing data.
+{{< /alert >}}
+
Let's consider the following index (avoid):
```sql
@@ -374,9 +383,12 @@ constant "load" on the query which often ends up in statement timeouts. We have
of [confidential issues](../../user/project/issues/confidential_issues.md), the execution time
and the accessed database rows depend on the data distribution in the `issues` table.
-NOTE:
+{{< alert type="note" >}}
+
Using subqueries works only when the subquery returns a small number of rows.
+{{< /alert >}}
+
#### Improving Subqueries
When dealing with subqueries, a slow iteration approach could work: the filter on `creator_id`
@@ -613,9 +625,12 @@ iterator.each_batch(of: 100) do |records|
end
```
-NOTE:
+{{< alert type="note" >}}
+
To keep the iteration stable and predictable, avoid updating the columns in the `ORDER BY` clause.
+{{< /alert >}}
+
### Iterate over the `merge_request_diff_commits` table
The `merge_request_diff_commits` table uses a composite primary key (`merge_request_diff_id, relative_order`),
diff --git a/doc/development/database/keyset_pagination.md b/doc/development/database/keyset_pagination.md
index fd22c84519a9f1f71e2ba2701b43e36e172ce452..80585e9111b4a8071aecbe73cca9bb1e984fde0b 100644
--- a/doc/development/database/keyset_pagination.md
+++ b/doc/development/database/keyset_pagination.md
@@ -165,9 +165,12 @@ the primary key is covered by a database index.
When two or more columns are used in the `ORDER BY` clause, it's advised to check the generated database query and make sure that the correct index configuration is used. More information can be found on the [pagination guideline page](pagination_guidelines.md#index-coverage).
-NOTE:
+{{< alert type="note" >}}
+
While the query performance of the first page might look good, the second page (where the cursor attributes are used in the query) might yield poor performance. It's advised to always verify the performance of both queries: first page and second page.
+{{< /alert >}}
+
Example database query with tie-breaker (`id`) column:
```sql
diff --git a/doc/development/database/loose_foreign_keys.md b/doc/development/database/loose_foreign_keys.md
index 297926320ae6f9bebb8ce035b7c754e7bbc7a42e..b215c6fcc8cfd22792654bd1f511eeeb8d997042 100644
--- a/doc/development/database/loose_foreign_keys.md
+++ b/doc/development/database/loose_foreign_keys.md
@@ -45,9 +45,12 @@ we can:
1. For each record in the table, delete the associated `ci_pipelines` records
using the `project_id` column.
-NOTE:
+{{< alert type="note" >}}
+
For this procedure to work, we must register which tables to clean up asynchronously.
+{{< /alert >}}
+
## The `scripts/decomposition/generate-loose-foreign-key`
We built an automation tool to aid migration of foreign keys into loose foreign keys as part of
@@ -55,9 +58,12 @@ decomposition effort. It presents existing keys and allows chosen foreign keys t
converted into loose foreign keys. This ensures consistency between foreign key and loose foreign
key definitions, and ensures that they are properly tested.
-WARNING:
+{{< alert type="warning" >}}
+
We strongly advise you to use the automation script for swapping any foreign key to a loose foreign key.
+{{< /alert >}}
+
The tool ensures that all aspects of swapping a foreign key are covered. This includes:
- Creating a migration to remove a foreign key.
@@ -386,10 +392,13 @@ def show
end
```
-NOTE:
+{{< alert type="note" >}}
+
This example is unlikely in GitLab, because we usually look up the parent models to perform
permission checks.
+{{< /alert >}}
+
## A note on `dependent: :destroy` and `dependent: :nullify`
We considered using these Rails features as an alternative to foreign keys but there are several problems which include:
@@ -843,9 +852,12 @@ When the cleanup is done, the older partitions are automatically detached by the
### PartitionManager bug
-NOTE:
+{{< alert type="note" >}}
+
This issue happened in the past on Staging and it has been mitigated.
+{{< /alert >}}
+
When adding a new partition, the default value of the `partition` column is also updated. This is
a schema change that is executed in the same transaction as the new partition creation. It's highly
unlikely that the `partition` column goes outdated.
diff --git a/doc/development/database/maintenance_operations.md b/doc/development/database/maintenance_operations.md
index ac49fff916a2b3cb5061404092c1ec46e63ac156..4aeb3a0798e9cd94668a199d6136e84bff2966f6 100644
--- a/doc/development/database/maintenance_operations.md
+++ b/doc/development/database/maintenance_operations.md
@@ -9,10 +9,13 @@ This page details various database related operations that may relate to develop
## Disabling an index is not safe
-WARNING:
+{{< alert type="warning" >}}
+
Previously, this section described a procedure to mark the index as invalid before removing it.
It's no longer recommended, as [it is not safe](https://gitlab.com/groups/gitlab-org/-/epics/11543#note_1570734906).
+{{< /alert >}}
+
There are certain situations in which you might want to disable an index before removing it:
- The index is on a large table and rebuilding it in the case of a revert would take a long time.
diff --git a/doc/development/database/multiple_databases.md b/doc/development/database/multiple_databases.md
index 03042a7ba9fac68588badd4f420a4f118adc9273..be55f3d1e08037523c2b138a3dd2aa032cc9e3cf 100644
--- a/doc/development/database/multiple_databases.md
+++ b/doc/development/database/multiple_databases.md
@@ -104,11 +104,14 @@ Read [Migrations for Multiple Databases](migrations_for_multiple_databases.md).
By default, GDK is configured to run with multiple databases.
-WARNING:
+{{< alert type="warning" >}}
+
Switching back-and-forth between single and multiple databases in
the same development instance is discouraged. Any data in the `ci`
database will not be accessible in single database mode. For single database, you should use a separate development instance.
+{{< /alert >}}
+
To configure GDK to use a single database:
1. On the GDK root directory, run:
@@ -126,10 +129,13 @@ To configure GDK to use a single database:
To switch back to using multiple databases, set `gitlab.rails.databases.ci.enabled` to `true` and run `gdk reconfigure`.
<!--
-NOTE: The `validate_cross_joins!` method in `spec/support/database/prevent_cross_joins.rb` references
+{{< alert type="note" >}}
+
+The `validate_cross_joins!` method in `spec/support/database/prevent_cross_joins.rb` references
the following heading in the code, so if you make a change to this heading, make sure to update
the corresponding documentation URL used in `spec/support/database/prevent_cross_joins.rb`.
-->
+{{< /alert >}}
### Removing joins between `ci` and non `ci` tables
@@ -536,9 +542,12 @@ class Group < Namespace
end
```
-WARNING:
+{{< alert type="warning" >}}
+
Overriding an association can have unintended consequences and may even lead to data loss, as we noticed in [issue 424307](https://gitlab.com/gitlab-org/gitlab/-/issues/424307). Do not override existing ActiveRecord associations to mark a cross-join as allowed, as in the example below.
+{{< /alert >}}
+
```ruby
class Group < Namespace
has_many :users, through: :group_members
@@ -824,15 +833,21 @@ For this purpose, GitLab provides two Rake tasks, one for each database:
- `gitlab:db:truncate_legacy_tables:main` will truncate the CI tables in Main database.
- `gitlab:db:truncate_legacy_tables:ci` will truncate the Main tables in CI database.
-NOTE:
+{{< alert type="note" >}}
+
These tasks can only be run when the tables in the database are
[locked for writes](#locking-writes-on-the-tables-that-dont-belong-to-the-database-schemas).
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The examples in this section use `DRY_RUN=true`. This ensures no data is actually
truncated. GitLab highly recommends to have a backup available before you run any of
these tasks without `DRY_RUN=true`.
+{{< /alert >}}
+
These tasks have the option to see what they do without actually changing the
data:
diff --git a/doc/development/database/not_null_constraints.md b/doc/development/database/not_null_constraints.md
index 2c5ea1555f8d18456e8d934d8953ea68201f596a..4680f0dac21f7dcd9ad804ab00dd298794a23105 100644
--- a/doc/development/database/not_null_constraints.md
+++ b/doc/development/database/not_null_constraints.md
@@ -68,10 +68,13 @@ The steps required are:
examples of methods to look out for.
1. Add a post-deployment migration to fix the existing records.
- NOTE:
+ {{< alert type="note" >}}
+
Depending on the size of the table, a background migration for cleanup could be required in the next release.
See the [`NOT NULL` constraints on large tables](not_null_constraints.md#not-null-constraints-on-large-tables) section for more information.
+ {{< /alert >}}
+
1. Release `N.M+1` (next release)
1. Make sure all existing records on GitLab.com have attribute set. If not, go back to step 1 from Release `N.M`.
@@ -88,10 +91,13 @@ Considering a given release milestone, such as 13.0.
After checking our production database, we know that there are `epics` with `NULL` descriptions,
so we cannot add and validate the constraint in one step.
-NOTE:
+{{< alert type="note" >}}
+
Even if we did not have any epic with a `NULL` description, another instance of GitLab could have
such records, so we would follow the same process either way.
+{{< /alert >}}
+
#### Prevent new invalid records (current release)
Update all the code paths where the attribute is being set to `nil`, if any, to set the attribute to non-nil value
@@ -335,10 +341,13 @@ scheduled after the background migration has completed, which could be several r
end
```
- NOTE:
+ {{< alert type="note" >}}
+
`prepare_partitioned_async_check_constraint_validation` only validates the existing `NOT VALID` check constraint asynchronously for all the partitions.
It doesn't create or validate the check constraint for the partitioned table.
+ {{< /alert >}}
+
1. **Optional.** If the constraint was validated asynchronously, validate the `NOT NULL` constraint once validation is complete:
- Use [Database Lab](database_lab.md) to check if the validation was successful.
Run the command `\d+ table_name` and ensure that `NOT VALID` has been removed from the check constraint definition.
@@ -458,9 +467,12 @@ CREATE TABLE labels (
#### Example
-NOTE:
+{{< alert type="note" >}}
+
The milestone number is just an example. Please use the correct version.
+{{< /alert >}}
+
```ruby
# frozen_string_literal: true
@@ -522,9 +534,12 @@ CREATE TABLE labels (
#### Example
-NOTE:
+{{< alert type="note" >}}
+
The milestone number is just an example. Please use the correct version.
+{{< /alert >}}
+
```ruby
# frozen_string_literal: true
diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md
index 93c80a2c7ca77a08e528b4fe6f3ad03508f12afe..18c7f7bd0b648fd857f285e7facfba34cb1f7294 100644
--- a/doc/development/database/pagination_guidelines.md
+++ b/doc/development/database/pagination_guidelines.md
@@ -68,9 +68,12 @@ Offset-based pagination is the easiest way to paginate over records, however, it
- Promote the usage of the [`Link` header](../../api/rest/_index.md#pagination-link-header) where the URLs for the next and previous page are provided by the backend.
- This way changing the URL structure is possible without breaking backward compatibility.
-NOTE:
+{{< alert type="note" >}}
+
Infinite scroll can use keyset pagination without affecting the user experience since there are no exposed page numbers.
+{{< /alert >}}
+
## Options for pagination
### Offset pagination
@@ -146,9 +149,12 @@ CREATE INDEX index_on_issues_project_id ON issues (project_id, id);
By making the `id` column part of the index, the previous query reads maximum 20 rows. The query performs well regardless of the number of issues within a project. So with this change, we've also improved the initial page load (when the user loads the issue page).
-NOTE:
+{{< alert type="note" >}}
+
Here we're leveraging the ordered property of the b-tree database index. Values in the index are sorted so reading 20 rows does not require further sorting.
+{{< /alert >}}
+
#### Known issues
##### `COUNT(*)` on a large dataset
@@ -279,9 +285,12 @@ In GraphQL, the parameters are serialized to JSON and then encoded:
eyJpZCI6Ijk0NzMzNTk0IiwidXBkYXRlZF9hdCI6IjIwMjEtMDQtMDkgMDg6NTA6MDUuODA1ODg0MDAwIFVUQyJ9
```
-NOTE:
+{{< alert type="note" >}}
+
Pagination parameters are visible to the user, so be careful about which columns we order by.
+{{< /alert >}}
+
Keyset pagination can only provide the next, previous, first, and last pages.
##### Complexity
diff --git a/doc/development/database/pagination_performance_guidelines.md b/doc/development/database/pagination_performance_guidelines.md
index 6415a2c769a73d79870c2c8c7f51df77753da7a4..01bfca8ae71ff8250d0290cff1d41a95c6618cd3 100644
--- a/doc/development/database/pagination_performance_guidelines.md
+++ b/doc/development/database/pagination_performance_guidelines.md
@@ -38,9 +38,12 @@ SELECT issues.* FROM issues ORDER BY created_at, id;
This change makes the order distinct so we have "stable" sorting.
-NOTE:
+{{< alert type="note" >}}
+
To make the query efficient, we need an index covering both columns: `(created_at, id)`. The order of the columns **should match** the columns in the `ORDER BY` clause.
+{{< /alert >}}
+
### Incremental sorting
In PostgreSQL 13 incremental sorting was added which can help introducing a tie-breaker column to the `ORDER BY` clause without adding or replacing an index. Also, with incremental sorting, introducing a new keyset-paginated database query can happen before the new index is built (async indexes). Incremental sorting is enabled by default.
@@ -144,9 +147,12 @@ LIMIT 20
OFFSET 0
```
-NOTE:
+{{< alert type="note" >}}
+
The query requires an index on `issue_metrics` table with the following column configuration: `(project_id, first_mentioned_in_commit_at DESC, issue_id DESC)`.
+{{< /alert >}}
+
## Filtering
### By project
@@ -279,9 +285,12 @@ We might be tempted to add an index on `project_id`, `confidential`, and `iid` t
On the other hand, if we implemented a special filter where we only show confidential issues, we need the index. Finding 20 confidential issues might require the database to scan hundreds of rows or, in the worst case, all issues in the project.
-NOTE:
+{{< alert type="note" >}}
+
Be aware of the data distribution and the table access patterns (how features work) when introducing a new database index. Sampling production data might be necessary to make the right decision.
+{{< /alert >}}
+
#### Columns in a different database table
Example: filtering issues in a project by an assignee
@@ -385,5 +394,8 @@ The query now performs well for any number of `issue_assignees` records, however
- The new database query is very specific to the assignee search and needs complex backend code to build it.
- If the assignee is filtered by the user, then order by a different column, remove the `project_id` filter, etc.
-NOTE:
+{{< alert type="note" >}}
+
Currently we're not doing these kinds of denormalization at GitLab.
+
+{{< /alert >}}
diff --git a/doc/development/database/partitioning/_index.md b/doc/development/database/partitioning/_index.md
index 14341d578e145c405411a570680ddc6e7ba9db06..83d800f508cc41f316cb5c814e43849c9687fe45 100644
--- a/doc/development/database/partitioning/_index.md
+++ b/doc/development/database/partitioning/_index.md
@@ -5,13 +5,16 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Database table partitioning
---
-WARNING:
+{{< alert type="warning" >}}
+
If you have questions not answered below, check for and add them
to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/398650).
Tag `@gitlab-org/database-team/triage` and we'll get back to you with an
answer as soon as possible. If you get an answer in Slack, document
it on the issue as well so we can update this document in the future.
+{{< /alert >}}
+
Table partitioning is a powerful database feature that allows a table's
data to be split into smaller physical tables that act as a single large
table. If the application is designed to work with partitioning in mind,
diff --git a/doc/development/database/partitioning/date_range.md b/doc/development/database/partitioning/date_range.md
index f08b6c04304d6c9c9892e0b2e8a80913ae2adbff..d7506caca17c0c338598d81ecca8b33bc2143763 100644
--- a/doc/development/database/partitioning/date_range.md
+++ b/doc/development/database/partitioning/date_range.md
@@ -55,10 +55,13 @@ CREATE TABLE audit_events (
PARTITION BY RANGE(created_at);
```
-NOTE:
+{{< alert type="note" >}}
+
The primary key of a partitioned table must include the partition key as
part of the primary key definition.
+{{< /alert >}}
+
And we might have a list of partitions for the table, such as:
```sql
@@ -169,9 +172,12 @@ background migration. This includes forcing any remaining jobs to
execute, and copying data that may have been missed, due to dropped or
failed jobs.
-WARNING:
+{{< alert type="warning" >}}
+
A required stop must occur between steps 2 and 3 to allow the background migration from step 2 to complete successfully.
+{{< /alert >}}
+
Once again, continuing the example, this migration would look like:
```ruby
diff --git a/doc/development/database/partitioning/int_range.md b/doc/development/database/partitioning/int_range.md
index 5d451653f3555a312ece1984b6bfbe3de8538471..1b099a9835c0858eb64261a01bf5dfb7b8d9fbf2 100644
--- a/doc/development/database/partitioning/int_range.md
+++ b/doc/development/database/partitioning/int_range.md
@@ -5,7 +5,11 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Int range partitioning
---
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132148) in GitLab 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132148) in GitLab 16.8.
+
+{{< /history >}}
## Description
@@ -44,10 +48,13 @@ CREATE TABLE merge_request_diff_files (
PARTITION BY RANGE(merge_request_diff_id);
```
-NOTE:
+{{< alert type="note" >}}
+
The primary key of a partitioned table must include the partition key as
part of the primary key definition.
+{{< /alert >}}
+
And we might have a list of partitions for the table, such as:
```sql
@@ -147,9 +154,12 @@ background migration. This includes forcing any remaining jobs to
execute, and copying data that may have been missed, due to dropped or
failed jobs.
-WARNING:
+{{< alert type="warning" >}}
+
A required stop must occur between steps 2 and 3 to allow the background migration from step 2 to complete successfully.
+{{< /alert >}}
+
Once again, continuing the example, this migration would look like:
```ruby
diff --git a/doc/development/database/partitioning/list.md b/doc/development/database/partitioning/list.md
index b9164716b89bf7db280776b468732e143c10f8fc..ddb4b62bb5fa6b99245fc25c2e4232f52505decc 100644
--- a/doc/development/database/partitioning/list.md
+++ b/doc/development/database/partitioning/list.md
@@ -5,7 +5,11 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: List partition
---
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96815) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96815) in GitLab 15.4.
+
+{{< /history >}}
## Description
@@ -160,9 +164,12 @@ class PreparePrimaryKeyForPartitioning < Gitlab::Database::Migration[2.1]
end
```
-NOTE:
+{{< alert type="note" >}}
+
Do not forget to set the primary key explicitly in your model as `ActiveRecord` does not support composite primary keys.
+{{< /alert >}}
+
```ruby
class Model < ApplicationRecord
self.primary_key = :id
@@ -238,11 +245,14 @@ class ConvertTableToListPartitioning < Gitlab::Database::Migration[2.1]
end
```
-NOTE:
+{{< alert type="note" >}}
+
Do not forget to set the sequence name explicitly in your model because it will
be owned by the routing table and `ActiveRecord` can't determine it. This can
be cleaned up after the `table_name` is changed to the routing table.
+{{< /alert >}}
+
```ruby
class Model < ApplicationRecord
self.sequence_name = 'model_id_seq'
diff --git a/doc/development/database/poc_tree_iterator.md b/doc/development/database/poc_tree_iterator.md
index 9464698863a4cfe452b7a73bfbb1ec31a55ed83b..712618e058572cf44cec11cb60592b9617ad6ede 100644
--- a/doc/development/database/poc_tree_iterator.md
+++ b/doc/development/database/poc_tree_iterator.md
@@ -188,12 +188,15 @@ FROM result
114 | {} | {24,25,26,112,113,114} | jump
```
-NOTE:
+{{< alert type="note" >}}
+
Using this query to find all the namespace IDs in a group hierarchy is likely slower
than other querying methods, such as the current `self_and_descendants` implementation
based on the `traversal_ids` column. The query above should be only used when
implementing batch iteration over the group hierarchy.
+{{< /alert >}}
+
Rudimentary batching implementation in Ruby:
```ruby
diff --git a/doc/development/database/scalability/patterns/_index.md b/doc/development/database/scalability/patterns/_index.md
index 3d3876cbf04d1aa36ab4bbea9d1e732f9433730c..0cd2878345dea0bab34d2329bc646fe30024e025 100644
--- a/doc/development/database/scalability/patterns/_index.md
+++ b/doc/development/database/scalability/patterns/_index.md
@@ -2,7 +2,7 @@
stage: Data Access
group: Database Frameworks
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
-description: 'Learn how to scale the database through the use of best-of-class database scalability patterns'
+description: Learn how to scale the database through the use of best-of-class database scalability patterns
title: Database Scalability Patterns
---
diff --git a/doc/development/database/scalability/patterns/read_mostly.md b/doc/development/database/scalability/patterns/read_mostly.md
index 6d278fc996fc09caf6a2545b23d5eee68ae4024b..316baff6e54f4698ec5a3aafb5e3cee417127acf 100644
--- a/doc/development/database/scalability/patterns/read_mostly.md
+++ b/doc/development/database/scalability/patterns/read_mostly.md
@@ -2,7 +2,7 @@
stage: Data Access
group: Database Frameworks
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
-description: 'Learn how to scale operating on read-mostly data at scale'
+description: Learn how to scale operating on read-mostly data at scale
title: Read-mostly data
---
diff --git a/doc/development/database/scalability/patterns/time_decay.md b/doc/development/database/scalability/patterns/time_decay.md
index 836c56d891b6ef239b08e32d35266ccd1673b9cb..bd5cc1d78d9e69941760e41ced3a65946437658a 100644
--- a/doc/development/database/scalability/patterns/time_decay.md
+++ b/doc/development/database/scalability/patterns/time_decay.md
@@ -2,7 +2,7 @@
stage: Data Access
group: Database Frameworks
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
-description: 'Learn how to operate on large time-decay data'
+description: Learn how to operate on large time-decay data
title: Time-decay data
---
@@ -352,6 +352,9 @@ to align all access patterns with a specific time-decay related access method.
### CI tables
-NOTE:
+{{< alert type="note" >}}
+
Requirements and analysis of the CI tables use case: still a work in progress. We intend
to add more details after the analysis moves forward.
+
+{{< /alert >}}
diff --git a/doc/development/database/strings_and_the_text_data_type.md b/doc/development/database/strings_and_the_text_data_type.md
index dd0fdb96e626dfc29f0a9b2f932f5a8d59899877..a43acceb2d3bc503adcbb36a5c65a536d00db5fa 100644
--- a/doc/development/database/strings_and_the_text_data_type.md
+++ b/doc/development/database/strings_and_the_text_data_type.md
@@ -33,10 +33,13 @@ but only for updating the declaration of the columns. We can then validate it at
`VALIDATE CONSTRAINT`, which requires only a `SHARE UPDATE EXCLUSIVE LOCK` (only conflicts with other
validations and index creation while it allows reads and writes).
-NOTE:
+{{< alert type="note" >}}
+
Don't use text columns for `attr_encrypted` attributes. Use a
[`:binary` column](../migration_style_guide.md#encrypted-attributes) instead.
+{{< /alert >}}
+
## Create a new table with text columns
When adding a new table, the limits for all text columns should be added in the same migration as
@@ -142,10 +145,13 @@ Adding text limits to existing database columns requires multiple steps split in
- Add a post-deployment migration to add the limit to the text column with `validate: false`.
- Add a post-deployment migration to fix the existing records.
- NOTE:
+ {{< alert type="note" >}}
+
Depending on the size of the table, a background migration for cleanup could be required in the next release.
See [text limit constraints on large tables](strings_and_the_text_data_type.md#text-limit-constraints-on-large-tables) for more information.
+ {{< /alert >}}
+
- Create an issue for the next milestone to validate the text limit.
1. Release `N.M+1` (next release)
@@ -163,10 +169,13 @@ other processes that try to access it while running the update.
Also, after checking our production database, we know that there are `issues` with more characters in
their title than the 1024 character limit, so we cannot add and validate the constraint in one step.
-NOTE:
+{{< alert type="note" >}}
+
Even if we did not have any record with a title larger than the provided limit, another
instance of GitLab could have such records, so we would follow the same process either way.
+{{< /alert >}}
+
#### Prevent new invalid records (current release)
We first add the limit as a `NOT VALID` check constraint to the table, which enforces consistency when
diff --git a/doc/development/database/transaction_guidelines.md b/doc/development/database/transaction_guidelines.md
index 08717f8ac5269e728b4a1a04c2aaa6f7a32250fc..e2e89486b42bea0ad1c4e39b0b6679291f74d90d 100644
--- a/doc/development/database/transaction_guidelines.md
+++ b/doc/development/database/transaction_guidelines.md
@@ -36,9 +36,12 @@ end
This transaction involves two database tables. In case of an error, each `UPDATE`
statement rolls back to the previous consistent state.
-NOTE:
+{{< alert type="note" >}}
+
Avoid referencing the `ActiveRecord::Base` class and use `ApplicationRecord` instead.
+{{< /alert >}}
+
## Transaction and database locks
When a transaction block is opened, the database tries to acquire the necessary
diff --git a/doc/development/database_review.md b/doc/development/database_review.md
index b74d9b31863239d4454ebc7b67ff86392953c0f6..3fe9edafd749ef8c339e10d9858e88f4c53b8621 100644
--- a/doc/development/database_review.md
+++ b/doc/development/database_review.md
@@ -185,7 +185,11 @@ Include in the MR description:
- Optionally, you can also use your own `user_id`, or the `user_id` of a user with a long history within the project or group being used to generate the query plan.
- That means that no query plan should return 0 records or less records than the provided limit (if a limit is included). If a query is used in batching, a proper example batch with adequate included results should be identified and provided.
- NOTE: The `UPDATE` statement always returns 0 records. To identify the rows it updates, we need to check the following lines below.
+ {{< alert type="note" >}}
+
+ The `UPDATE` statement always returns 0 records. To identify the rows it updates, we need to check the following lines below.
+
+ {{< /alert >}}
For example, the `UPDATE` statement returns 0 records, but we can see that it updates 1 row from the line starting with `-> Index scan`.:
diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md
index f31200ddb698e5f420d8fb297ac0bbdb639b4877..f881959c8e565f981233a6a6a5731db286cd1ab5 100644
--- a/doc/development/distributed_tracing.md
+++ b/doc/development/distributed_tracing.md
@@ -224,10 +224,13 @@ This configuration string uses the Jaeger driver `opentracing://jaeger` with the
| `sampler_param` | `0.01` | Use a ratio of `0.01` to configure the `probabilistic` sampler to randomly sample _1%_ of traces. |
| `service_name` | `api` | Override the service name used by the Jaeger backend. This parameter takes precedence over the application-supplied value. |
-NOTE:
+{{< alert type="note" >}}
+
The same `GITLAB_TRACING` value should to be configured in the environment
variables for all GitLab processes, including Workhorse, Gitaly, Rails, and Sidekiq.
+{{< /alert >}}
+
### 3. Start the GitLab application
After the `GITLAB_TRACING` environment variable is exported to all GitLab services, start the
@@ -259,6 +262,9 @@ not set.
By default, the Jaeger search UI is available at <http://localhost:16686/search>.
-NOTE:
+{{< alert type="note" >}}
+
Don't forget that you must generate traces by using the application before
they appear in the Jaeger UI.
+
+{{< /alert >}}
diff --git a/doc/development/distribution/_index.md b/doc/development/distribution/_index.md
index fc772a5f244929f93ebd460be3a432bf74da50a0..f1f81b8adad6b1a56b2a5ff9f83f6c4e6052b6dd 100644
--- a/doc/development/distribution/_index.md
+++ b/doc/development/distribution/_index.md
@@ -2,7 +2,7 @@
stage: Systems
group: Distribution
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "GitLab's development guidelines for Distribution"
+description: GitLab's development guidelines for Distribution
title: Contribute to GitLab Distribution
---
diff --git a/doc/development/documentation/backporting.md b/doc/development/documentation/backporting.md
index a65427e6c8f78cd47b1d2b4361620a5dc405c47d..ff10270434eb2a4af35722a13012362e9188d436 100644
--- a/doc/development/documentation/backporting.md
+++ b/doc/development/documentation/backporting.md
@@ -21,9 +21,12 @@ follow the [standard process to contribute to documentation](_index.md).
## Backport documentation changes to older releases
-WARNING:
+{{< alert type="warning" >}}
+
You should only rarely consider backporting documentation to older stable releases. Legitimate reasons to backport documentation include legal issues, emergency security fixes, and fixes to content that might prevent users from upgrading or cause data loss.
+{{< /alert >}}
+
To backport documentation changes in documentation releases older than the
current stable branch:
diff --git a/doc/development/documentation/experiment_beta.md b/doc/development/documentation/experiment_beta.md
index 1ea231390604962aafd1083d98a48a225ef425f9..59b65e3b48832e1aec24a2eec06e2874d63a7347 100644
--- a/doc/development/documentation/experiment_beta.md
+++ b/doc/development/documentation/experiment_beta.md
@@ -1,7 +1,7 @@
---
-info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects
stage: none
group: unassigned
+info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects
title: Documenting experimental and beta features
---
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md
index bcb2fc94f6f79b7a14e23f8bd7cf049b4d7ef5ee..186529ab9b0b463b81554f30cebecd747e52427c 100644
--- a/doc/development/documentation/feature_flags.md
+++ b/doc/development/documentation/feature_flags.md
@@ -1,8 +1,8 @@
---
-info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
stage: none
group: unassigned
-description: "GitLab development - how to document features deployed behind feature flags"
+info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: GitLab development - how to document features deployed behind feature flags
title: Document features deployed behind feature flags
---
@@ -81,11 +81,14 @@ This feature is available for testing, but not ready for production use.
This note renders on the GitLab documentation site as:
-FLAG:
+{{< alert type="flag" >}}
+
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
## History examples
The following examples show the progression of a feature flag. Update the history with every change:
diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md
index d850e6a9cad2c5cc75b5a6fed0bc0425d9641c1f..0f6a7ef622e5b79a2523a42e7d202e0c00a1425c 100644
--- a/doc/development/documentation/graphql_styleguide.md
+++ b/doc/development/documentation/graphql_styleguide.md
@@ -2,7 +2,7 @@
stage: none
group: unassigned
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Writing styles, markup, formatting, and other standards for GraphQL API's GitLab Documentation."
+description: Writing styles, markup, formatting, and other standards for GraphQL API's GitLab Documentation.
title: Creating a GraphQL example page
---
@@ -68,7 +68,7 @@ You can use GraphiQL to list the branch rules for a project.
## Related topics:
-- [GraphQL API reference](reference/index.md)
+- [GraphQL API reference](reference/_index.md)
```
## Add the GraphQL example to the global navigation
diff --git a/doc/development/documentation/help.md b/doc/development/documentation/help.md
index b3edf9cbba9c18279e73022ec963f05f75f8c066..b7663107a4243671f7582195ea9330f67e6c1d9e 100644
--- a/doc/development/documentation/help.md
+++ b/doc/development/documentation/help.md
@@ -42,7 +42,11 @@ directory. For example:
### `_index.md` files
-> - Support for `_index.md` files [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144419) in GitLab 16.10.
+{{< history >}}
+
+- Support for `_index.md` files [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144419) in GitLab 16.10.
+
+{{< /history >}}
The Hugo static site generator makes use of `_index.md` files. To allow for index pages to be
named either `index.md` or `_index.md` in `/help`, GitLab maps requests for `index.md`, `index.html`, or `index`:
diff --git a/doc/development/documentation/hugo_migration.md b/doc/development/documentation/hugo_migration.md
index 6a8e4ab60caafe215e4526b5db67a998a283c2cf..85bd4cd87564af0f5504fce2ddb204172144be13 100644
--- a/doc/development/documentation/hugo_migration.md
+++ b/doc/development/documentation/hugo_migration.md
@@ -272,9 +272,12 @@ The [Docs project maintenance tasks rotation](https://handbook.gitlab.com/handbo
For February 2025, run the checks for broken external links and `start_remove` content before Wednesday, February 12. Other tasks are fine to skip for now. From March onwards, the monthly maintenance task will be on hold until further notice.
-NOTE:
+{{< alert type="note" >}}
+
This does not impact the release post [structural check](https://handbook.gitlab.com/handbook/marketing/blog/release-posts/#structural-check) or [monthly documentation release](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md) tasks. The assigned Technical Writer should continue to do these tasks as previously scheduled.
+{{< /alert >}}
+
**Why:** Some Ruby scripts need to be rewritten in Go, and the maintenance tasks are
low-priority enough that we can launch without them. There may be more opportunity
post-launch to share more of these scripts with the Handbook project.
diff --git a/doc/development/documentation/metadata.md b/doc/development/documentation/metadata.md
index 1a0f5d1ab8b91b9ffd45a259361c8dcce993538a..a78e5fee63175abdf8553748956477e9fb5e4fd7 100644
--- a/doc/development/documentation/metadata.md
+++ b/doc/development/documentation/metadata.md
@@ -1,7 +1,7 @@
---
-info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
stage: none
group: unassigned
+info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
title: Metadata
---
diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md
index fa195d15cdd6f416cab0a8a53973e595e028ef38..7fd2e2e0b50feec03c150739aa7a1dac64fb10a1 100644
--- a/doc/development/documentation/redirects.md
+++ b/doc/development/documentation/redirects.md
@@ -30,12 +30,15 @@ Add a redirect to ensure:
Be sure to assign a technical writer to any merge request that moves, renames, or deletes a page.
Technical Writers can help with any questions and can review your change.
-NOTE:
+{{< alert type="note" >}}
+
When you change the filename of a page, the Google Analytics are removed
from the content audit and the page views start from scratch.
If you want to change the filename, edit the page first,
so you can ensure the new page name is as accurate as possible.
+{{< /alert >}}
+
## Types of redirects
There are two types of redirects:
@@ -71,7 +74,7 @@ To redirect a page to another page in the same repository:
<!-- markdownlint-disable -->
- This document was moved to [another location](../newpath/to/file/index.md).
+ This document was moved to [another location](../newpath/to/file/_index.md).
<!-- This redirect file can be deleted after <YYYY-MM-DD>. -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md
index 959948bfceffae39e46dc27d68427e2710c9940d..3d79b5e7d777ae9a63ffac58880a165403c2620b 100644
--- a/doc/development/documentation/restful_api_styleguide.md
+++ b/doc/development/documentation/restful_api_styleguide.md
@@ -1,8 +1,8 @@
---
-info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
stage: none
group: unassigned
-description: 'Writing styles, markup, formatting, and other standards for the GitLab RESTful APIs.'
+info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Writing styles, markup, formatting, and other standards for the GitLab RESTful APIs.
title: Documenting REST API resources
---
@@ -242,11 +242,14 @@ For information about writing attribute descriptions, see the [GraphQL API descr
The following sections include a set of [cURL](https://curl.se/) examples
you can use in the API documentation.
-WARNING:
+{{< alert type="warning" >}}
+
Do not use information for real users, URLs, or tokens. For documentation, refer to our
relevant style guide sections on [Fake user information](styleguide/_index.md#fake-user-information),
[Fake URLs](styleguide/_index.md#fake-urls), and [Fake tokens](styleguide/_index.md#fake-tokens).
+{{< /alert >}}
+
### Simple cURL command
Get the details of a group:
diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md
index ae68a96d7065d4674540344eacf0dc342a7dd607..09214c9e7f53691d7c667d42edf5a8dd88d57adc 100644
--- a/doc/development/documentation/site_architecture/deployment_process.md
+++ b/doc/development/documentation/site_architecture/deployment_process.md
@@ -156,7 +156,7 @@ Maintainers can [manually](../../../ci/pipelines/schedules.md#run-manually) run
production:
1. Go to the [scheduled pipelines](https://gitlab.com/gitlab-org/gitlab-docs/-/pipeline_schedules) for `gitlab-docs`.
-1. Next to `Build docs.gitlab.com every hour`, select **Play** (**{play}**).
+1. Next to `Build docs.gitlab.com every hour`, select **Play** ({{< icon name="play" >}}).
The updated documentation is available in production after the `pages` and `pages:deploy` jobs
complete in the new pipeline.
diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md
index fbae6af292f940e1f82175636ae35e1689154d30..f43f716d71a7f91718b65fee02713370d266dea2 100644
--- a/doc/development/documentation/site_architecture/global_nav.md
+++ b/doc/development/documentation/site_architecture/global_nav.md
@@ -2,7 +2,7 @@
stage: none
group: unassigned
info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
-description: "Learn how GitLab docs' global navigation works and how to add new items."
+description: Learn how GitLab docs' global navigation works and how to add new items.
title: Global navigation
---
diff --git a/doc/development/documentation/styleguide/_index.md b/doc/development/documentation/styleguide/_index.md
index 9266281bf3f83f3fc2b8ff9f2bb886e324c344a8..30d40964ea9bb34cd04dedd88d4db55b56fdab4d 100644
--- a/doc/development/documentation/styleguide/_index.md
+++ b/doc/development/documentation/styleguide/_index.md
@@ -1,8 +1,8 @@
---
-info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
stage: none
group: unassigned
-description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.'
+info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Writing styles, markup, formatting, and other standards for GitLab Documentation.
title: Documentation Style Guide
---
@@ -758,8 +758,8 @@ page), use these phrases:
| Option | Markdown | Displayed result |
|--------|--------------------------|------------------------|
-| No | `**{dash-circle}** No` | **{dash-circle}** No |
-| Yes | `**{check-circle-filled}** Yes` | **{check-circle-filled}** Yes |
+| No | `{{< icon name="dash-circle" >}} No` | {{< icon name="dash-circle" >}} No |
+| Yes | `{{< icon name="check-circle-filled" >}} Yes` | {{< icon name="check-circle-filled" >}} Yes |
Do not use these SVG icons in API documentation.
Instead, follow the [API topic template](../restful_api_styleguide.md#api-topic-template).
@@ -871,7 +871,7 @@ and edit.
To link to another documentation (`.md`) file in the same repository:
-- Use an inline link with a relative file path. For example, `[GitLab.com settings](../user/gitlab_com/index.md)`.
+- Use an inline link with a relative file path. For example, `[GitLab.com settings](../user/gitlab_com/_index.md)`.
- Put the entire link on a single line, even if the link is very long. ([Vale](../testing/vale.md) rule: [`MultiLineLinks.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab_base/MultiLineLinks.yml)).
To link to a file outside of the documentation files, for example to link from development
@@ -1094,13 +1094,13 @@ To open either project or group settings:
To create a project:
```markdown
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
```
To create a group:
```markdown
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
```
To open the **Admin** area:
@@ -1517,7 +1517,7 @@ the Markdown rendering engine used for GitLab documentation.
## GitLab SVG icons
You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/)
-directly in the documentation. For example, `**{tanuki}**` renders as: **{tanuki}**.
+directly in the documentation. For example, `{{< icon name="tanuki" >}}` renders as: {{< icon name="tanuki" >}}.
In most cases, you should avoid using the icons in text.
However, you can use an icon when hover text is the only
@@ -1526,21 +1526,21 @@ often have hover text only.
When you do use an icon, start with the hover text and follow it with the SVG reference in parentheses.
-- Avoid: `Select **{pencil}** **Edit**.` This generates as: Select **{pencil}** **Edit**.
-- Use instead: `Select **Edit** (**{pencil}**).` This generates as: Select **Edit** (**{pencil}**).
+- Avoid: `Select {{< icon name="pencil" >}} **Edit**.` This generates as: Select {{< icon name="pencil" >}} **Edit**.
+- Use instead: `Select **Edit** ({{< icon name="pencil" >}}).` This generates as: Select **Edit** ({{< icon name="pencil" >}}).
Do not use words to describe the icon:
- Avoid: `Select **Erase job log** (the trash icon).`
-- Use instead: `Select **Erase job log** (**{remove}**).` This generates as: Select **Erase job log** (**{remove}**).
+- Use instead: `Select **Erase job log** ({{< icon name="remove" >}}).` This generates as: Select **Erase job log** ({{< icon name="remove" >}}).
When the button doesn't have any hover text, you can describe the icon.
Follow up by creating a
[UX bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Bug)
to add hover text to the button to improve accessibility.
-- Avoid: `Select **{ellipsis_v}**.`
-- Use instead: `Select the vertical ellipsis (**{ellipsis_v}**).` This generates as: Select the vertical ellipsis (**{ellipsis_v}**).
+- Avoid: `Select {{< icon name="ellipsis_v" >}}.`
+- Use instead: `Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).` This generates as: Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
## Videos
@@ -1686,9 +1686,12 @@ This is something to note.
It renders on the GitLab documentation site as:
-NOTE:
+{{< alert type="note" >}}
+
This is something to note.
+{{< /alert >}}
+
### Warning
Use a warning to indicate deprecated features, or to provide a warning about
@@ -1701,9 +1704,12 @@ This is something to be warned about.
It renders on the GitLab documentation site as:
-WARNING:
+{{< alert type="warning" >}}
+
This is something to be warned about.
+{{< /alert >}}
+
### Disclaimer
If you **must** write about features we have not yet delivered, put this exact disclaimer about forward-looking statements near the content it applies to.
@@ -1719,12 +1725,7 @@ sole discretion of GitLab Inc.
It renders on the GitLab documentation site as:
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the
-sole discretion of GitLab Inc.
+{{< alert type="disclaimer" />}}
If all of the content on the page is not available, use the disclaimer about forward-looking statements once at the top of the page.
@@ -1775,9 +1776,12 @@ It renders on the GitLab documentation site as:
On the docs site, you can format text so it's displayed as tabs.
-WARNING:
+{{< alert type="warning" >}}
+
Do not put version history bullets, topic headings, HTML, or tabs in tabs. Only use paragraphs, lists, alert boxes, and code blocks. Other styles might not render properly. When in doubt, keep things simple.
+{{< /alert >}}
+
To create a set of tabs, follow this example:
```plaintext
@@ -1797,17 +1801,21 @@ Here's some other content in tab two.
This code renders on the GitLab documentation site as:
-::Tabs
+{{< tabs >}}
-:::TabTitle Tab One
+{{< tab title="Tab One" >}}
Here's some content in tab one.
-:::TabTitle Tab Two
+{{< /tab >}}
+
+{{< tab title="Tab Two" >}}
Here's some other content in tab two.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
For tab titles, be brief and consistent. Ensure they are parallel, and start each with a capital letter.
For example:
@@ -2020,9 +2028,9 @@ following snippet:
It renders as:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -2036,7 +2044,9 @@ It renders as:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -2059,7 +2069,9 @@ It renders as:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -2078,7 +2090,9 @@ It renders as:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -2098,4 +2112,6 @@ It renders as:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/development/documentation/styleguide/availability_details.md b/doc/development/documentation/styleguide/availability_details.md
index 196eea4831fa8de4a714f1b4ab19173015236b3a..0c4022214dd88934d8ca9c7602c3159ff1fdf781 100644
--- a/doc/development/documentation/styleguide/availability_details.md
+++ b/doc/development/documentation/styleguide/availability_details.md
@@ -1,8 +1,8 @@
---
-info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
stage: none
group: unassigned
-description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.'
+info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Writing styles, markup, formatting, and other standards for GitLab Documentation.
title: Product availability details
---
@@ -64,9 +64,12 @@ The possibilities are:
**Tier:** Ultimate with GitLab Duo Enterprise
```
-NOTE:
+{{< alert type="note" >}}
+
GitLab Dedicated always includes an Ultimate subscription.
+{{< /alert >}}
+
### Status
For status, choose one:
diff --git a/doc/development/documentation/styleguide/deprecations_and_removals.md b/doc/development/documentation/styleguide/deprecations_and_removals.md
index 7f28e17c3712ae14833e3fb2c0ab067c623e1ee1..eab388e2f9f1335dae6b83e773870232657edac1 100644
--- a/doc/development/documentation/styleguide/deprecations_and_removals.md
+++ b/doc/development/documentation/styleguide/deprecations_and_removals.md
@@ -1,8 +1,8 @@
---
-info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
stage: none
group: unassigned
-description: 'Guidelines for deprecations and page removals'
+info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Guidelines for deprecations and page removals
title: Deprecations and removals
---
@@ -11,11 +11,14 @@ This process requires temporarily changing content to be "deprecated" or "remove
If a feature is not generally available, you can delete the content outright instead of following these instructions.
-NOTE:
+{{< alert type="note" >}}
+
REST API docs [have a separate deprecation style](../restful_api_styleguide.md#deprecations).
The GraphQL API [has a separate deprecation process](../../../api/graphql/_index.md#deprecation-and-removal-process),
and [style for the deprecation reason](../../api_graphql_styleguide.md#deprecation-reason-style-guide).
+{{< /alert >}}
+
## Features not actively being developed
When a feature is no longer actively developed, but not deprecated, add the following note under
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md
index 1b55e351078fd677174735451c4c19759ec6ba67..ee17af751572d4ad421324d62b9fd640d82762b0 100644
--- a/doc/development/documentation/styleguide/word_list.md
+++ b/doc/development/documentation/styleguide/word_list.md
@@ -2,7 +2,7 @@
stage: none
group: Documentation Guidelines
info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
-description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.'
+description: Writing styles, markup, formatting, and other standards for GitLab Documentation.
title: Recommended word list
---
@@ -820,7 +820,7 @@ Use **drawer** to describe a [drawer UI component](../drawers.md) that:
To see examples of drawers:
-- Go to the [Technical Writing Pipeline Editor](https://gitlab.com/gitlab-org/technical-writing/team-tasks/-/ci/editor?branch_name=main) and select **Help** (**{information-o}**).
+- Go to the [Technical Writing Pipeline Editor](https://gitlab.com/gitlab-org/technical-writing/team-tasks/-/ci/editor?branch_name=main) and select **Help** ({{< icon name="information-o" >}}).
- Open GitLab Duo Chat.
Before using this term, confirm whether **drawer** or [**dialog**](#dialog) is
diff --git a/doc/development/documentation/testing/_index.md b/doc/development/documentation/testing/_index.md
index e4253f980a5003f9ad78529c2ffbb7838a4bbcff..a92dd46109fd70271fe66a6af3f0f7dde9f30133 100644
--- a/doc/development/documentation/testing/_index.md
+++ b/doc/development/documentation/testing/_index.md
@@ -53,7 +53,11 @@ The `docs-lint markdown` job fails if any of these `lint-doc.sh` tests fail:
### Mermaid chart linting
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144328) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144328) in GitLab 16.10.
+
+{{< /history >}}
[Mermaid](https://mermaid.js.org/) builds charts and diagrams from code.
diff --git a/doc/development/documentation/testing/vale.md b/doc/development/documentation/testing/vale.md
index dba2c5237954f25672347b68c67f439b2bf5a964..0e56074573b5535abbf9640c6b4b44dd46947daa 100644
--- a/doc/development/documentation/testing/vale.md
+++ b/doc/development/documentation/testing/vale.md
@@ -102,9 +102,9 @@ The result types have these attributes:
| Result type | Displays in CI/CD job output | Displays in MR diff | Causes CI/CD jobs to fail | Vale rule link |
|--------------|------------------------------|---------------------|---------------------------|----------------|
-| `error` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | [Error-level Vale rules](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=master&scope=blobs&search=level%3A+error+file%3A%5Edoc&snippets=false&utf8=✓) |
-| `warning` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | [Warning-level Vale rules](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=master&scope=blobs&search=level%3A+warning+file%3A%5Edoc&snippets=false&utf8=✓) |
-| `suggestion` | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | [Suggestion-level Vale rules](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=master&scope=blobs&search=level%3A+suggestion+file%3A%5Edoc&snippets=false&utf8=✓) |
+| `error` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | [Error-level Vale rules](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=master&scope=blobs&search=level%3A+error+file%3A%5Edoc&snippets=false&utf8=✓) |
+| `warning` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | [Warning-level Vale rules](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=master&scope=blobs&search=level%3A+warning+file%3A%5Edoc&snippets=false&utf8=✓) |
+| `suggestion` | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | [Suggestion-level Vale rules](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=master&scope=blobs&search=level%3A+suggestion+file%3A%5Edoc&snippets=false&utf8=✓) |
## When to add a new Vale rule
diff --git a/doc/development/documentation/topic_types/version_specific_changes.md b/doc/development/documentation/topic_types/version_specific_changes.md
index 158801a9118e720c28715ff7711be8da26878998..ff2b69344a64380a0ddfa397a200945acc3bded2 100644
--- a/doc/development/documentation/topic_types/version_specific_changes.md
+++ b/doc/development/documentation/topic_types/version_specific_changes.md
@@ -1,8 +1,8 @@
---
-info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
stage: none
group: unassigned
-description: 'Learn how to document version-specific changes'
+info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Learn how to document version-specific changes
title: Version-specific changes
---
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md
index 48984a07c6b8ca05c230557227181a2e45953f0a..380568561b91bee4655b5098c22929df1c885fca 100644
--- a/doc/development/documentation/workflow.md
+++ b/doc/development/documentation/workflow.md
@@ -66,13 +66,16 @@ It includes these labels, which are added to the merge request:
A member of the Technical Writing team adds the [`~Technical Writing` team label](../labels/_index.md#team-labels).
-NOTE:
+{{< alert type="note" >}}
+
With the exception of `/doc/development/documentation`,
technical writers do not review content in the `doc/development` directory.
Any Maintainer can merge content in the `doc/development` directory.
If you would like a technical writer review of content in the `doc/development` directory,
ask in the `#docs` Slack channel.
+{{< /alert >}}
+
## Post-merge reviews
If not assigned to a Technical Writer for review prior to merging, a review must be scheduled
diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md
index fdf52c4b652e7925778e0debf309fdf7b21ee3a0..d0c86989426b7d3aeacb0ae13b714cd4bebd7a08 100644
--- a/doc/development/ee_features.md
+++ b/doc/development/ee_features.md
@@ -1345,11 +1345,14 @@ export default {
</template>
```
-NOTE:
+{{< alert type="note" >}}
+
An EE component can be imported
[asynchronously](https://v2.vuejs.org/v2/guide/components-dynamic-async.html#Async-Components) if
its rendering within CE codebase relies on some check (e.g. a feature flag check).
+{{< /alert >}}
+
Check `glFeatures` to ensure that the Vue components are guarded. The components render only when
the license is present.
@@ -1377,9 +1380,12 @@ export default {
</template>
```
-NOTE:
+{{< alert type="note" >}}
+
Do not use mixins unless ABSOLUTELY NECESSARY. Try to find an alternative pattern.
+{{< /alert >}}
+
##### Recommended alternative approach (named/scoped slots)
- We can use slots and/or scoped slots to achieve the same thing as we did with mixins. If you only need an EE component there is no need to create the CE component.
diff --git a/doc/development/event_store.md b/doc/development/event_store.md
index c3f7cfd7c777d727831ba983a1dd9d406c3fb430..a5d6c20716054e6573f2fbb8ec2b93de29ba5722 100644
--- a/doc/development/event_store.md
+++ b/doc/development/event_store.md
@@ -301,10 +301,13 @@ end
To subscribe the worker to a specific event in `lib/gitlab/event_store.rb`,
add a line like this to the `Gitlab::EventStore.configure!` method:
-WARNING:
+{{< alert type="warning" >}}
+
New workers are recommended to be introduced with a feature flag in order to
[ensure compatibility with canary deployments](sidekiq/compatibility_across_updates.md#adding-new-workers).
+{{< /alert >}}
+
```ruby
module Gitlab
module EventStore
@@ -345,10 +348,13 @@ the condition is met.
This technique can avoid scheduling Sidekiq jobs if the subscriber is interested in a
small subset of events.
-WARNING:
+{{< alert type="warning" >}}
+
When using conditional dispatch it must contain only cheap conditions because they are
executed synchronously every time the given event is published.
+{{< /alert >}}
+
For complex conditions it's best to subscribe to all the events and then handle the logic
in the `handle_event` method of the subscriber worker.
diff --git a/doc/development/experiment_guide/experiment_rollout.md b/doc/development/experiment_guide/experiment_rollout.md
index 37b4e3be7a9743cf00d739a4248e620a2d03e77e..1b9963e872418006e37f144a2a650e15dd88997b 100644
--- a/doc/development/experiment_guide/experiment_rollout.md
+++ b/doc/development/experiment_guide/experiment_rollout.md
@@ -32,11 +32,14 @@ This can be done via ChatOps:
## Notes on feature flags
-NOTE:
+{{< alert type="note" >}}
+
We use the terms "enabled" and "disabled" here, even though it's against our
[documentation style guide recommendations](../documentation/styleguide/word_list.md#enable)
because these are the terms that the feature flag documentation uses.
+{{< /alert >}}
+
You may already be familiar with the concept of feature flags in GitLab, but using
feature flags in experiments is a bit different. While in general terms, a feature flag
is viewed as being either `on` or `off`, this isn't accurate for experiments.
diff --git a/doc/development/experiment_guide/implementing_experiments.md b/doc/development/experiment_guide/implementing_experiments.md
index b80ada0d26be24f3f36e3c1f5520abcd78afddf8..2e6a0004b6c27da43a5b423251bcbd95b4cebf52 100644
--- a/doc/development/experiment_guide/implementing_experiments.md
+++ b/doc/development/experiment_guide/implementing_experiments.md
@@ -68,15 +68,21 @@ variant, and 25% would be assigned the _blue_ variant:
For an even distribution in this example, change the command to set it to 66% instead
of 50.
-NOTE:
+{{< alert type="note" >}}
+
To immediately stop running an experiment, use the
`/chatops run feature set pill_color false` command.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
We strongly recommend using the `--actors` flag when using the ChatOps commands,
as anything else may give odd behaviors due to how the caching of variant assignment is
handled.
+{{< /alert >}}
+
We can also implement this experiment in a HAML file with HTML wrappings:
```haml
@@ -134,18 +140,24 @@ results of the experience we've rendered to that context key. These concepts are
somewhat abstract and hard to understand initially, but this approach enables us to
communicate about experiments as something that's wider than just user behavior.
-NOTE:
+{{< alert type="note" >}}
+
Using `actor:` uses cookies if the `current_user` is nil. If you don't need
cookies though - meaning that the exposed functionality would only be visible to
authenticated users - `{ user: current_user }` would be just as effective.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The caching of variant assignment is done by using this context, and so consider
your impact on the cache size when defining your experiment. If you use
`{ time: Time.current }` you would be inflating the cache size every time the
experiment is run. Not only that, your experiment would not be "sticky" and events
wouldn't be resolvable.
+{{< /alert >}}
+
### Advanced experimentation
There are two ways to implement an experiment:
@@ -192,10 +204,13 @@ experiment(:pill_color, actor: current_user) do |e|
end
```
-NOTE:
+{{< alert type="note" >}}
+
When passing a block to the `experiment` method, it is implicitly invoked as
if `run` has been called.
+{{< /alert >}}
+
#### Segmentation rules
You can use runtime segmentation rules to, for instance, segment contexts into a specific
@@ -226,10 +241,13 @@ defined. The first segmentation rule to produce a truthy result assigns the vari
In our example, any user named `'Richard'`, regardless of account age, is always
assigned the _red_ variant. If you want the opposite logic, flip the order.
-NOTE:
+{{< alert type="note" >}}
+
Keep in mind when defining segmentation rules: after a truthy result, the remaining
segmentation rules are skipped to achieve optimal performance.
+{{< /alert >}}
+
#### Exclusion rules
Exclusion rules are similar to segmentation rules, but are intended to determine
@@ -299,7 +317,8 @@ is run), and we track an event for them, they are assigned a variant and see
that variant if they ever encountered the experiment later, when an `:assignment`
event would be tracked at that time for them.
-NOTE:
+{{< alert type="note" >}}
+
GitLab tries to be sensitive and respectful of our customers regarding tracking,
so our experimentation library allows us to implement an experiment without ever tracking identifying
IDs. It's not always possible, though, based on experiment reporting requirements.
@@ -307,6 +326,8 @@ You may be asked from time to time to track a specific record ID in experiments.
The approach is largely up to the PM and engineer creating the implementation.
No recommendations are provided here at this time.
+{{< /alert >}}
+
## Experiments in the client layer
Any experiment that's been run in the request lifecycle surfaces in `window.gl.experiments`,
@@ -364,5 +385,8 @@ export default {
</template>
```
-NOTE:
+{{< alert type="note" >}}
+
When there is no experiment data in the `window.gl.experiments` object for the given experiment name, the `control` slot is used, if it exists.
+
+{{< /alert >}}
diff --git a/doc/development/experiment_guide/testing_experiments.md b/doc/development/experiment_guide/testing_experiments.md
index 716acac021b4efa950a9771794b9833f955bafdb..fa2906a2cf44ea839a5131cfa7fabc28616b9017 100644
--- a/doc/development/experiment_guide/testing_experiments.md
+++ b/doc/development/experiment_guide/testing_experiments.md
@@ -125,9 +125,12 @@ describe('when my_experiment is enabled', () => {
});
```
-NOTE:
+{{< alert type="note" >}}
+
This method of stubbing in Jest specs does not automatically un-stub itself at the end of the test. We merge our stubbed experiment in with all the other global data in `window.gl`. If you must remove the stubbed experiments after your test or ensure a clean global object before your test, you must manage the global object directly yourself:
+{{< /alert >}}
+
```javascript
describe('tests that care about global state', () => {
const originalObjects = [];
diff --git a/doc/development/export_csv.md b/doc/development/export_csv.md
index 8574768dad1486eed4b3d583e41ee56ae18e707f..9e3d7fe399f39a13cce2f619e324eaed709158be 100644
--- a/doc/development/export_csv.md
+++ b/doc/development/export_csv.md
@@ -16,5 +16,8 @@ This document lists the different implementations of CSV export in GitLab codeba
| Polling (non-persistent state) | - Asynchronously processes the query with the background job.<br>- Frontend(FE) polls every few seconds to check if CSV file is ready. | - Asynchronous processing.<br>- Automatically downloads to local machine on completion.<br>- In-app solution. | - Non-persistable request - request expires when the user goes to a different page.<br>- API is processed for each polling request. | [Export Vulnerabilities](../user/application_security/vulnerability_report/_index.md#export-vulnerability-details) |
| Polling (persistent state) (*) | - Asynchronously processes the query with background job.<br>- Backend (BE) maintains the export state<br>- FE polls every few seconds to check status.<br>- FE shows 'Download link' when export is ready.<br>- User can download or regenerate a new report. | - Asynchronous processing.<br>- No database calls made during the polling requests (HTTP 304 status is returned until export status changes).<br>- Does not require user to stay on page until export is complete.<br>- In-app solution.<br>- Can be expanded into a generic CSV feature (such as dashboard / CSV API). | - Requires to maintain export states in DB.<br>- Does not automatically download the CSV export to local machine, requires users to select 'Download'. | [Export Merge Commits Report](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43055) |
-NOTE:
+{{< alert type="note" >}}
+
Export types marked as * are currently work in progress.
+
+{{< /alert >}}
diff --git a/doc/development/fe_guide/analytics_dashboards.md b/doc/development/fe_guide/analytics_dashboards.md
index 3ce919513921aad5211ea3b15bcb0d331eee4970..a8e8c4f1c72f7f6d33125244e16f28a8644f5594 100644
--- a/doc/development/fe_guide/analytics_dashboards.md
+++ b/doc/development/fe_guide/analytics_dashboards.md
@@ -5,15 +5,22 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Analytics dashboards
---
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98610) in GitLab 15.5 as an [experiment](../../policy/development_stages_support.md#experiment).
-> - Inline visualizations configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/509111) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98610) in GitLab 15.5 as an [experiment](../../policy/development_stages_support.md#experiment).
+- Inline visualizations configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/509111) in GitLab 17.9.
+
+{{< /history >}}
Analytics dashboards provide a configuration-based [dashboard](https://design.gitlab.com/patterns/dashboards)
structure, which is used to render and modify dashboard configurations created by GitLab or users.
-NOTE:
+{{< alert type="note" >}}
+
Analytics dashboards is intended for Premium and Ultimate subscriptions.
+{{< /alert >}}
+
## Customizable dashboard framework
Analytics dashboards utilize a set of standardized UI components that ensure a consistent user experience. These components are modular and can be integrated into other dashboard interfaces where basic visualization capabilities are needed, without advanced features like data fetching, filtering, or editing.
@@ -211,9 +218,12 @@ To add a new data source:
1. Add your module to the list exports in [`data_sources/index.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/assets/javascripts/analytics/analytics_dashboards/data_sources/index.js).
1. Add your data source to the schema's list of `Data` types in [`analytics_visualizations.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/analytics_visualization.json).
-NOTE:
+{{< alert type="note" >}}
+
Your data source must respect the filters so that all panels shows the same filtered data.
+{{< /alert >}}
+
### Adding a new visualization render type
To add a new visualization render type:
diff --git a/doc/development/fe_guide/content_editor.md b/doc/development/fe_guide/content_editor.md
index 998d54705265fa30f90efa1d5b394b8cc426c083..d7d049b20e5266d38da9ac2a8da1895607d6e981 100644
--- a/doc/development/fe_guide/content_editor.md
+++ b/doc/development/fe_guide/content_editor.md
@@ -170,11 +170,14 @@ Node views are located in `~/content_editor/components/wrappers`.
You can inject the Tiptap Editor object to Vue components to dispatch
commands.
-NOTE:
+{{< alert type="note" >}}
+
Do not implement logic that changes the editor's
state in Vue components. Encapsulate this logic in commands, and dispatch
the command from the component's methods.
+{{< /alert >}}
+
```html
<script>
export default {
diff --git a/doc/development/fe_guide/customizable_dashboards.md b/doc/development/fe_guide/customizable_dashboards.md
index fc480b7903d22df2b50dfe7b2b450aa641aeeeb1..64dac71c05b78d138fba83608a569013a5336405 100644
--- a/doc/development/fe_guide/customizable_dashboards.md
+++ b/doc/development/fe_guide/customizable_dashboards.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'analytics_dashboards.md'
-remove_date: '2025-04-17'
+redirect_to: analytics_dashboards.md
+remove_date: "2025-04-17"
---
<!-- markdownlint-disable -->
diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md
index 3b744778386364171e655ca100a7bdcae90d0a07..71cd7dd3e627300d822be41ae4510ca22ef5ad4c 100644
--- a/doc/development/fe_guide/design_patterns.md
+++ b/doc/development/fe_guide/design_patterns.md
@@ -7,10 +7,13 @@ title: Design Patterns
This page covers suggested design patterns and also anti-patterns.
-NOTE:
+{{< alert type="note" >}}
+
When adding a design pattern to this document, be sure to clearly state the **problem it solves**.
When adding a design anti-pattern, clearly state **the problem it prevents**.
+{{< /alert >}}
+
## Patterns
The following design patterns are suggested approaches for solving common problems. Use discretion when evaluating
@@ -24,9 +27,12 @@ generally be avoided.
Throughout the GitLab codebase, there may be historic uses of these anti-patterns. [Use discretion](https://handbook.gitlab.com/handbook/engineering/development/principles/#balance-refactoring-and-velocity)
when figuring out whether or not to refactor, when touching code that uses one of these legacy patterns.
-NOTE:
+{{< alert type="note" >}}
+
For new features, anti-patterns are not necessarily prohibited, but it is **strongly suggested** to find another approach.
+{{< /alert >}}
+
### Shared Global Object
A shared global object is an instance of something that can be accessed from anywhere and therefore has no clear owner.
diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md
index b237ced4fa7f509d5427f15f25dc3a15e90e902d..d2c896945422b385dde87a28ac977de1b18b4fce 100644
--- a/doc/development/fe_guide/frontend_faq.md
+++ b/doc/development/fe_guide/frontend_faq.md
@@ -189,7 +189,7 @@ To see what polyfills are being used:
1. Select the [`compile-production-assets`](https://gitlab.com/gitlab-org/gitlab/-/jobs/641770154) job.
1. In the right-hand sidebar, scroll to **Job Artifacts**, and select **Browse**.
1. Select the **webpack-report** folder to open it, and select **index.html**.
-1. In the upper-left corner of the page, select the right arrow (**{chevron-lg-right}**)
+1. In the upper-left corner of the page, select the right arrow ({{< icon name="chevron-lg-right" >}})
to display the explorer.
1. In the **Search modules** field, enter `gitlab/node_modules/core-js` to see
which polyfills are being loaded and where:
diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md
index 11a78cc2d975fd79c3672b8c646aa0207961f9b3..2eef8357fe6268459e211dd6b5996be1693cc502 100644
--- a/doc/development/fe_guide/graphql.md
+++ b/doc/development/fe_guide/graphql.md
@@ -1315,12 +1315,15 @@ bundle exec rake gitlab:graphql:schema:dump
You should run this task after pulling from upstream, or when rebasing your
branch. This is run automatically as part of `gdk update`.
-NOTE:
+{{< alert type="note" >}}
+
If you use the RubyMine IDE, and have marked the `tmp` directory as
"Excluded", you should "Mark Directory As -> Not Excluded" for
`gitlab/tmp/tests/graphql`. This will allow the **JS GraphQL** plugin to
automatically find and index the schema.
+{{< /alert >}}
+
#### Mocking Apollo Client
To test the components with Apollo operations, we need to mock an Apollo Client in our unit tests. We use [`mock-apollo-client`](https://www.npmjs.com/package/mock-apollo-client) library to mock Apollo client and [`createMockApollo` helper](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/frontend/__helpers__/mock_apollo_helper.js) we created on top of it.
diff --git a/doc/development/fe_guide/haml.md b/doc/development/fe_guide/haml.md
index bdb7df5c3a00a8d2538dbdeced1e99bd2fd91547..978d4dffb766199bfc075487f664274929d1c3b9 100644
--- a/doc/development/fe_guide/haml.md
+++ b/doc/development/fe_guide/haml.md
@@ -77,9 +77,12 @@ For example:
When using the GitLab UI form builder, the following components are available for use in HAML.
-NOTE:
+{{< alert type="note" >}}
+
Currently only the listed components are available but more components are planned.
+{{< /alert >}}
+
#### `gitlab_ui_checkbox_component`
[GitLab UI Docs](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-form-form-checkbox--default)
diff --git a/doc/development/fe_guide/merge_request_widgets.md b/doc/development/fe_guide/merge_request_widgets.md
index d8d01fef1480cff6a1109d144a1577c2ba2e218c..9e5e24dbe41ae811718870c75cd859f2c1ad7fc3 100644
--- a/doc/development/fe_guide/merge_request_widgets.md
+++ b/doc/development/fe_guide/merge_request_widgets.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Review
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: 'Developer documentation for extending the merge request report widget with additional features.'
+description: Developer documentation for extending the merge request report widget with additional features.
title: Merge request widgets
---
@@ -87,11 +87,14 @@ export default {
To fetch data when the widget is mounted, pass the `:fetch-collapsed-data` property a function
that performs an API call.
-WARNING:
+{{< alert type="warning" >}}
+
The function must return a `Promise` that resolves to the `response` object.
The implementation relies on the `POLL-INTERVAL` header to keep polling, therefore it is
important not to alter the status code and headers.
+{{< /alert >}}
+
```vue
<script>
export default {
@@ -187,9 +190,12 @@ Each widget reports:
When adding new widgets, the above events must be marked as `known`, and have metrics
created, to be reportable.
-NOTE:
+{{< alert type="note" >}}
+
Events that are only for EE should include `--ee` at the end of both shell commands below.
+{{< /alert >}}
+
To generate these known events for a single widget:
1. Widgets should be named `Widget${CamelName}`.
diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md
index eae5ae6938d4b51552cdaeb58b1074e6e3473a32..4c4ae81bc7021ff56ce309f7a5bc8588e64e52fa 100644
--- a/doc/development/fe_guide/performance.md
+++ b/doc/development/fe_guide/performance.md
@@ -202,9 +202,12 @@ All the marks and measures should be instantiated with the constants from
`app/assets/javascripts/performance/constants.js`. When you're ready to add a new mark's or
measurement's label, you can follow the pattern.
-NOTE:
+{{< alert type="note" >}}
+
This pattern is a recommendation and not a hard rule.
+{{< /alert >}}
+
```javascript
app-*-start // for a start 'mark'
app-*-end // for an end 'mark'
@@ -343,11 +346,14 @@ Previously, GitLab encouraged the use of
manually generated webpack bundles. However under this new system you should
not ever need to manually add an entry point to the `webpack.config.js` file.
-NOTE:
+{{< alert type="note" >}}
+
When unsure what controller and action corresponds to a page,
inspect `document.body.dataset.page` in your
browser's developer console from any page in GitLab.
+{{< /alert >}}
+
TROUBLESHOOTING:
If using Vite, keep in mind that support for it is new and you may encounter unexpected effects from time to
time. If the entrypoint is correctly configured but the JavaScript is not loading,
diff --git a/doc/development/fe_guide/pinia.md b/doc/development/fe_guide/pinia.md
index f5bd108f9826636b2f36aa95cfce7784e1cd0c97..e10aca9f835ecf8dad783be1b870e9378eb0a813 100644
--- a/doc/development/fe_guide/pinia.md
+++ b/doc/development/fe_guide/pinia.md
@@ -5,11 +5,14 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Pinia
---
-WARNING:
+{{< alert type="warning" >}}
+
**[Pilot Phase](https://gitlab.com/gitlab-org/gitlab/-/issues/479279)**: Adopt Pinia with caution.
This is a new technology at GitLab and we might not have all the necessary precautions and best practices in place yet.
If you're considering using Pinia please drop a message in the `#frontend` internal Slack channel for evaluation.
+{{< /alert >}}
+
[Pinia](https://pinia.vuejs.org/) is a tool for [managing client-side state](state_management.md) for Vue applications.
Refer to the [official documentation](https://pinia.vuejs.org/core-concepts/) on how to use Pinia.
diff --git a/doc/development/fe_guide/sentry.md b/doc/development/fe_guide/sentry.md
index 6c1f70ce598ff683e23d15f22c40fa9a7f0833b3..ee9a69d20ee6e80371660a63ee759fcf07999288 100644
--- a/doc/development/fe_guide/sentry.md
+++ b/doc/development/fe_guide/sentry.md
@@ -12,10 +12,13 @@ GitLab.com is configured to report to our Sentry instance at **Admin > Metrics a
We monitor two kinds of data: **Errors** and **Performance**.
-NOTE:
+{{< alert type="note" >}}
+
The [Frontend Observability Working Group](https://handbook.gitlab.com/handbook/company/working-groups/frontend-observability/) is looking to improve how we use Sentry. GitLab team members can provide feedback at
[issue #427402](https://gitlab.com/gitlab-org/gitlab/-/issues/427402).
+{{< /alert >}}
+
## Start using Sentry
Our Sentry instance is located at [https://new-sentry.gitlab.net/](https://new-sentry.gitlab.net/).
@@ -66,10 +69,13 @@ Once errors are captured, they appear in Sentry. For example you can see the
In the list, select any error to see more details... and ideally propose a solution for it!
-NOTE:
+{{< alert type="note" >}}
+
We suggest filtering errors by the environments `gprd` and `gprd-cny`, as there is some spam in our
environment data.
+{{< /alert >}}
+
### Exploring error data
Team members can use Sentry's [Discover page](https://new-sentry.gitlab.net/organizations/gitlab/discover/homepage/?environment=gprd-cny&environment=gprd&field=title&field=event.type&field=project&field=user.display&field=timestamp&field=replayId&name=All+Events&project=4&query=&sort=-timestamp&statsPeriod=14d&yAxis=count%28%29) to find unexpected issues.
diff --git a/doc/development/fe_guide/state_management.md b/doc/development/fe_guide/state_management.md
index defccddec590e4c9722154af7d2817f68376fcb7..966514918e7feb50bf733638e3d69354350f14d6 100644
--- a/doc/development/fe_guide/state_management.md
+++ b/doc/development/fe_guide/state_management.md
@@ -65,11 +65,14 @@ If you're still uncertain, prefer using Apollo before Pinia.
## Pinia
-WARNING:
+{{< alert type="warning" >}}
+
**[Pilot Phase](https://gitlab.com/gitlab-org/gitlab/-/issues/479279)**: Adopt Pinia with caution.
This is a new technology at GitLab and we might not have all the necessary precautions and best practices in place yet.
If you're considering using Pinia please drop a message in the `#frontend` internal Slack channel for evaluation.
+{{< /alert >}}
+
[Pinia](https://pinia.vuejs.org/) is the client-side state management tool Vue recommends.
[Learn more about Pinia at GitLab](pinia.md).
diff --git a/doc/development/fe_guide/storybook.md b/doc/development/fe_guide/storybook.md
index 915c205e28c7587169932a5b350b874804095d7c..5ae11798a537f3e570dec3c1fe6c1708bf8e7540 100644
--- a/doc/development/fe_guide/storybook.md
+++ b/doc/development/fe_guide/storybook.md
@@ -47,13 +47,16 @@ To add a story:
For instructions on how to write stories, refer to the [official Storybook instructions](https://storybook.js.org/docs/writing-stories/)
- NOTE:
- Specify the `title` field of the story as the component's file path from the `javascripts/` directory, without the `/components` part.
+ {{< alert type="note" >}}
+
+Specify the `title` field of the story as the component's file path from the `javascripts/` directory, without the `/components` part.
For example, if the component is located at `app/assets/javascripts/vue_shared/components/sidebar/todo_toggle/todo_button.vue`,
specify the story `title` as `vue_shared/sidebar/todo_toggle/todo_button`.
If the component is located in the `ee/` directory, make sure to prefix the story's title with `ee/` as well.
This will ensure the Storybook navigation maps closely to our internal directory structure.
+ {{< /alert >}}
+
## Using GitLab REST and GraphQL APIs
You can write stories for components that use either the GitLab [REST](../../api/rest/_index.md) or
@@ -65,8 +68,11 @@ To add a story with API access:
1. Create a [personal access token](../../user/profile/personal_access_tokens.md) in your GitLab instance.
- NOTE:
- If you test against `gitlab.com`, make sure to use a token with `read_api` if possible and to make the token short-lived.
+ {{< alert type="note" >}}
+
+If you test against `gitlab.com`, make sure to use a token with `read_api` if possible and to make the token short-lived.
+
+ {{< /alert >}}
1. Create an `.env` file in the `storybook` directory. Use the `storybook/.env.template` file as
a starting point.
diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md
index 3831886c35beb0e190483c9d8ea01061b4de3fbd..35a0aa249b5e02529ac23f4fdbd4a9b2be03777c 100644
--- a/doc/development/fe_guide/style/javascript.md
+++ b/doc/development/fe_guide/style/javascript.md
@@ -11,9 +11,12 @@ linter to manage most of our JavaScript style guidelines.
In addition to the style guidelines set by Airbnb, we also have a few specific rules
listed below.
-NOTE:
+{{< alert type="note" >}}
+
You can run ESLint locally by running `yarn run lint:eslint:all` or `yarn run lint:eslint $PATH_TO_FILE`.
+{{< /alert >}}
+
## Avoid `forEach`
Avoid `forEach` when mutating data. Use `map`, `reduce` or `filter` instead of `forEach`
@@ -121,9 +124,12 @@ things.map(parseInt);
things.map(Number);
```
-NOTE:
+{{< alert type="note" >}}
+
If the String could represent a non-integer (a number that includes a decimal), **do not** use `parseInt`. Consider `Number` or `parseFloat` instead.
+{{< /alert >}}
+
## CSS Selectors - Use `js-` prefix
If a CSS class is only being used in JavaScript as a reference to the element, prefix
diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md
index 2988f0591083f40ddb4c4b86f33f1d53d1ca9d6f..598977a3c1e3a1dd1e37cd8ef3de2104573318ee 100644
--- a/doc/development/fe_guide/style/scss.md
+++ b/doc/development/fe_guide/style/scss.md
@@ -28,7 +28,8 @@ that use non-design-system values should be avoided. Use classes with conforming
Avoid [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/).
-NOTE:
+{{< alert type="note" >}}
+
While migrating [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/)
to the [GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/css.md#utilities)
utility classes, note both the classes for margin and padding differ. The size scale used at
@@ -36,6 +37,8 @@ GitLab differs from the scale used in the Bootstrap library. For a Bootstrap pad
utility, you may need to double the size of the applied utility to achieve the same visual
result (such as `ml-1` becoming `gl-ml-2`).
+{{< /alert >}}
+
### Tailwind CSS
As of August 2024, we are using [Tailwind CSS](https://tailwindcss.com/) as our CSS utilities provider.
@@ -108,9 +111,12 @@ Tailwind CSS autocomplete lists all available classes in your code editor.
##### VS Code
-NOTE:
+{{< alert type="note" >}}
+
If you are having trouble with slow autocomplete you may need to [increase the amount of memory the TS server is allowed to use](../type_hinting.md#vs-code-settings).
+{{< /alert >}}
+
Install the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
extension. For HAML and custom `*-class` prop support these are the recommended settings:
diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md
index 91b1ed3f91a0689acd5b3ab69bc42a87481c7509..06e06a254fcfafbfc7cf3bdda2fafbb193a08852 100644
--- a/doc/development/fe_guide/tooling.md
+++ b/doc/development/fe_guide/tooling.md
@@ -51,9 +51,12 @@ yarn run lint:eslint:all:fix
If manual changes are required, a list of changes are sent to the console.
-WARNING:
+{{< alert type="warning" >}}
+
Limit use to global rule updates. Otherwise, the changes can lead to huge Merge Requests.
+{{< /alert >}}
+
### Disabling ESLint in new files
Do not disable ESLint when creating new files. Existing files may have existing rules
@@ -131,9 +134,12 @@ It is strongly encouraged that you:
- Put in an **alternative path for developers** looking to use this function.
- **Provide a link to the issue** that tracks the migration process.
-NOTE:
+{{< alert type="note" >}}
+
Uses are detected if you import the deprecated function into another file. They are not detected when the function is used in the same file.
+{{< /alert >}}
+
Running `$ yarn eslint` after this will give us the list of deprecated usages:
```shell
diff --git a/doc/development/fe_guide/type_hinting.md b/doc/development/fe_guide/type_hinting.md
index b68fba5cd02800d0571aae785f4f2450752762e4..d05fb45b20f090f5dc05d13e5f6f501814962592 100644
--- a/doc/development/fe_guide/type_hinting.md
+++ b/doc/development/fe_guide/type_hinting.md
@@ -140,11 +140,14 @@ let wrapper;
wrapper = shallowMount(/* ... */);
```
-NOTE:
+{{< alert type="note" >}}
+
`import()` is [not a native JSDoc construct](https://github.com/jsdoc/jsdoc/issues/1645), but it is
recognized by many IDEs and tools. In this case we're aiming for better clarity in the code and
improved Developer Experience with an IDE.
+{{< /alert >}}
+
#### JSDoc is limited
As was stated above, JSDoc has limited vocabulary. And using it would not describe the type fully.
diff --git a/doc/development/fe_guide/view_component.md b/doc/development/fe_guide/view_component.md
index c3e9c27151a764840762212985f6931e4ac48fbb..9c10be7aa8c734b83d33be3e40282fa63f565902 100644
--- a/doc/development/fe_guide/view_component.md
+++ b/doc/development/fe_guide/view_component.md
@@ -21,11 +21,14 @@ We have a [Lookbook](https://github.com/allmarkedup/lookbook) in `http://gdk.tes
Some of the components of our [Pajamas](https://design.gitlab.com) design system are
available as a ViewComponent in `app/components/pajamas`.
-NOTE:
+{{< alert type="note" >}}
+
We are still in the process of creating these components, so not every Pajamas component is available as ViewComponent.
Reach out to the [Design Systems team](https://handbook.gitlab.com/handbook/engineering/development/dev/foundations/design-system/)
if the component you are looking for is not yet available.
+{{< /alert >}}
+
### Available components
Consider this list a best effort. The full list can be found in [`app/components/pajamas`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/components/pajamas). Also see our Lookbook (`http://gdk.test:3000/rails/lookbook`) for a more interactive way to browse our components.
@@ -177,11 +180,14 @@ For the full list of options, see its
The `Pajamas::CheckboxComponent` follows the [Pajamas Checkbox](https://design.gitlab.com/components/checkbox/) specification.
-NOTE:
+{{< alert type="note" >}}
+
`Pajamas::CheckboxComponent` is used internally by the [GitLab UI form builder](haml.md#use-the-gitlab-ui-form-builder) and requires an instance of [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) to be passed as the `form` argument.
It is preferred to use the [`gitlab_ui_checkbox_component`](haml.md#gitlab_ui_checkbox_component) method to render this ViewComponent.
To use a checkbox without an instance of [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) use [CheckboxTagComponent](#checkbox-tag).
+{{< /alert >}}
+
For the full list of options, see its
[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/components/pajamas/checkbox_component.rb).
@@ -197,10 +203,13 @@ The `Pajamas::ToggleComponent` follows the [Pajamas Toggle](https://design.gitla
Leverage this block to render a rich help text. To render a plain text help text, prefer the `help` parameter.
```
-NOTE:
+{{< alert type="note" >}}
+
**The toggle ViewComponent is special as it depends on the Vue.js component.**
To actually initialize this component, make sure to call the `initToggle` helper from `~/toggles`.
+{{< /alert >}}
+
For the full list of options, see its
[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/components/pajamas/toggle_component.rb).
diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md
index d1a513ad7b3a77bac263a3791ed4be8ff89c490e..591b981fe29fae7ed8922c0e7f682d73404105e0 100644
--- a/doc/development/fe_guide/vue.md
+++ b/doc/development/fe_guide/vue.md
@@ -242,10 +242,13 @@ return new Vue({
});
```
-NOTE:
+{{< alert type="note" >}}
+
When adding an `id` attribute to mount a Vue application, make sure this `id` is unique
across the codebase.
+{{< /alert >}}
+
For more information on why we explicitly declare the data being passed into the Vue app,
refer to our [Vue style guide](style/vue.md#basic-rules).
@@ -922,7 +925,11 @@ You should only apply to be a Vue.js expert when your own merge requests and you
## Vue 2 -> Vue 3 Migration
-> - This section is added temporarily to support the efforts to migrate the codebase from Vue 2.x to Vue 3.x
+{{< history >}}
+
+- This section is added temporarily to support the efforts to migrate the codebase from Vue 2.x to Vue 3.x
+
+{{< /history >}}
We recommend to minimize adding certain features to the codebase to prevent increasing
the tech debt for the eventual migration:
diff --git a/doc/development/fe_guide/vue3_migration.md b/doc/development/fe_guide/vue3_migration.md
index d96809f30ea159ce95b61fdc04f49dd81b862f74..47c14767f9a71112eafb59d6f028fa0f3d26e43f 100644
--- a/doc/development/fe_guide/vue3_migration.md
+++ b/doc/development/fe_guide/vue3_migration.md
@@ -189,9 +189,12 @@ Uncaught TypeError: Cannot read properties of undefined (reading 'loading')
VueApollo v3 (used for Vue.js 2) fails to initialize in Vue.js `compat`
-NOTE:
+{{< alert type="note" >}}
+
While stubbing `Vue.version` will solve VueApollo-related issues in the demo project, it will still lose reactivity on specific scenarios, so an upgrade is still needed
+{{< /alert >}}
+
#### Step 1. Perform upgrade according to library docs
According to [VueApollo v4 installation guide](https://v4.apollo.vuejs.org/guide/installation.html), we need to install `@vue/apollo-option` (this package provides VueApollo support for Options API) and make changes to our application:
@@ -254,9 +257,12 @@ In order to backport this behavior, we need the following knowledge:
- We can access extra options provided to Vue instance via `$options`, so extra `apolloProvider` will be visible as `this.$options.apolloProvider`
- We can access the current `app` (in Vue.js 3 meaning) on the Vue instance via `this.$.appContext.app`
-NOTE:
+{{< alert type="note" >}}
+
We're relying on non-public Vue.js 3 API in this case. However, since `@vue/compat` builds are expected to be available only for 3.2.x branch, we have reduced risks that this API will be changed
+{{< /alert >}}
+
With this knowledge, we can move the initialization of our tooling as early as possible in Vue2 - in the `beforeCreate()` lifecycle hook:
```diff
diff --git a/doc/development/feature_categorization/_index.md b/doc/development/feature_categorization/_index.md
index 990c6bf55979e26d3363a151760956d750827db8..fd25f6f237a4375244ad712b5da6d86b5eebb17d 100644
--- a/doc/development/feature_categorization/_index.md
+++ b/doc/development/feature_categorization/_index.md
@@ -112,9 +112,12 @@ class MyBackgroundMigrationJob < BatchedMigrationJob
end
```
-NOTE:
+{{< alert type="note" >}}
+
[`RuboCop::Cop::BackgroundMigration::FeatureCategory`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/cop/background_migration/feature_category.rb) cop ensures a valid `feature_category` is defined.
+{{< /alert >}}
+
## Rails controllers
Specifying feature categories on controller actions can be done using
diff --git a/doc/development/feature_flags/_index.md b/doc/development/feature_flags/_index.md
index 0d19ad92818b0c4dd7b6660b4d46b7f7e4b10e35..0e0643c76295d569ad78b227b8d9a8b2e836ba9c 100644
--- a/doc/development/feature_flags/_index.md
+++ b/doc/development/feature_flags/_index.md
@@ -1,20 +1,28 @@
---
stage: none
group: unassigned
-info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines"
+info: 'See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines'
title: Feature flags in the development of GitLab
---
-NOTE:
+{{< alert type="note" >}}
+
This document explains how to contribute to the development and operations of the GitLab product.
If you want to use feature flags to show and hide functionality in your own applications,
view [this feature flags information](../../operations/feature_flags.md) instead.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
All newly-introduced feature flags should be [disabled by default](https://handbook.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/).
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
All newly-introduced feature flags should be [used with an actor](controls.md#percentage-based-actor-selection).
+{{< /alert >}}
Design documents:
@@ -298,14 +306,20 @@ Each feature flag is defined in a separate YAML file consisting of a number of f
| `rollout_issue_url` | no | The URL to the Issue covering the feature flag rollout. |
| `log_state_changes` | no | Used to log the state of the feature flag |
-NOTE:
+{{< alert type="note" >}}
+
All validations are skipped when running in `RAILS_ENV=production`.
+{{< /alert >}}
+
## Create a new feature flag
-NOTE:
+{{< alert type="note" >}}
+
GitLab Pages uses [a different process](../pages/_index.md#feature-flags) for feature flags.
+{{< /alert >}}
+
The GitLab codebase provides [`bin/feature-flag`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/bin/feature-flag),
a dedicated tool to create new feature flag definitions.
The tool asks various questions about the new feature flag, then creates
@@ -363,9 +377,12 @@ request removing the feature flag or the merge request where the default value o
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:
+{{< alert type="note" >}}
+
To create a feature flag that is only used in EE, add the `--ee` flag: `bin/feature-flag --ee`
+{{< /alert >}}
+
### Naming new flags
When choosing a name for a new feature flag, consider the following guidelines:
@@ -382,11 +399,14 @@ When choosing a name for a new feature flag, consider the following guidelines:
### Risk of a broken master (main) branch
-WARNING:
+{{< alert type="warning" >}}
+
Feature flags **must** be used in the MR that introduces them. Not doing so causes a
[broken master](https://handbook.gitlab.com/handbook/engineering/workflow/#broken-master) scenario due
to the `rspec:feature-flags` job that only runs on the `master` branch.
+{{< /alert >}}
+
### Optionally add a `.patch` file for automated removal of feature flags
The [`gitlab-housekeeper`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/gems/gitlab-housekeeper) is able to automatically remove your feature flag code for you using the [`DeleteOldFeatureFlags` keep](https://gitlab.com/gitlab-org/gitlab/-/blob/master/keeps/delete_old_feature_flags.rb). The tool will run periodically and automatically clean up old feature flags from the code.
@@ -484,7 +504,8 @@ if Feature.disabled?(:worker_feature_flag, project, type: :worker)
end
```
-WARNING:
+{{< alert type="warning" >}}
+
Don't use feature flags at application load time. For example, using the `Feature` class in
`config/initializers/*` or at the class level could cause an unexpected error. This error occurs
because a database that a feature flag adapter might depend on doesn't exist at load time
@@ -496,6 +517,8 @@ Web/API/Sidekiq fleet on production, which takes time to fully rollout/rollback
these reasons, use environment variables (for example, `ENV['YOUR_FEATURE_NAME']`) or `gitlab.yml`
instead.
+{{< /alert >}}
+
Here's an example of a pattern that you should avoid:
```ruby
@@ -645,9 +668,12 @@ Feature.enabled?(:feature_flag_user, user)
#### Instance actor
-WARNING:
+{{< alert type="warning" >}}
+
Instance-wide feature flags should only be used when a feature is tied in to an entire instance. Always prioritize other actors first.
+{{< /alert >}}
+
In some cases, you may want a feature flag to be enabled for an entire instance and not based on an actor. A great example are the Admin settings, where it would be impossible to enable the Feature Flag based on a group or a project since they are both `undefined`.
The user actor would cause confusion since a Feature Flag might be enabled for a user who is not an admin, but disabled for a user who is.
@@ -660,7 +686,11 @@ Feature.enabled?(:feature_flag, :instance)
#### Current request actor
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132078) in GitLab 16.5
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132078) in GitLab 16.5
+
+{{< /history >}}
It is not recommended to use percentage of time rollout, as each call may return
inconsistent results.
@@ -694,10 +724,13 @@ use `percentage_of_actors`.
#### Use actors for verifying in production
-WARNING:
+{{< alert type="warning" >}}
+
Using production as a testing environment is not recommended. Use our testing
environments for testing features that are not production-ready.
+{{< /alert >}}
+
While the staging environment provides a way to test features in an environment
that resembles production, it doesn't allow you to compare before-and-after
performance metrics specific to production environment. It can be useful to have a
@@ -802,9 +835,12 @@ Usage and state of the feature flag is logged if either:
When the state of a feature flag is logged, it can be identified by using the `"json.feature_flag_states": "feature_flag_name:1"` or `"json.feature_flag_states": "feature_flag_name:0"` condition in Kibana.
You can see an example in [this](https://log.gprd.gitlab.net/app/discover#/?_g=(filters:!(),refreshInterval:(pause:!t,value:60000),time:(from:now-7d%2Fd,to:now))&_a=(columns:!(json.feature_flag_states),filters:!(('$state':(store:appState),meta:(alias:!n,disabled:!f,field:json.feature_flag_states,index:'7092c4e2-4eb5-46f2-8305-a7da2edad090',key:json.feature_flag_states,negate:!f,params:(query:'optimize_where_full_path_in:1'),type:phrase),query:(match_phrase:(json.feature_flag_states:'optimize_where_full_path_in:1')))),hideChart:!f,index:'7092c4e2-4eb5-46f2-8305-a7da2edad090',interval:auto,query:(language:kuery,query:''),sort:!(!(json.time,desc)))) link.
-NOTE:
+{{< alert type="note" >}}
+
Only 20% of the requests log the state of the feature flags. This is controlled with the [`feature_flag_state_logs`](https://gitlab.com/gitlab-org/gitlab/-/blob/6deb6ecbc69f05a80d920a295dfc1a6a303fc7a0/config/feature_flags/ops/feature_flag_state_logs.yml) feature flag.
+{{< /alert >}}
+
## Changelog
We want to avoid introducing a changelog when features are not accessible by an end-user either directly (example: ability to use the feature) or indirectly (examples: ability to take advantage of background jobs, performance improvements, or database migration updates).
@@ -852,9 +888,12 @@ When using the testing environment, all feature flags are enabled by default.
Flags can be disabled by default in the [`spec/spec_helper.rb` file](https://gitlab.com/gitlab-org/gitlab/-/blob/b61fba42eea2cf5bb1ca64e80c067a07ed5d1921/spec/spec_helper.rb#L274).
Add a comment inline to explain why the flag needs to be disabled. You can also attach the issue URL for reference if possible.
-WARNING:
+{{< alert type="warning" >}}
+
This does not apply to end-to-end (QA) tests, which [do not enable feature flags by default](#end-to-end-qa-tests). There is a different [process for using feature flags in end-to-end tests](../testing_guide/end_to_end/best_practices/feature_flags.md).
+{{< /alert >}}
+
To disable a feature flag in a test, use the `stub_feature_flags`
helper. For example, to globally disable the `ci_live_trace` feature
flag in a test:
@@ -1038,10 +1077,13 @@ Deferring jobs can be useful during an incident where contentious behavior from
worker instances are saturating infrastructure resources (such as database and database connection pool).
The implementation can be found at [SkipJobs Sidekiq server middleware](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/sidekiq_middleware/skip_jobs.rb).
-NOTE:
+{{< alert type="note" >}}
+
Jobs are deferred indefinitely as long as the feature flag is disabled. It is important to remove the
feature flag after the worker is deemed safe to continue processing.
+{{< /alert >}}
+
When set to false, 100% of the jobs are deferred. When you want processing to resume, you can
use a **percentage of time** rollout. For example:
@@ -1072,5 +1114,8 @@ Instead of [deferring jobs](#deferring-sidekiq-jobs), jobs can be entirely dropp
/chatops run feature delete drop_sidekiq_jobs_SlowRunningWorker
```
-NOTE:
+{{< alert type="note" >}}
+
Dropping feature flag (`drop_sidekiq_jobs_{WorkerName}`) takes precedence over deferring feature flag (`run_sidekiq_jobs_{WorkerName}`). When `drop_sidekiq_jobs` is enabled and `run_sidekiq_jobs` is disabled, jobs are entirely dropped.
+
+{{< /alert >}}
diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
index 9b75eaf1a574c5d84d7f23c76a1d5022c459f601..bdaa21e0692b9a32b42da9b6b440d6f6981ee405 100644
--- a/doc/development/feature_flags/controls.md
+++ b/doc/development/feature_flags/controls.md
@@ -1,15 +1,18 @@
---
stage: none
group: unassigned
-info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines"
+info: 'See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines'
title: Use ChatOps to enable and disable feature flags
---
-NOTE:
+{{< alert type="note" >}}
+
This document explains how to contribute to the development of the GitLab product.
If you want to use feature flags to show and hide functionality in your own applications,
view [this feature flags information](../../operations/feature_flags.md) instead.
+{{< /alert >}}
+
To turn on/off features behind feature flags in any of the
GitLab-provided environments, like staging and production, you need to
have access to the [ChatOps](../chatops_on_gitlabcom.md) bot. The ChatOps bot
diff --git a/doc/development/fips_compliance.md b/doc/development/fips_compliance.md
index 51fc866bc504a4b072d039e9e636aafa844cc7c1..8772642156a333103cec0d479ee5fdc10cd6c4d5 100644
--- a/doc/development/fips_compliance.md
+++ b/doc/development/fips_compliance.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'fips_gitlab.md'
-remove_date: '2025-04-29'
+redirect_to: fips_gitlab.md
+remove_date: "2025-04-29"
---
<!-- markdownlint-disable -->
diff --git a/doc/development/gems.md b/doc/development/gems.md
index 5effb22c38d00f416832e6a1f54c8d78b8a1feb0..f6f1bfdc10d28bae28ff77a0a2a493bc4ab8e87f 100644
--- a/doc/development/gems.md
+++ b/doc/development/gems.md
@@ -34,10 +34,13 @@ If the answer is **Yes** for any of the questions above, you should strongly con
You can always start by creating a new Gem [in the same repository](#in-the-same-repo) and later evaluate whether to migrate it to a separate repository, when it is intended
to be used by a wider community.
-WARNING:
+{{< alert type="warning" >}}
+
To prevent malicious actors from name-squatting the extracted Gems, follow the instructions
to [reserve a gem name](#reserve-a-gem-name).
+{{< /alert >}}
+
## Advantages of using Gems
Using Gems can provide several benefits for code maintenance:
@@ -79,10 +82,13 @@ and prevents complexity (coordinating changes across repositories, new permissio
Gems stored in the same repository should be referenced in `Gemfile` with the `path:` syntax.
-WARNING:
+{{< alert type="warning" >}}
+
To prevent malicious actors from name-squatting the extracted Gems, follow the instructions
to [reserve a gem name](#reserve-a-gem-name).
+{{< /alert >}}
+
### Create and use a new Gem
You can see example adding a new gem: [!121676](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121676).
diff --git a/doc/development/geo.md b/doc/development/geo.md
index c4d97a8e1a489b2bb2d0ae63503f9070cec62aed..2b0535fc8a9b846147422203dab61d4bf201bc68 100644
--- a/doc/development/geo.md
+++ b/doc/development/geo.md
@@ -333,10 +333,13 @@ Authorization: GL-Geo <access_key>:<JWT payload>
The **primary** site uses the `access_key` field to look up the corresponding
**secondary** site and decrypts the JWT payload.
-NOTE:
+{{< alert type="note" >}}
+
JWT requires synchronized clocks between the machines involved, otherwise the
**primary** site may reject the request.
+{{< /alert >}}
+
### File transfers
When the **secondary** site wishes to download a file, the JWT payload
diff --git a/doc/development/geo/api.md b/doc/development/geo/api.md
index 8fd1a21c26fbc0cf87b0cec19583f05ec703a230..f4103f447162d5bfc307466c557bc773936697c1 100644
--- a/doc/development/geo/api.md
+++ b/doc/development/geo/api.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Geo API
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
The Geo API is used internally by GitLab components to assist in coordinating Geo actions. It is inaccessible to admins or users.
## Fetch pipeline refs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415179) in GitLab 16.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415179) in GitLab 16.7.
+
+{{< /history >}}
This method returns a list of branches matching `pipeline/refs/X` that exist on the repository for `gl_repository` on the current Geo node. This endpoint is used by runners registered with a secondary Geo instance to check if a repository is up to date.
diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md
index f40d4727c171d6210f767f25c07fda242f1ab1b6..0dcd5beaf03bd51c7ef663b6d3bb8c7d478a7e17 100644
--- a/doc/development/geo/framework.md
+++ b/doc/development/geo/framework.md
@@ -5,13 +5,16 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Geo self-service framework
---
-NOTE:
+{{< alert type="note" >}}
+
This document is subject to change as we continue to implement and iterate on the framework.
Follow the progress in the [epic](https://gitlab.com/groups/gitlab-org/-/epics/2161).
If you need to replicate a new data type, reach out to the Geo
team to discuss the options. You can contact them in `#g_geo` on Slack
or mention `@geo-team` in the issue or merge request.
+{{< /alert >}}
+
Geo provides an API to make it possible to easily replicate data types
across Geo sites. This API is presented as a Ruby Domain-Specific
Language (DSL) and aims to make it possible to replicate data with
diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md
index 8c1f6d9169a61652c0ff1f788c8d58dcd59dde06..eecefdf882672ee16d87a6a9f232da7941e201c6 100644
--- a/doc/development/git_object_deduplication.md
+++ b/doc/development/git_object_deduplication.md
@@ -34,11 +34,14 @@ own refs and configuration. Objects in A that are not in B remain in A. For this
configuration to work, **objects must not be deleted from repository B** because
repository A might need them.
-WARNING:
+{{< alert type="warning" >}}
+
Do not run `git prune` or `git gc` in object pool repositories, which are
stored in the `@pools` directory. This can cause data loss in the regular
repositories that depend on the object pool.
+{{< /alert >}}
+
The danger lies in `git prune`, and `git gc` calls `git prune`. The
problem is that `git prune`, when running in a pool repository, cannot
reliably decide if an object is no longer needed.
diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md
index 3a4c0f5f1b85a4685fbe20b486d6f5bae0001a40..1efb37d1a6274b77cb4ada21a293bbf711be0305 100644
--- a/doc/development/gitaly.md
+++ b/doc/development/gitaly.md
@@ -117,12 +117,15 @@ Usually, GitLab CE/EE tests use a local clone of Gitaly in
`GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports also
branches and SHA to use a custom commit in [the repository](https://gitlab.com/gitlab-org/gitaly).
-NOTE:
+{{< alert type="note" >}}
+
With the introduction of auto-deploy for Gitaly, the format of
`GITALY_SERVER_VERSION` was aligned with Omnibus syntax.
It no longer supports `=revision`, it evaluates the file content as a Git
reference (branch or SHA). Only if it matches a semantic version does it prepend a `v`.
+{{< /alert >}}
+
If you want to run tests locally against a modified version of Gitaly you
can replace `tmp/tests/gitaly` with a symlink. This is much faster
because it avoids a Gitaly re-install each time you run `rspec`.
@@ -276,10 +279,13 @@ Pay attention to the name of the flag and the one used in the Rails console. The
between them (dashes replaced by underscores and name prefix is changed). Make sure to prefix all
flags with `gitaly_`.
-NOTE:
+{{< alert type="note" >}}
+
If not set in GitLab, feature flags are read as false from the console and Gitaly uses their
default value. The default value depends on the GitLab version.
+{{< /alert >}}
+
### Testing with GDK
To be sure that the flag is set correctly and it goes into Gitaly, you can check
diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md
index 17e931691ae874bc578c0d86f491c165be6ed3e6..022c89ffd6a6ecde721392e5ad1443bf8c725f2d 100644
--- a/doc/development/github_importer.md
+++ b/doc/development/github_importer.md
@@ -83,9 +83,12 @@ This worker imports all pull requests. For every pull request a job for the
This worker imports only direct repository collaborators who are not outside collaborators.
For every collaborator, we schedule a job for the `Gitlab::GithubImport::ImportCollaboratorWorker` worker.
-NOTE:
+{{< alert type="note" >}}
+
This stage is optional (controlled by `Gitlab::GithubImport::Settings`) and is selected by default.
+{{< /alert >}}
+
### 6. Stage::ImportIssuesAndDiffNotesWorker
This worker imports all issues and pull request comments. For every issue, we
@@ -136,9 +139,12 @@ Each job:
1. Downloads the attachment.
1. Replaces the old link with a newly-generated link to GitLab.
-NOTE:
+{{< alert type="note" >}}
+
It's an optional stage that could consume significant extra import time (controlled by `Gitlab::GithubImport::Settings`).
+{{< /alert >}}
+
### 9. Stage::ImportProtectedBranchesWorker
This worker imports protected branch rules.
diff --git a/doc/development/gitlab_flavored_markdown/_index.md b/doc/development/gitlab_flavored_markdown/_index.md
index b8f31e9484e6aaa80fc374249571a4875da1c200..7a256b09f3065873ec6b123a3ff93be6c2c5e1e1 100644
--- a/doc/development/gitlab_flavored_markdown/_index.md
+++ b/doc/development/gitlab_flavored_markdown/_index.md
@@ -2,7 +2,7 @@
stage: Plan
group: Knowledge
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Development guidelines for GitLab Flavored Markdown (GLFM)."
+description: Development guidelines for GitLab Flavored Markdown (GLFM).
title: GitLab Flavored Markdown (GLFM) development guidelines
---
@@ -24,10 +24,13 @@ Extensions from [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/)
Various [extensions](../../user/markdown.md#differences-with-standard-markdown), such as math and multiline
blockquotes are then added, creating GLFM.
-NOTE:
+{{< alert type="note" >}}
+
In many places in the code, we use `gfm` or `GFM`. In those cases, we're usually
referring to the Markdown in general, not specifically GLFM.
+{{< /alert >}}
+
## Basic flow
To create the HTML displayed to the user, the Markdown is usually processed as follows:
diff --git a/doc/development/gitlab_flavored_markdown/banzai_pipeline_and_parsing.md b/doc/development/gitlab_flavored_markdown/banzai_pipeline_and_parsing.md
index 69b657e7ad64d7f7e7e2c5c1678000cc44529bec..ce6e90a1b0d95a3f85b94520df0f0dbdb3591e8a 100644
--- a/doc/development/gitlab_flavored_markdown/banzai_pipeline_and_parsing.md
+++ b/doc/development/gitlab_flavored_markdown/banzai_pipeline_and_parsing.md
@@ -2,7 +2,7 @@
stage: Plan
group: Knowledge
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "The Banzai pipeline and parsing."
+description: The Banzai pipeline and parsing.
title: The Banzai pipeline and parsing
---
diff --git a/doc/development/gitlab_flavored_markdown/reference_processing.md b/doc/development/gitlab_flavored_markdown/reference_processing.md
index 27241470133688e52f1c4ebfd254ee8af5782a15..c34f83822369c32d5610ba554520f482a784d8d8 100644
--- a/doc/development/gitlab_flavored_markdown/reference_processing.md
+++ b/doc/development/gitlab_flavored_markdown/reference_processing.md
@@ -2,7 +2,7 @@
stage: Plan
group: Knowledge
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: 'An introduction to reference parsers and reference filters, and a guide to their implementation.'
+description: An introduction to reference parsers and reference filters, and a guide to their implementation.
title: Reference processing
---
diff --git a/doc/development/gitlab_shell/features.md b/doc/development/gitlab_shell/features.md
index f09ae2a0274c3ccd564a77e6f2b118cf4b725487..93d18590febb6aad881bca6a5dba2797b4643e5b 100644
--- a/doc/development/gitlab_shell/features.md
+++ b/doc/development/gitlab_shell/features.md
@@ -92,9 +92,9 @@ Expires: 2022-02-05
Administrators can control PAT generation with SSH.
To configure PAT settings in GitLab Shell:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit the `/etc/gitlab/gitlab.rb` file.
1. Add or modify the following configuration:
@@ -109,7 +109,9 @@ To configure PAT settings in GitLab Shell:
1. Save the file and [Restart GitLab](../../administration/restart_gitlab.md).
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Edit the `values.yaml` file:
@@ -132,7 +134,9 @@ To configure PAT settings in GitLab Shell:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit the `docker-compose.yaml` file:
@@ -153,7 +157,9 @@ To configure PAT settings in GitLab Shell:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit the `/home/git/gitlab-shell/config.yml` file:
@@ -177,8 +183,13 @@ To configure PAT settings in GitLab Shell:
sudo service gitlab-shell restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
+
+{{< alert type="note" >}}
-NOTE:
These settings only affect PAT generation with SSH and do not
impact PATs created through the web interface.
+
+{{< /alert >}}
diff --git a/doc/development/gitlab_shell/process.md b/doc/development/gitlab_shell/process.md
index 95c05ff05d01814f041a5b46ab1fb666f631101e..249e988017da64c96ffdb053b38cf12e35aebe5b 100644
--- a/doc/development/gitlab_shell/process.md
+++ b/doc/development/gitlab_shell/process.md
@@ -27,10 +27,13 @@ Rails application:
1. Update `GITLAB_SHELL_VERSION` in the Rails application to the **raw
version**.
- NOTE:
- This can be done as a separate merge request, or in a merge request
+ {{< alert type="note" >}}
+
+This can be done as a separate merge request, or in a merge request
that uses the latest GitLab Shell changes.
+ {{< /alert >}}
+
## Security releases
GitLab Shell is included in the packages we create for GitLab. Each version of
diff --git a/doc/development/go_guide/_index.md b/doc/development/go_guide/_index.md
index 4717561359464f0adf139c20afb23a7c41085561..f7ae7a5b0359be4b1ace47fa8f145ef1c8b9f2ee 100644
--- a/doc/development/go_guide/_index.md
+++ b/doc/development/go_guide/_index.md
@@ -125,10 +125,13 @@ projects:
### Automatic linting
-WARNING:
+{{< alert type="warning" >}}
+
The use of `registry.gitlab.com/gitlab-org/gitlab-build-images:golangci-lint-alpine` has been
[deprecated as of 16.10](https://gitlab.com/gitlab-org/gitlab-build-images/-/issues/131).
+{{< /alert >}}
+
Use the upstream version of [golangci-lint](https://golangci-lint.run/).
See the list of linters [enabled/disabled by default](https://golangci-lint.run/usage/linters/#enabled-by-default).
diff --git a/doc/development/go_guide/go_upgrade.md b/doc/development/go_guide/go_upgrade.md
index 475acbf0879beb67545fa63f854e8961b3d1c356..120d8ea398f95b96ac79d3d8ea9f39fc0dbce1ea 100644
--- a/doc/development/go_guide/go_upgrade.md
+++ b/doc/development/go_guide/go_upgrade.md
@@ -88,19 +88,24 @@ if you need help finding the correct person or labels:
- The issue should be assigned by a member of the maintaining group.
- The milestone should be assigned by a member of the maintaining group.
- NOTE:
- Some overlap exists between project dependencies. When creating an issue for a
+ {{< alert type="note" >}}
+
+Some overlap exists between project dependencies. When creating an issue for a
dependency that is part of a larger product, note the relationship in the issue
body. For example: Projects built in the context of Omnibus GitLab have their
runtime Go version managed by Omnibus, but "support" and compatibility should
be a concern of the individual project. Issues in the parent project's dependencies
issue should be about adding support for the updated Go version.
- NOTE:
- The upgrade issues must include [upgrade validation items](#upgrade-validation)
+ {{< /alert >}}
+
+ {{< alert type="note" >}}
+
+The upgrade issues must include [upgrade validation items](#upgrade-validation)
in their definition of done. Creating a second [performance testing issue](#upgrade-validation)
titled `Validate operation and performance at scale with Go <VERSION_NUMBER>`
is strongly recommended to help with scheduling tasks and managing workloads.
+ {{< /alert >}}
1. Schedule an update with the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit/-/issues):
- Title the issue `Support using Go version <VERSION_NUMBER>`.
@@ -110,10 +115,13 @@ if you need help finding the correct person or labels:
- [Composition Analysis tracker](https://gitlab.com/gitlab-org/gitlab/-/issues).
- [Container Security tracker](https://gitlab.com/gitlab-org/gitlab/-/issues).
- NOTE:
- Updates to these Security analyzers should not block upgrades to Charts or Omnibus since
+ {{< alert type="note" >}}
+
+Updates to these Security analyzers should not block upgrades to Charts or Omnibus since
the analyzers are built independently as separate container images.
+ {{< /alert >}}
+
1. Schedule builder updates with Distribution projects:
- Dependency and GitLab Development Kit issues created in previous steps should be set as blockers.
- Each issue should have the title `Support building with Go <VERSION_NUMBER>` and description as noted:
@@ -135,12 +143,15 @@ if you need help finding the correct person or labels:
Update `BUILDER_IMAGE_REVISION` in `.gitlab-ci.yml` to match tag from builder.
```
- NOTE:
- If the component is not automatically upgraded for [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues)
+ {{< alert type="note" >}}
+
+If the component is not automatically upgraded for [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues)
and [Cloud Native GitLab](https://gitlab.com/gitlab-org/charts/gitlab/-/issues),
issues should be opened in their respective trackers titled `Updated bundled version of COMPONENT_NAME`
and set as blocked by the component's upgrade issue.
+ {{< /alert >}}
+
#### Known dependencies using Go
The directly responsible individual for a Go upgrade must ensure all
diff --git a/doc/development/graphql_guide/authorization.md b/doc/development/graphql_guide/authorization.md
index 08777a2b1ad9f3481efa24c2ebee72e4c5f7490a..55aae0941e8f1edff30b7946cb5cdb5b25324db1 100644
--- a/doc/development/graphql_guide/authorization.md
+++ b/doc/development/graphql_guide/authorization.md
@@ -32,18 +32,21 @@ system as throughout the rest of the application.
Also see [authorizing resources in a mutation](../api_graphql_styleguide.md#authorizing-resources).
-NOTE:
+{{< alert type="note" >}}
+
The best practice is to load only what the currently authenticated user is allowed to
view with our existing finders first, without relying on authorization
to filter the records. This minimizes database queries and unnecessary
authorization checks of the loaded records. It also avoids situations,
such as short pages, which can expose the presence of confidential resources.
+{{< /alert >}}
+
See [`authorization_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/graphql/features/authorization_spec.rb)
for examples of all the authorization schemes discussed here.
<!--
- NOTE: if you change this heading (or the location to this file), make sure to update
+if you change this heading (or the location to this file), make sure to update
the referenced link in rubocop/cop/graphql/authorize_types.rb
-->
@@ -317,9 +320,12 @@ class SomeType < BaseObject
end
```
-NOTE:
+{{< alert type="note" >}}
+
We can optimize the authorization calls with `skip_type_authorization` in this case, because:
+{{< /alert >}}
+
- We already authorize the discussions in `SomeResolver`
- Permissions to read one note or all notes are the same for a discussion
- Permission to read a note or read an emoji are equivalent
diff --git a/doc/development/graphql_guide/batchloader.md b/doc/development/graphql_guide/batchloader.md
index 3af8e021f40e67f2a1375d7cc2552c06e1b100cd..8d1f7da0227cc4bd0e76c34596f83e55f609a464 100644
--- a/doc/development/graphql_guide/batchloader.md
+++ b/doc/development/graphql_guide/batchloader.md
@@ -132,11 +132,14 @@ z.sync
# => will run 1 query
```
-NOTE:
+{{< alert type="note" >}}
+
There is no dependency analysis in the use of batch-loading. There is
a pending queue of requests, and as soon as any one result is needed, all pending
requests are evaluated.
+{{< /alert >}}
+
You should never call `batch.sync` or use `Lazy.force` in resolver code.
If you depend on a lazy value, use `Lazy.with_value` instead:
diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md
index e9f37098db1a439e29a6b96671bfa1a7f0cdb2ea..a67339d4c846037997e7263ab5fd4ea5408b0a37 100644
--- a/doc/development/i18n/externalization.md
+++ b/doc/development/i18n/externalization.md
@@ -9,10 +9,13 @@ For working with internationalization (i18n),
[GNU gettext](https://www.gnu.org/software/gettext/) is used given it's the most
used tool for this task and there are many applications that help us work with it.
-NOTE:
+{{< alert type="note" >}}
+
All `rake` commands described on this page must be run on a GitLab instance. This instance is
usually the GitLab Development Kit (GDK).
+{{< /alert >}}
+
## Setting up the GitLab Development Kit (GDK)
To work on the [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss)
@@ -1031,9 +1034,12 @@ A new language should only be added as an option in User Preferences once at lea
strings have been translated and approved. Even though a larger number of strings may have been
translated, only the approved translations display in the GitLab UI.
-NOTE:
+{{< alert type="note" >}}
+
Languages with less than 2% of translations are not available in the UI.
+{{< /alert >}}
+
Suppose you want to add translations for a new language, for example, French:
1. Register the new language in `lib/gitlab/i18n.rb`:
diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md
index 443a94c4d743a7ebe8937631c146c450d888199c..680f2255de2c3c37a762873d53858d5ccbf44e76 100644
--- a/doc/development/i18n/merging_translations.md
+++ b/doc/development/i18n/merging_translations.md
@@ -67,9 +67,12 @@ have been fixed on the default branch.
## Recreate the GitLab integration in Crowdin
-NOTE:
+{{< alert type="note" >}}
+
These instructions work only for GitLab Team Members.
+{{< /alert >}}
+
If for some reason the GitLab integration in Crowdin doesn't exist, you can
recreate it with the following steps:
diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md
index 259b495743f576aa82d1c0be9849e08750378e3c..99e45236b318b1114e39cb94d1f2df4548c88536 100644
--- a/doc/development/i18n/translation.md
+++ b/doc/development/i18n/translation.md
@@ -43,15 +43,21 @@ Remember to **Save** each translation.
### Context
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature is in [beta](../../policy/development_stages_support.md#beta).
You might get a string similar to the one you want to translate,
so be sure to select the correct string and line of code.
If you cannot find a string with code search, post a comment in Crowdin with that string.
+{{< /alert >}}
+
In Crowdin, each string contains a link that shows all instances of the string in the entire GitLab codebase.
When you translate a string, you can go to the relevant commit or merge request to get more context.
diff --git a/doc/development/import_export.md b/doc/development/import_export.md
index 5c36609decc4ae1a789b0eee067a2453006c422e..9af35e24029aee812f0d3c35fe6d7b9ddda64996 100644
--- a/doc/development/import_export.md
+++ b/doc/development/import_export.md
@@ -5,9 +5,12 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Import/Export development documentation
---
-NOTE:
+{{< alert type="note" >}}
+
To mitigate the risk of introducing bugs and performance issues, newly added relations should be put behind a feature flag.
+{{< /alert >}}
+
General development guidelines and tips for the [Import/Export feature](../user/project/settings/import_export.md).
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> This document is originally based on the [Import/Export 201 presentation available on YouTube](https://www.youtube.com/watch?v=V3i1OfExotE).
diff --git a/doc/development/integrations/_index.md b/doc/development/integrations/_index.md
index 69ce8123b7579d0442e89b7954fbd1364c9289a1..c29e0227d0784e58a326585065dd328bfef15fe1 100644
--- a/doc/development/integrations/_index.md
+++ b/doc/development/integrations/_index.md
@@ -2,7 +2,7 @@
stage: Foundations
group: Import and Integrate
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "GitLab's development guidelines for Integrations"
+description: GitLab's development guidelines for Integrations
title: Integration development guidelines
---
diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md
index eb2df29df61b806b4335be4142eaff620b341660..973746661ce98f3bf39dcc5506cf496067fb2afa 100644
--- a/doc/development/integrations/secure.md
+++ b/doc/development/integrations/secure.md
@@ -309,7 +309,11 @@ You can find the schemas for these scanners here:
### Report validation
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351000) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351000) in GitLab 15.0.
+
+{{< /history >}}
You must ensure that reports generated by the scanner pass validation against the schema version
declared in your reports. Reports that don't pass validation are not ingested by GitLab, and an
diff --git a/doc/development/internal_analytics/_index.md b/doc/development/internal_analytics/_index.md
index 7f44cfff30096458185fe5ea9ae31c517dadeab2..31c654912ede4e09d7ad2f5ce7929f5059da734d 100644
--- a/doc/development/internal_analytics/_index.md
+++ b/doc/development/internal_analytics/_index.md
@@ -64,9 +64,12 @@ It can either be accessed directly via SQL in Snowflake for [ad-hoc analyses](ht
[Tableau](https://handbook.gitlab.com/handbook/business-technology/data-team/platform/tableau/), which has access to Snowflake.
Both platforms need an access request ([Snowflake](https://handbook.gitlab.com/handbook/business-technology/data-team/platform/#warehouse-access), [Tableau](https://handbook.gitlab.com/handbook/business-technology/data-team/platform/tableau/#tableau-online-access)).
-NOTE:
+{{< alert type="note" >}}
+
To track user interactions in the browser, Do-Not-Track (DNT) needs to be disabled. DNT is disabled by default for most browsers.
+{{< /alert >}}
+
### Tableau
Tableau is a data visualization platform and allows building dashboards and GUI based discovery of events and metrics.
diff --git a/doc/development/internal_analytics/browser_sdk.md b/doc/development/internal_analytics/browser_sdk.md
index 5a773d3b2b83167d7488709eb265b229e5ad3c4c..6268cbfb54658c05455360d9aaac89ee07f359b7 100644
--- a/doc/development/internal_analytics/browser_sdk.md
+++ b/doc/development/internal_analytics/browser_sdk.md
@@ -13,21 +13,25 @@ This SDK is for instrumenting web sites and applications to send data for the Gi
Add the NPM package to your package JSON using your preferred package manager:
-::Tabs
+{{< tabs >}}
-:::TabTitle yarn
+{{< tab title="yarn" >}}
```shell
yarn add @gitlab/application-sdk-browser
```
-:::TabTitle npm
+{{< /tab >}}
+
+{{< tab title="npm" >}}
```shell
npm i @gitlab/application-sdk-browser
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
Then, for browser usage import the client SDK:
@@ -190,9 +194,12 @@ glClient.refreshLinkClickTracking();
### `trackError`
-NOTE:
+{{< alert type="note" >}}
+
`trackError` is supported on the Browser SDK, but the resulting events are not used or available.
+{{< /alert >}}
+
Used to capture errors. This works only when the `errorTracking` plugin is enabled. The [plugin](#plugins) is enabled by default.
```javascript
diff --git a/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md b/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md
index 6a5b855e068d296bf1d160cacffeefc72c4e6c47..609fe246fcf571e1e47b84cc586043b5f68be908 100644
--- a/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md
+++ b/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md
@@ -5,9 +5,12 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Event definition guide
---
-NOTE:
+{{< alert type="note" >}}
+
The event dictionary is a work in progress, and this process is subject to change.
+{{< /alert >}}
+
This guide describes the event dictionary and how it's implemented.
## Event definition and validation
diff --git a/doc/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.md b/doc/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.md
index 4a053a40e3846fbc733d13952aa58ffd15411610..5bb82b77920eeae656b3b6402d8979225c632618 100644
--- a/doc/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.md
+++ b/doc/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.md
@@ -5,10 +5,13 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Local setup and debugging
---
-NOTE:
+{{< alert type="note" >}}
+
To track user interactions in the browser, browser settings, such as privacy filters (e.g.
AdBlock, uBlock) and Do-Not-Track (DNT). [Read more about settings that affects tracking](https://snowplow.io/blog/how-many-visitors-block-your-tracking/).
+{{< /alert >}}
+
Internal events are using a tool called Snowplow under the hood. To develop and test internal events, there are several tools to test frontend and backend events:
| Testing Tool | Frontend Tracking | Backend Tracking | Local Development Environment | Production Environment | Shows individual events |
diff --git a/doc/development/internal_analytics/internal_event_instrumentation/migration.md b/doc/development/internal_analytics/internal_event_instrumentation/migration.md
index 9f879cac1a0d4bab3ee47c877716886ca6e156fa..7c5931b8ba63baff14e1303dbfaf35a715aa0d9a 100644
--- a/doc/development/internal_analytics/internal_event_instrumentation/migration.md
+++ b/doc/development/internal_analytics/internal_event_instrumentation/migration.md
@@ -9,10 +9,13 @@ GitLab Internal Events Tracking exposes a unified API on top of the deprecated S
This page describes how you can switch from one of the previous methods to using Internal Events Tracking.
-NOTE:
+{{< alert type="note" >}}
+
Tracking events directly via Snowplow, Redis/RedisHLL is deprecated but won't be removed in the foreseeable future.
While we encourage you to migrate to Internal Event tracking the deprecated methods will continue to work for existing events and metrics.
+{{< /alert >}}
+
## Migrating from existing Snowplow tracking
If you are already tracking events in Snowplow, you can also start collecting metrics from GitLab Self-Managed instances by switching to Internal Events Tracking.
diff --git a/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md b/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md
index 6cd432344fd8f90866d84fadee4cb131b1bdbf7a..80879189a6bb31e349d3f82271e652145e93fb05 100644
--- a/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md
+++ b/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md
@@ -387,10 +387,13 @@ Sometimes we want to send internal events when the component is rendered or load
You can include additional properties with events to save additional data. When included you must define each additional property in the `additional_properties` field. It is possible to send the three built-in additional properties with keys `label` (string), `property` (string) and `value`(numeric) and [custom additional properties](quick_start.md#additional-properties) if the built-in properties are not sufficient.
-NOTE:
+{{< alert type="note" >}}
+
Do not pass the page URL or page path as an additional property because we already track the pseudonymized page URL for each event.
Getting the URL from `window.location` does not pseudonymize project and namespace information [as documented](https://metrics.gitlab.com/identifiers).
+{{< /alert >}}
+
For Vue Mixin:
```javascript
diff --git a/doc/development/internal_analytics/metrics/metrics_dictionary.md b/doc/development/internal_analytics/metrics/metrics_dictionary.md
index 40434aad04bbd511c7492fc05ec15342d513a131..af3558ad4a201690035c6b86d7d032c317d7663c 100644
--- a/doc/development/internal_analytics/metrics/metrics_dictionary.md
+++ b/doc/development/internal_analytics/metrics/metrics_dictionary.md
@@ -29,9 +29,12 @@ All metrics are stored in YAML files:
- [`config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/metrics)
-WARNING:
+{{< alert type="warning" >}}
+
Only metrics with a metric definition YAML and whose status is not `removed` are added to the Service Ping JSON payload.
+{{< /alert >}}
+
Each metric is defined in a YAML file consisting of a number of fields:
| Field | Required | Additional information |
diff --git a/doc/development/internal_analytics/metrics/metrics_instrumentation.md b/doc/development/internal_analytics/metrics/metrics_instrumentation.md
index 0de536a14dca38fe28d0913ed5d7749820702767..6deac249654836c0d183a62f0252033cfde855c2 100644
--- a/doc/development/internal_analytics/metrics/metrics_instrumentation.md
+++ b/doc/development/internal_analytics/metrics/metrics_instrumentation.md
@@ -34,10 +34,13 @@ Using an instrumentation class ensures that metrics can fail safe individually,
## Database metrics
-NOTE:
+{{< alert type="note" >}}
+
Whenever possible we recommend using [internal event tracking](../internal_event_instrumentation/quick_start.md) instead of database metrics.
Database metrics can create unnecessary load on the database of bigger GitLab instances and potential optimisations can affect instance performance.
+{{< /alert >}}
+
You can use database metrics to track data kept in the database, for example, a count of issues that exist on a given instance.
- `operation`: Operations for the given `relation`, one of `count`, `distinct_count`, `sum`, and `average`.
@@ -173,12 +176,15 @@ Estimated batch counter functionality handles `ActiveRecord::StatementInvalid` e
when used through the provided `estimate_batch_distinct_count` method.
Errors return a value of `-1`.
-WARNING:
+{{< alert type="warning" >}}
+
This functionality estimates a distinct count of a specific ActiveRecord_Relation in a given column,
which uses the [HyperLogLog](https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/40671.pdf) algorithm.
As the HyperLogLog algorithm is probabilistic, the **results always include error**.
The highest encountered error rate is 4.9%.
+{{< /alert >}}
+
When correctly used, the `estimate_batch_distinct_count` method enables efficient counting over
columns that contain non-unique values, which cannot be assured by other counters.
diff --git a/doc/development/internal_analytics/metrics/metrics_lifecycle.md b/doc/development/internal_analytics/metrics/metrics_lifecycle.md
index 718956d46a3f101ef0f6cbfbae63090b5133d5d0..ccbd6e9def6fcb048cb02a534917e4c2a8ac7c68 100644
--- a/doc/development/internal_analytics/metrics/metrics_lifecycle.md
+++ b/doc/development/internal_analytics/metrics/metrics_lifecycle.md
@@ -13,9 +13,12 @@ Follow the [metrics instrumentation](metrics_instrumentation.md) guide.
## Change an existing metric
-WARNING:
+{{< alert type="warning" >}}
+
We want to **PREVENT** changes to the calculation logic or important attributes on any metric as this invalidates comparisons of the same metric across different versions of GitLab.
+{{< /alert >}}
+
If you change a metric, you have to consider that not all instances of GitLab are running on the newest version. Old instances will still report the old version of the metric.
Additionally, a metric's reported numbers are primarily interesting compared to previously reported numbers.
As a result, if you need to change one of the following parts of a metric, you need to add a new metric instead. It's your choice whether to keep the old metric alongside the new one or [remove it](#remove-a-metric).
diff --git a/doc/development/internal_analytics/product_analytics.md b/doc/development/internal_analytics/product_analytics.md
index e8a8b95c2b5246794e8e838d30db2ef21e7f2b66..f1b7a8b1f6055f85ea5c52cbf19d5dc5f231f2a6 100644
--- a/doc/development/internal_analytics/product_analytics.md
+++ b/doc/development/internal_analytics/product_analytics.md
@@ -5,29 +5,39 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Product analytics
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
-
-> - Introduced in GitLab 15.4 as an [experiment](../../policy/development_stages_support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default.
-> - `cube_api_proxy` changed to reference only the [product analytics API](../../api/product_analytics.md) in GitLab 15.6.
-> - `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10.
-> - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11.
-> - Snowplow integration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398253) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `product_analytics_snowplow_support`. Disabled by default.
-> - Snowplow integration feature flag `product_analytics_snowplow_support` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130228) in GitLab 16.4.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/414865) from GitLab Self-Managed to GitLab.com in 16.7.
-> - Enabled in GitLab 16.7 as a [beta](../../policy/development_stages_support.md#beta) feature.
-> - `product_analytics_dashboards` [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/398653) by default in GitLab 16.11.
-> - Feature flag `product_analytics_dashboards` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454059) in GitLab 17.1.
-> - Funnels support removed in GitLab 17.4.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167192) to beta and feature flags `product_analytics_admin_settings` and [`product_analytics_features`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167296) added in GitLab 17.5. Disabled by default.
-
-FLAG:
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced in GitLab 15.4 as an [experiment](../../policy/development_stages_support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default.
+- `cube_api_proxy` changed to reference only the [product analytics API](../../api/product_analytics.md) in GitLab 15.6.
+- `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10.
+- `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11.
+- Snowplow integration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398253) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `product_analytics_snowplow_support`. Disabled by default.
+- Snowplow integration feature flag `product_analytics_snowplow_support` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130228) in GitLab 16.4.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/414865) from GitLab Self-Managed to GitLab.com in 16.7.
+- Enabled in GitLab 16.7 as a [beta](../../policy/development_stages_support.md#beta) feature.
+- `product_analytics_dashboards` [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/398653) by default in GitLab 16.11.
+- Feature flag `product_analytics_dashboards` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454059) in GitLab 17.1.
+- Funnels support removed in GitLab 17.4.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167192) to beta and feature flags `product_analytics_admin_settings` and [`product_analytics_features`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167296) added in GitLab 17.5. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
+
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is not ready for production use.
+{{< /alert >}}
+
The product analytics feature empowers you to track user behavior and gain insights into how your
applications are used and how users interact with your product.
By using the data collected with product analytics in GitLab, you can better understand your users,
@@ -80,12 +90,16 @@ accDescr: How data is collected, processed, and visualized in dashboards.
## Enable product analytics
-> - Introduced in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default.
-> - Moved behind a [flag](../../administration/feature_flags.md) named `product_analytics_admin_settings` in GitLab 15.7. Disabled by default.
-> - Feature flag `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10.
-> - Feature flag `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11.
-> - Feature flag `product_analytics_admin_settings` [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/385602) by default in GitLab 16.11.
-> - Feature flag `product_analytics_admin_settings` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454342) in GitLab 17.1.
+{{< history >}}
+
+- Introduced in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default.
+- Moved behind a [flag](../../administration/feature_flags.md) named `product_analytics_admin_settings` in GitLab 15.7. Disabled by default.
+- Feature flag `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10.
+- Feature flag `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11.
+- Feature flag `product_analytics_admin_settings` [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/385602) by default in GitLab 16.11.
+- Feature flag `product_analytics_admin_settings` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454342) in GitLab 17.1.
+
+{{< /history >}}
To track events in your project's applications,
you must enable and configure product analytics.
@@ -96,19 +110,24 @@ Your GitLab instance connects to a product analytics provider.
A product analytics provider is the collection of services required to receive,
process, store and query your analytics data.
-::Tabs
+{{< tabs >}}
-:::TabTitle GitLab-managed provider
+{{< tab title="GitLab-managed provider" >}}
-DETAILS:
-**Offering:** GitLab.com
+{{< details >}}
+
+- Offering: GitLab.com
+
+{{< /details >}}
On GitLab.com you can use a GitLab-managed provider offered only in the Google Cloud Platform zone `us-central-1`.
If GitLab manages your product analytics provider, then your analytics data is retained for one year.
You can request to delete your data at any time by [contacting support](https://about.gitlab.com/support/#contact-support).
-:::TabTitle Self-managed provider
+{{< /tab >}}
+
+{{< tab title="Self-managed provider" >}}
>[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117804) in GitLab 16.0.
@@ -120,7 +139,9 @@ On GitLab.com, the self-managed provider details are defined in [project-level s
On GitLab Self-Managed, you must define the self-managed analytics provider in [instance-level settings](#instance-level-settings).
If you need different providers for different projects, you can define additional analytics providers in [project-level settings](#project-level-settings).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Instance-level settings
@@ -130,10 +151,13 @@ Prerequisites:
- You must have administrator access for the instance.
-NOTE:
+{{< alert type="note" >}}
+
These instance-level settings are required to enable product analytics on GitLab Self-Managed,
and cascade to all projects by default.
+{{< /alert >}}
+
To enable product analytics on your instance:
1. On the left sidebar, at the bottom, select **Admin**.
@@ -158,7 +182,11 @@ Prerequisites:
## Onboard a GitLab project
-> - Minimum required role [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/154089/) in GitLab 17.1.
+{{< history >}}
+
+- Minimum required role [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/154089/) in GitLab 17.1.
+
+{{< /history >}}
Prerequisites:
@@ -174,9 +202,9 @@ To onboard a project:
Then continue with the setup depending on the provider type.
-::Tabs
+{{< tabs >}}
-:::TabTitle GitLab-managed provider
+{{< tab title="GitLab-managed provider" >}}
Prerequisites:
@@ -194,7 +222,9 @@ Prerequisites:
Your instance is being created, and the project onboarded.
-:::TabTitle Self-managed provider
+{{< /tab >}}
+
+{{< tab title="Self-managed provider" >}}
1. Select **Connect your own provider**.
1. Configure project-level settings for your self-managed provider:
@@ -207,7 +237,9 @@ Your instance is being created, and the project onboarded.
Your instance is being created, and the project onboarded.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Instrument your application
@@ -215,7 +247,11 @@ You can instrument code to collect data by using [tracking SDKs](../_index.md).
## Product analytics dashboards
-> - Introduced in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. Disabled by default.
+{{< history >}}
+
+- Introduced in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. Disabled by default.
+
+{{< /history >}}
Product analytics dashboards are a subset of dashboards under [Analytics dashboards](../../user/analytics/analytics_dashboards.md).
@@ -236,7 +272,11 @@ When product analytics is enabled and onboarded, two built-in dashboards are ava
### Filling missing data
-> - Introduced in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. Disabled by default.
+{{< history >}}
+
+- Introduced in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. Disabled by default.
+
+{{< /history >}}
When [exporting data](#raw-data-export) or [viewing dashboards](../../user/analytics/analytics_dashboards.md#view-project-dashboards),
if there is no data for a given day, the missing data is autofilled with `0`.
@@ -302,8 +342,12 @@ If the request is successful, the returned JSON includes an array of rows of res
## View product analytics usage quota
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424153) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `product_analytics_usage_quota`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427838) in GitLab 16.7. Feature flag `product_analytics_usage_quota` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424153) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `product_analytics_usage_quota`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427838) in GitLab 16.7. Feature flag `product_analytics_usage_quota` removed.
+
+{{< /history >}}
Product analytics usage quota is calculated from the number of events received from instrumented applications.
diff --git a/doc/development/internal_api/_index.md b/doc/development/internal_api/_index.md
index cc9ea7db0a4e602de57a46cce7bd526cdb23f7c8..e41a0517de2973b76f6731f559b8b7a2f6b04417 100644
--- a/doc/development/internal_api/_index.md
+++ b/doc/development/internal_api/_index.md
@@ -1,7 +1,7 @@
---
stage: Create
group: Source Code
-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"
+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
title: Internal API
---
@@ -465,7 +465,11 @@ Example response:
## GitLab agent endpoints
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/432773) in GitLab 16.7.
+{{< history >}}
+
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/432773) in GitLab 16.7.
+
+{{< /history >}}
The following endpoints are used by the GitLab agent server (`kas`)
for various purposes.
@@ -842,9 +846,12 @@ Example response:
## Group SCIM API
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
The group SCIM API partially implements the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). This API provides the `/groups/:group_path/Users` and `/groups/:group_path/Users/:id` endpoints. The base URL is `<http|https>://<GitLab host>/api/scim/v2`. Because this API is for
**system** use for SCIM provider integration, it is subject to change without notice.
@@ -867,9 +874,12 @@ This group SCIM API is different to the [SCIM API](../../api/scim.md). The SCIM
- Does not implement the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644).
- Gets, checks, updates, and deletes SCIM identities in groups.
-NOTE:
+{{< alert type="note" >}}
+
This API does not require the `Gitlab-Shell-Api-Request` header.
+{{< /alert >}}
+
### Get a list of SCIM provisioned users
This endpoint is used as part of the SCIM syncing mechanism. It returns a list of users depending on the filter used.
@@ -887,9 +897,12 @@ Parameters:
| `startIndex` | integer | no | The 1-based index indicating where to start returning results from. A value of less than one is interpreted as 1. |
| `count` | integer | no | Desired maximum number of query results. |
-NOTE:
+{{< alert type="note" >}}
+
Pagination follows the [SCIM spec](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.4) rather than GitLab pagination as used elsewhere. If records change between requests it is possible for a page to either be missing records that have moved to a different page or repeat records from a previous request.
+{{< /alert >}}
+
Example request filtering on a specific identifier:
```shell
@@ -1020,9 +1033,12 @@ Example response:
Returns a `201` status code if successful.
-NOTE:
+{{< alert type="note" >}}
+
After you create a group SCIM identity for a user, you can see that SCIM identity in the **Admin** area.
+{{< /alert >}}
+
### Update a single SCIM provisioned user
Fields that can be updated are:
@@ -1093,11 +1109,18 @@ Returns an empty response with a `204` status code if successful.
## Instance SCIM API
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378599) in GitLab 15.8.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378599) in GitLab 15.8.
+{{< /history >}}
The instance SCIM API partially implements the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). This API provides the `/application/Users` and `/application/Users/:id` endpoints. The base URL is `<http|https>://<GitLab host>/api/scim/v2`. Because this API is for
**system** use for SCIM provider integration, it is subject to change without notice.
@@ -1119,9 +1142,12 @@ This instance SCIM API is different to the [SCIM API](../../api/scim.md). The SC
- Does not implement the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644).
- Gets, checks, updates, and deletes SCIM identities within groups.
-NOTE:
+{{< alert type="note" >}}
+
This API does not require the `Gitlab-Shell-Api-Request` header.
+{{< /alert >}}
+
### Get a list of SCIM provisioned users
This endpoint is used as part of the SCIM syncing mechanism. It returns a list of users depending on the filter used.
@@ -1138,9 +1164,12 @@ Parameters:
| `startIndex` | integer | no | The 1-based index indicating where to start returning results from. A value of less than one is interpreted as 1. |
| `count` | integer | no | Desired maximum number of query results. |
-NOTE:
+{{< alert type="note" >}}
+
Pagination follows the [SCIM spec](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.4) rather than GitLab pagination as used elsewhere. If records change between requests it is possible for a page to either be missing records that have moved to a different page or repeat records from a previous request.
+{{< /alert >}}
+
Example request:
```shell
diff --git a/doc/development/internal_api/gitlab_subscriptions.md b/doc/development/internal_api/gitlab_subscriptions.md
index 5bdb6b984f3316ae8512c905d868497717b5ce83..444a7bff91850f57b9d93fe654888815265e2c5b 100644
--- a/doc/development/internal_api/gitlab_subscriptions.md
+++ b/doc/development/internal_api/gitlab_subscriptions.md
@@ -1,7 +1,7 @@
---
stage: Fulfillment
group: Provision
-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"
+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
title: GitLab Subscriptions Internal API
---
@@ -853,7 +853,11 @@ Example response:
### Compute quota provisioning (deprecated)
-> - [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" and "compute minutes" in GitLab 16.1.
+{{< history >}}
+
+- [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" and "compute minutes" in GitLab 16.1.
+
+{{< /history >}}
The compute quota endpoints are used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
to apply additional packs of compute minutes, for personal namespaces or top-level groups in GitLab.com.
diff --git a/doc/development/internal_api/internal_api_allowed.md b/doc/development/internal_api/internal_api_allowed.md
index 12edbeef42b27d157a42acad38f3543fc555eacd..88b4fc24f1ea41a1845a4ca07c747d1485d91da0 100644
--- a/doc/development/internal_api/internal_api_allowed.md
+++ b/doc/development/internal_api/internal_api_allowed.md
@@ -1,7 +1,7 @@
---
stage: Create
group: Source Code
-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"
+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
title: Internal allowed API
---
@@ -87,7 +87,8 @@ same manner as the standard repositories, and is more prone to the refs issue.
### Parallel push checks
-FLAG:
+{{< alert type="flag" >}}
+
On GitLab Self-Managed, by default this feature is not available. To make it available,
an administrator can [enable the feature flag](../../administration/feature_flags.md) named `parallel_push_checks`.
On GitLab.com, by default this feature is not available. To make it available
@@ -96,6 +97,8 @@ per project, ask GitLab.com administrator to
You should not use this feature for production environments. On GitLab Dedicated, this feature is
not available.
+{{< /alert >}}
+
This experimental feature flag enables the endpoint to run multiple RPCs simultaneously,
reducing the overall time taken by roughly half. This time savings is achieved through
threading, and has potential side effects at large scale. On GitLab.com, this feature flag
diff --git a/doc/development/issue_types.md b/doc/development/issue_types.md
index 508309916b0e5b96cd93f5d59bfc78162f7b809e..e9ffa0e95ae1e3c4aebe1d0f745d66c440e4b001 100644
--- a/doc/development/issue_types.md
+++ b/doc/development/issue_types.md
@@ -5,9 +5,12 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Issue Types (deprecated)
---
-WARNING:
+{{< alert type="warning" >}}
+
We have deprecated Issue Types in favor of [Work Items and Work Item Types](work_items.md).
+{{< /alert >}}
+
Sometimes when a new resource type is added it's not clear if it should be only an
"extension" of Issue (Issue Type) or if it should be a new first-class resource type
(similar to issue, epic, merge request, snippet).
diff --git a/doc/development/jh_features_review.md b/doc/development/jh_features_review.md
index 22e5a36fe0259d3de9b7f069338e9270d52ff8ee..51742a3dbbc13177b1e9baf939154eaac28acc63 100644
--- a/doc/development/jh_features_review.md
+++ b/doc/development/jh_features_review.md
@@ -98,7 +98,8 @@ the relevant EE and JH modules by the name of the receiver module.
If reviewing the corresponding JH file is needed, it should be found at
[JH repository](https://jihulab.com/gitlab-cn/gitlab).
-NOTE:
+{{< alert type="note" >}}
+
In some cases, JH does need to override something we don't need, and in that
case it is ok to also add `prepend_mod` for the modules. When we do this,
also add a comment mentioning it, and a link to the JH module using it.
@@ -106,6 +107,8 @@ This way we know where it's used and when we might not need it anymore,
and we do not remove them only because we're not using it, accidentally
breaking JH. An example of this:
+{{< /alert >}}
+
```ruby
# Added for JiHu
# Used in https://jihulab.com/gitlab-cn/gitlab/-/blob/main-jh/jh/lib/jh/api/integrations.rb
diff --git a/doc/development/language_server/_index.md b/doc/development/language_server/_index.md
index 6814c7f43a7b817065c104c4454bee66e22dc140..d915d80554b60d231b80f24a2bdaaa0fffd93328 100644
--- a/doc/development/language_server/_index.md
+++ b/doc/development/language_server/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../../editor_extensions/language_server/_index.md'
-remove_date: '2025-02-11'
+redirect_to: ../../editor_extensions/language_server/_index.md
+remove_date: "2025-02-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/development/logs.md b/doc/development/logs.md
index 9e38ad6836dd9383a2d0a0969ec72ed24c87c95d..05efe27dc6b6330bd0747b881b07f36ef209e155 100644
--- a/doc/development/logs.md
+++ b/doc/development/logs.md
@@ -5,24 +5,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Logs
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is not under active development.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143027) in GitLab 16.10 [with a flag](../administration/feature_flags.md) named `observability_logs`. Disabled by default. This feature is in [beta](../policy/development_stages_support.md#beta).
-> - Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158786) in GitLab 17.3 to the `observability_features` [feature flag](../administration/feature_flags.md), disabled by default. The previous feature flag (`observability_logs`) was removed.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/100) for GitLab Self-Managed in GitLab 17.3.
-> - [Changed](https://gitlab.com/gitlab-com/marketing/digital-experience/buyer-experience/-/issues/4198) to internal Beta in GitLab 17.7.
+{{< /alert >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143027) in GitLab 16.10 [with a flag](../administration/feature_flags.md) named `observability_logs`. Disabled by default. This feature is in [beta](../policy/development_stages_support.md#beta).
+- Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158786) in GitLab 17.3 to the `observability_features` [feature flag](../administration/feature_flags.md), disabled by default. The previous feature flag (`observability_logs`) was removed.
+- [Introduced](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/100) for GitLab Self-Managed in GitLab 17.3.
+- [Changed](https://gitlab.com/gitlab-com/marketing/digital-experience/buyer-experience/-/issues/4198) to internal Beta in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
GitLab supports centralized application and infrastructure logs collection, storage, and analysis.
GitLab Logging provides insight about the operational health of monitored systems.
Use logs to learn more about your systems and applications in a given range of time.
diff --git a/doc/development/merge_request_concepts/_index.md b/doc/development/merge_request_concepts/_index.md
index 587c9a655ddea3fa65af5c8b03406f05e596c20b..f563f2e0f97274e2cdbd166fd0f7b4c33c491179 100644
--- a/doc/development/merge_request_concepts/_index.md
+++ b/doc/development/merge_request_concepts/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Developer information explaining terminology and features used in merge requests."
+description: Developer information explaining terminology and features used in merge requests.
title: Merge request concepts
---
-NOTE:
+{{< alert type="note" >}}
+
The documentation below is the single source of truth for the merge request terminology and functionality.
+{{< /alert >}}
+
The merge request is made up of several different key components and ideas that encompass the overall merge request experience. These concepts sometimes have competing and confusing terminology or overlap with other concepts. This page covers the following concepts:
1. Merge widget
diff --git a/doc/development/merge_request_concepts/approval_rules.md b/doc/development/merge_request_concepts/approval_rules.md
index 337aed45948ff6732e972b099e4fcb5e353924f5..9662151c36a797dd00dc34ab1a68edb11269e965 100644
--- a/doc/development/merge_request_concepts/approval_rules.md
+++ b/doc/development/merge_request_concepts/approval_rules.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Review
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Developer documentation explaining the design and workflow of merge request approval rules."
+description: Developer documentation explaining the design and workflow of merge request approval rules.
title: Approval rules development guidelines
---
@@ -18,11 +18,14 @@ can change often. The code should explain those things better. The components
mentioned here are the major parts of the application for the approval rules
feature to work.
-NOTE:
+{{< alert type="note" >}}
+
This is a living document and should be updated accordingly when parts
of the codebase touched in this document are changed or removed, or when new components
are added.
+{{< /alert >}}
+
## Data Model
```mermaid
diff --git a/doc/development/merge_request_concepts/diffs/_index.md b/doc/development/merge_request_concepts/diffs/_index.md
index f7e29453a48fad29530dc2f82c3bc6c92f9f3ec6..1951ac9ed036c41a6bd19ab54b770066a2f979e8 100644
--- a/doc/development/merge_request_concepts/diffs/_index.md
+++ b/doc/development/merge_request_concepts/diffs/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Review
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Developer documentation for how diffs are generated and rendered in GitLab."
+description: Developer documentation for how diffs are generated and rendered in GitLab.
title: Working with diffs
---
diff --git a/doc/development/merge_request_concepts/diffs/development.md b/doc/development/merge_request_concepts/diffs/development.md
index f3c0968decaa5121c7871c585a09d20ba62a5b67..4788ebc6f8648d442209f88bd8f0d9e0d9cdd890 100644
--- a/doc/development/merge_request_concepts/diffs/development.md
+++ b/doc/development/merge_request_concepts/diffs/development.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Review
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Developer documentation for the backend design and flow of merge request diffs."
+description: Developer documentation for the backend design and flow of merge request diffs.
title: Merge request diffs development guide
---
@@ -17,11 +17,14 @@ can change often. The code better explains these details. The components
mentioned here are the major parts of the application for how merge request diffs
are generated, stored, and returned to users.
-NOTE:
+{{< alert type="note" >}}
+
This page is a living document. Update it accordingly when the parts
of the codebase touched in this document are changed or removed, or when new components
are added.
+{{< /alert >}}
+
## Data model
Four main ActiveRecord models represent what we collectively refer to
diff --git a/doc/development/merge_request_concepts/diffs/frontend.md b/doc/development/merge_request_concepts/diffs/frontend.md
index 9346a4aae87b437891b8e568b45a263ee02f3664..b5465636686b13ad10478c6c151aa22a4cceb090 100644
--- a/doc/development/merge_request_concepts/diffs/frontend.md
+++ b/doc/development/merge_request_concepts/diffs/frontend.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Review
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Developer documentation explaining how the different parts of the Vue-based frontend diffs are generated."
+description: Developer documentation explaining how the different parts of the Vue-based frontend diffs are generated.
title: Merge request diffs frontend overview
---
@@ -229,11 +229,14 @@ Previously, we had to request two different formats for inline and side-by-side.
then uses this standard format to render the diff line data. With this standard format, the user
can then switch between inline and side-by-side without the need to re-fetch any data.
-NOTE:
+{{< alert type="note" >}}
+
For this component, a lot of the data used and rendered gets memoized and cached, based on
various conditions. It is possible that data sometimes gets cached between each different
component render.
+{{< /alert >}}
+
### Vuex store
The Vuex store for the diffs app consists of 3 different modules:
@@ -333,11 +336,14 @@ formatting happens in a computed property inside the `diff_content.vue` componen
### Render queue
-NOTE:
+{{< alert type="note" >}}
+
This _might_ not be required any more. Some investigation work is required to decide
the future of the render queue. The virtual scroll bar we created has probably removed
any performance benefit we got from this approach.
+{{< /alert >}}
+
To render diffs quickly, we have a render queue that allows the diffs to render only if the
browser is idle. This saves the browser getting frozen when rendering a lot of large diffs at once,
and allows us to reduce the total blocking time.
diff --git a/doc/development/merge_request_concepts/mergeability_framework.md b/doc/development/merge_request_concepts/mergeability_framework.md
index 388a3bd4fcff334663671a9170e53e66e6f7a9ed..444c90acc4dac7c4e5bd455528715366c708c757 100644
--- a/doc/development/merge_request_concepts/mergeability_framework.md
+++ b/doc/development/merge_request_concepts/mergeability_framework.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Review
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Developer information explaining the process to add a new mergeability check"
+description: Developer information explaining the process to add a new mergeability check
title: Mergeability framework
---
diff --git a/doc/development/merge_request_concepts/performance.md b/doc/development/merge_request_concepts/performance.md
index 8b4b51dd015a4a85d98af7f813a1aa9227fdfbde..6b3cdd79d7c9739ff2c50b822745a798060aeec5 100644
--- a/doc/development/merge_request_concepts/performance.md
+++ b/doc/development/merge_request_concepts/performance.md
@@ -207,9 +207,12 @@ with the `MATERIALIZED` keyword. By default CTEs are inlined then [optimized by
When building CTE statements, use the `Gitlab::SQL::CTE` class.
By default, this `Gitlab::SQL::CTE` class forces materialization through adding the `MATERIALIZED` keyword.
-WARNING:
+{{< alert type="warning" >}}
+
Upgrading to GitLab 14.0 requires PostgreSQL 12 or later.
+{{< /alert >}}
+
## Cached Queries
**Summary:** a merge request **should not** execute duplicated cached queries.
diff --git a/doc/development/metrics.md b/doc/development/metrics.md
index 959c03e7424bc90a3324d0220100caa8c62c8ad6..d16982f514b59064b20e030ed6efb38597e0023d 100644
--- a/doc/development/metrics.md
+++ b/doc/development/metrics.md
@@ -5,24 +5,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Metrics
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is not under active development.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124966) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `observability_metrics`. Disabled by default. This feature is an [experiment](../policy/development_stages_support.md#experiment).
-> - Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158786) in GitLab 17.3 to the `observability_features` [feature flag](../administration/feature_flags.md), disabled by default. The previous feature flag (`observability_metrics`) was removed.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/100) for GitLab Self-Managed in GitLab 17.3.
-> - [Changed](https://gitlab.com/gitlab-com/marketing/digital-experience/buyer-experience/-/issues/4198) to internal beta in GitLab 17.7.
+{{< /alert >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124966) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `observability_metrics`. Disabled by default. This feature is an [experiment](../policy/development_stages_support.md#experiment).
+- Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158786) in GitLab 17.3 to the `observability_features` [feature flag](../administration/feature_flags.md), disabled by default. The previous feature flag (`observability_metrics`) was removed.
+- [Introduced](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/100) for GitLab Self-Managed in GitLab 17.3.
+- [Changed](https://gitlab.com/gitlab-com/marketing/digital-experience/buyer-experience/-/issues/4198) to internal beta in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Metrics provide insight about the operational health of monitored systems.
Use metrics to learn more about your systems and applications in a given time range.
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md
index 3f871142642085e457be7bda7977dbfd18e8fccb..23f90a4cfe5099941c5a89f0a4ec7eb76fa8bf45 100644
--- a/doc/development/migration_style_guide.md
+++ b/doc/development/migration_style_guide.md
@@ -63,9 +63,12 @@ work it needs to perform and how long it takes to complete:
- Creating a new table, example: `create_table`.
- Adding a new column to an existing table, example: `add_column`.
- NOTE:
+ {{< alert type="note" >}}
+
Post-deployment migration is often abbreviated as PDM.
+ {{< /alert >}}
+
1. [**Batched background migrations.**](database/batched_background_migrations.md) These aren't regular Rails migrations, but application code that is
executed via Sidekiq jobs, although a post-deployment migration is used to schedule them. Use them only for data migrations that
exceed the timing guidelines for post-deploy migrations. Batched background migrations should _not_ change the schema.
@@ -98,12 +101,17 @@ In general, all migrations for a single deploy shouldn't take longer than
1 hour for GitLab.com. The following guidelines are not hard rules, they were
estimated to keep migration duration to a minimum.
-NOTE:
+{{< alert type="note" >}}
+
Keep in mind that all durations should be measured against GitLab.com.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The result of a [database migration pipeline](database/database_migration_pipeline.md)
includes the timing information for migrations.
+{{< /alert >}}
| Migration Type | Recommended Duration | Notes |
|----|----|---|
@@ -157,11 +165,14 @@ table, that column is added at the bottom. Do not reorder
columns manually for existing tables as this causes confusion to
other people using `db/structure.sql` generated by Rails.
-NOTE:
+{{< alert type="note" >}}
+
[Creating an index asynchronously requires two merge requests.](database/adding_database_indexes.md#add-a-migration-to-create-the-index-synchronously)
When done, commit the schema change in the merge request
that adds the index with `add_concurrent_index`.
+{{< /alert >}}
+
When your local database in your GDK is diverging from the schema from
`main` it might be hard to cleanly commit the schema changes to
Git. In that case you can use the `scripts/regenerate-schema` script to
@@ -283,11 +294,14 @@ rails schema statement: [`add_index`](https://api.rubyonrails.org/classes/Active
This operation is a blocking operation, but it doesn't cause problems because the table is not yet used,
and therefore it does not have any records yet.
-NOTE:
+{{< alert type="note" >}}
+
Subtransactions are [disallowed](https://about.gitlab.com/blog/2021/09/29/why-we-spent-the-last-month-eliminating-postgresql-subtransactions/) in general.
Use multiple, separate transactions
if needed as described in [Heavy operations in a single transaction](#heavy-operations-in-a-single-transaction).
+{{< /alert >}}
+
### Heavy operations in a single transaction
When using a single-transaction migration, a transaction holds a database connection
@@ -316,10 +330,13 @@ depending on [how long a migration takes](#how-long-a-migration-should-take)
they automatically turn off the statement timeout as needed.
In rare cases, you might need to set the timeout limit yourself by [using `disable_statement_timeout`](#temporarily-turn-off-the-statement-timeout-limit).
-NOTE:
+{{< alert type="note" >}}
+
To run migrations, we directly connect to the primary database, bypassing PgBouncer
to control settings like `statement_timeout` and `lock_wait_timeout`.
+{{< /alert >}}
+
#### Temporarily turn off the statement timeout limit
The migration helper `disable_statement_timeout` enables you to
@@ -353,15 +370,20 @@ You should always read `disable_ddl_transaction!` as meaning:
"Do not execute this migration in a single PostgreSQL transaction. I'll open PostgreSQL transaction(s) only _when_ and _if_ I need them."
-NOTE:
+{{< alert type="note" >}}
+
Even if you don't use an explicit PostgreSQL transaction `.transaction` (or `BEGIN; COMMIT;`),
every SQL statement is still executed as a transaction.
See [the PostgreSQL documentation on transactions](https://www.postgresql.org/docs/current/tutorial-transactions.html).
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
In GitLab, we've sometimes referred to
the migrations that used `disable_ddl_transaction!` as non-transactional migrations.
It just meant the migrations were not executed as _single_ transactions.
+{{< /alert >}}
When should you use `disable_ddl_transaction!`? In most cases,
the existing RuboCop rules or migration helpers can detect if you should be
@@ -478,9 +500,12 @@ This script:
1. Updates both the filename and the timestamp within the migration class
1. Handles both regular and post-deployment migrations
-NOTE:
+{{< alert type="note" >}}
+
Run this script before merging if your migrations have been in review for a long time (_> 3 weeks_) or when rebasing old migration branches.
+{{< /alert >}}
+
## Migration helpers and versioning
Various helper methods are available for many common patterns in database migrations. Those
@@ -935,10 +960,13 @@ In this particular case, the default value exists and we're just changing the me
`request_access_enabled` column, which does not imply a rewrite of all the existing records
in the `namespaces` table. Only when creating a new column with a default, all the records are going be rewritten.
-NOTE:
+{{< alert type="note" >}}
+
A faster [ALTER TABLE ADD COLUMN with a non-null default](https://www.depesz.com/2018/04/04/waiting-for-postgresql-11-fast-alter-table-add-column-with-a-non-null-default/)
was introduced on PostgreSQL 11.0, removing the need of rewriting the table when a new column with a default value is added.
+{{< /alert >}}
+
For the reasons mentioned above, it's safe to use `change_column_default` in a single-transaction migration
without requiring `disable_ddl_transaction!`.
@@ -1004,10 +1032,13 @@ end
## Dropping a database table
-NOTE:
+{{< alert type="note" >}}
+
After a table has been dropped, it should be added to the database dictionary, following the
steps in the [database dictionary guide](database/database_dictionary.md#dropping-tables).
+{{< /alert >}}
+
Dropping a database table is uncommon, and the `drop_table` method
provided by Rails is generally considered safe. Before dropping the table,
consider the following:
@@ -1096,7 +1127,11 @@ end
## Dropping a sequence
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88387) in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88387) in GitLab 15.1.
+
+{{< /history >}}
Dropping a sequence is uncommon, but you can use the `drop_sequence` method provided by the database team.
@@ -1128,13 +1163,20 @@ class DropSequenceTest < Gitlab::Database::Migration[2.1]
end
```
-NOTE:
+{{< alert type="note" >}}
+
`add_sequence` should be avoided for columns with foreign keys.
Adding sequence to these columns is **only allowed** in the down method (restore previous schema state).
+{{< /alert >}}
+
## Truncate a table
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117373) in GitLab 15.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117373) in GitLab 15.11.
+
+{{< /history >}}
Truncating a table is uncommon, but you can use the `truncate_tables!` method provided by the database team.
@@ -1148,7 +1190,11 @@ Under the hood, it works like this:
## Swapping primary key
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98645) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98645) in GitLab 15.5.
+
+{{< /history >}}
Swapping the primary key is required to partition a table as the **partition key must be included in the primary key**.
@@ -1181,10 +1227,13 @@ class SwapPrimaryKey < Gitlab::Database::Migration[2.1]
end
```
-NOTE:
+{{< alert type="note" >}}
+
Make sure to introduce the new index beforehand in a separate migration in order
to swap the primary key.
+{{< /alert >}}
+
## Integer column type
By default, an integer column can hold up to a 4-byte (32-bit) number. That is
diff --git a/doc/development/navigation_sidebar.md b/doc/development/navigation_sidebar.md
index d8ee8095e0751d9098098eb681db9a826613e0a0..525638fa1ba8fc07c493fd867072130b64080e80 100644
--- a/doc/development/navigation_sidebar.md
+++ b/doc/development/navigation_sidebar.md
@@ -27,17 +27,24 @@ Pages can render arbitrary content into the sidebar using the `SidebarPortal`
component. Content passed to its default slot is rendered below that
page's navigation items in the sidebar.
-NOTE:
+{{< alert type="note" >}}
+
Only one instance of this component on a given page is supported. This is to
avoid ordering issues and cluttering the sidebar.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
You can use arbitrary content. You should implement nav items by subclassing `::Sidebars::Panel`.
If you must use Vue to render nav items (for example, if you need to use Vue Router) you can make an exception.
However, in the corresponding `panel.rb` file, you must add a comment that explains how the nav items are rendered.
+{{< /alert >}}
+
+{{< alert type="note" >}}
-NOTE:
Do not use the `SidebarPortalTarget` component. It is internal to the sidebar.
+{{< /alert >}}
## Snowplow Tracking
diff --git a/doc/development/observability/_index.md b/doc/development/observability/_index.md
index abda81a3a35776ae035827c720297e83229c818b..1407f2a1d1e497d2747b9ec40111871b7446e7ac 100644
--- a/doc/development/observability/_index.md
+++ b/doc/development/observability/_index.md
@@ -2,7 +2,7 @@
stage: Monitor
group: Platform Insights
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "Documentation for developers interested in contributing features or bugfixes for GitLab Observability."
+description: Documentation for developers interested in contributing features or bugfixes for GitLab Observability.
title: GitLab Observability development guidelines
---
@@ -111,9 +111,12 @@ You can reference the instructions for running the demo app [here](https://opent
exporters: [otlphttp/gitlab]
```
-NOTE:
+{{< alert type="note" >}}
+
For GDK and Docker to communicate you may need to set up a [loopback interface](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/local_network.md#create-loopback-interface).
+{{< /alert >}}
+
1. Save the configuration and start the demo app:
```shell
diff --git a/doc/development/organization/_index.md b/doc/development/organization/_index.md
index 3b4d1ddc6094f5fb2903b81593d1762f9c6b77b3..6da89050e882fafa98d4a0d89ae32896b3b8a702 100644
--- a/doc/development/organization/_index.md
+++ b/doc/development/organization/_index.md
@@ -1,8 +1,8 @@
---
stage: Tenant Scale
group: Organizations
-info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines"
-description: "Development Guidelines: learn about organization when developing GitLab."
+info: 'See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines'
+description: 'Development Guidelines: learn about organization when developing GitLab.'
title: Organization
---
diff --git a/doc/development/packages/dependency_proxy.md b/doc/development/packages/dependency_proxy.md
index 85193276b4829259f998a8502599ae310284a7d1..70c2f1e4f1d163da96945dab5367c0c19afce41c 100644
--- a/doc/development/packages/dependency_proxy.md
+++ b/doc/development/packages/dependency_proxy.md
@@ -8,9 +8,12 @@ title: Dependency Proxy
The Dependency Proxy is a pull-through-cache for public registry images from DockerHub. This document describes how this
feature is constructed in GitLab.
-NOTE:
+{{< alert type="note" >}}
+
Support for private registry images is proposed in [issue 331741](https://gitlab.com/gitlab-org/gitlab/-/issues/331741).
+{{< /alert >}}
+
## Container registry
The Dependency Proxy for the container registry acts a stand-in for a remote container registry. In our case,
diff --git a/doc/development/packages/harbor_registry_development.md b/doc/development/packages/harbor_registry_development.md
index c01b61297fb82922006d550f2013d3ba1487f6d8..4f9457a6391e49c1fb5e38db9a3949235955b05b 100644
--- a/doc/development/packages/harbor_registry_development.md
+++ b/doc/development/packages/harbor_registry_development.md
@@ -135,9 +135,12 @@ The relevant front-end code is located in the `app/assets/javascripts/packages_a
└── utils.js
```
-NOTE:
+{{< alert type="note" >}}
+
You can check out this [discussion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82777#note_1017875324) to see why we use the REST API instead of GraphQL.
+{{< /alert >}}
+
The file `harbor_registry/pages/index.vue` only contains a single Vue router-view component, which goes to the `images list`, `image detail`, and `tags list` pages via `router.js`.
Because `registry_breadcrumb.vue` component does not support multi-level paths, we have reimplemented the `harbor_registry/components/harbor_registry_breadcrumb.vue` component.
diff --git a/doc/development/packages/new_format_development.md b/doc/development/packages/new_format_development.md
index 61acee404908cd24778978ab5f90204ecd20c645..008f71feb6ac984ab47cef7a2dbc4e7bd3bdfc9c 100644
--- a/doc/development/packages/new_format_development.md
+++ b/doc/development/packages/new_format_development.md
@@ -65,9 +65,12 @@ As an MVC, we recommend beginning with a project-level endpoint. A typical itera
Using instance-level endpoints requires [stricter naming conventions](#naming-conventions).
-NOTE:
+{{< alert type="note" >}}
+
Composer package naming scope is Instance Level.
+{{< /alert >}}
+
### Naming conventions
To avoid name conflict for instance-level endpoints you must define a package naming convention
diff --git a/doc/development/pages/_index.md b/doc/development/pages/_index.md
index be7740d9ee8102fa599a41c6dec27a333cb8cdcb..b142b3cf4a5009edae99313a3b2f5b11a0615dc9 100644
--- a/doc/development/pages/_index.md
+++ b/doc/development/pages/_index.md
@@ -2,7 +2,7 @@
stage: Plan
group: Knowledge
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "GitLab's development guidelines for GitLab Pages"
+description: GitLab's development guidelines for GitLab Pages
title: Contribute to GitLab Pages development
---
@@ -243,9 +243,12 @@ make && go test ./ -run TestRedirect
### Feature flags
-WARNING:
+{{< alert type="warning" >}}
+
All newly-introduced feature flags should be [disabled by default](https://handbook.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#how-to-use-feature-flags).
+{{< /alert >}}
+
Consider adding a [feature flag](../feature_flags/_index.md) for any non-trivial changes.
Feature flags can make the release and rollback of these changes easier, avoiding
incidents and downtime. To add a new feature flag to GitLab Pages:
diff --git a/doc/development/pages/dnsmasq.md b/doc/development/pages/dnsmasq.md
index 1b814beeb012371f84f0940be572376f7b5e817d..9490dd7b6adc9d546853ca0a6034f79a96fbbf41 100644
--- a/doc/development/pages/dnsmasq.md
+++ b/doc/development/pages/dnsmasq.md
@@ -2,7 +2,7 @@
stage: Plan
group: Knowledge
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "dnsmasq configuration guidelines for GitLab Pages"
+description: dnsmasq configuration guidelines for GitLab Pages
title: Using `dnsmasq` to dynamically handle GitLab Pages subdomains
---
diff --git a/doc/development/performance.md b/doc/development/performance.md
index b097c0045700d5066bcfea9ff321255a30afc997..9dd5cac07cb39870bfb8057c415272a9c406eb6c 100644
--- a/doc/development/performance.md
+++ b/doc/development/performance.md
@@ -256,11 +256,14 @@ Currently supported profiling targets are:
- Puma worker
- Sidekiq
-NOTE:
+{{< alert type="note" >}}
+
The Puma master process is not supported.
Sending SIGUSR2 to it triggers restarts. In the case of Puma,
take care to only send the signal to Puma workers.
+{{< /alert >}}
+
This can be done via `pkill -USR2 puma:`. The `:` distinguishes between `puma
4.3.3.gitlab.2 ...` (the master process) from `puma: cluster worker 0: ...` (the
worker processes), selecting the latter.
diff --git a/doc/development/permissions/predefined_roles.md b/doc/development/permissions/predefined_roles.md
index c7e308e44210551fcc0e4ce8d62966b55e40238d..d9391371d0e6d6506fe4bc19340f122a9380d0e3 100644
--- a/doc/development/permissions/predefined_roles.md
+++ b/doc/development/permissions/predefined_roles.md
@@ -39,10 +39,13 @@ The visibility level of a group can be changed only if all subgroups and
sub-projects have the same or lower visibility level. For example, a group can be set
to internal only if all subgroups and projects are internal or private.
-WARNING:
+{{< alert type="warning" >}}
+
If you migrate an existing group to a lower visibility level, that action does not migrate subgroups
in the same way. This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/22406).
+{{< /alert >}}
+
Visibility levels can be found in the `Gitlab::VisibilityLevel` module.
### Feature specific permissions
@@ -91,9 +94,12 @@ can still view the groups and their entities (like epics).
Project membership (where the group membership is already taken into account)
is stored in the `project_authorizations` table.
-NOTE:
+{{< alert type="note" >}}
+
Projects in personal namespaces have a maximum role of Owner.
+{{< /alert >}}
+
#### Guest role
A user with the Guest role in GitLab can view project plans, blockers and other
diff --git a/doc/development/pipelines/_index.md b/doc/development/pipelines/_index.md
index 49f12cc20e8c6331e4960c11285406c8f9fe59df..613964444047cdbbe5a61b5f6ebfa6a7e27de4e3 100644
--- a/doc/development/pipelines/_index.md
+++ b/doc/development/pipelines/_index.md
@@ -293,9 +293,12 @@ We have dedicated jobs for each [testing level](../testing_guide/testing_levels.
changes made in your merge request.
If you want to force all the RSpec jobs to run regardless of your changes, you can add the `pipeline:run-all-rspec` label to the merge request.
-WARNING:
+{{< alert type="warning" >}}
+
Forcing all jobs on docs only related MRs would not have the prerequisite jobs and would lead to errors
+{{< /alert >}}
+
### End-to-end jobs
The [`e2e:test-on-omnibus`](../testing_guide/end_to_end/_index.md#using-the-test-on-omnibus-job) child pipeline
@@ -446,23 +449,31 @@ appending `-jh` to the branch name. If a corresponding JH branch is found,
as-if-jh pipeline grabs files from the respective branch, rather than from the
default branch `main-jh`.
-NOTE:
+{{< alert type="note" >}}
+
For now, CI will try to fetch the branch on the [GitLab JH mirror](https://gitlab.com/gitlab-org/gitlab-jh-mirrors/gitlab), so it might take some time for the new JH branch to propagate to the mirror.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
While [GitLab JH validation](https://gitlab.com/gitlab-org-sandbox/gitlab-jh-validation) is a mirror of
[GitLab JH mirror](https://gitlab.com/gitlab-org/gitlab-jh-mirrors/gitlab),
it does not include any corresponding JH branch beside the default `main-jh`.
This is why when we want to fetch corresponding JH branch we should fetch it
from the main mirror, rather than the validation project.
+{{< /alert >}}
#### How as-if-JH pipeline was configured
The whole process looks like this:
-NOTE:
+{{< alert type="note" >}}
+
We only run `sync-as-if-jh-branch` when there are dependencies changes.
+{{< /alert >}}
+
```mermaid
flowchart TD
subgraph "JiHuLab.com"
@@ -657,7 +668,11 @@ If these commands return `undercover: ✅ No coverage is missing in latest chang
### `pajamas_adoption` job
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141368) in GitLab 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141368) in GitLab 16.8.
+
+{{< /history >}}
The `pajamas_adoption` job runs the [Pajamas Adoption Scanner](https://gitlab-org.gitlab.io/frontend/pajamas-adoption-scanner/) in merge requests to prevent regressions in the adoption of the [Pajamas Design System](https://design.gitlab.com/).
diff --git a/doc/development/pipelines/internals.md b/doc/development/pipelines/internals.md
index d673c4e315e19e5b6d2bd70f405dd434d82dd2be..ff8921164a5edbe095a01e09a5097963e84ca9ce 100644
--- a/doc/development/pipelines/internals.md
+++ b/doc/development/pipelines/internals.md
@@ -152,10 +152,13 @@ To work around that, we have a special workflow rule, that overrides the
GITLAB_DEPENDENCY_PROXY_ADDRESS: ""
```
-NOTE:
+{{< alert type="note" >}}
+
We don't directly override the `${GITLAB_DEPENDENCY_PROXY}` variable because group-level
variables have higher precedence over `.gitlab-ci.yml` variables.
+{{< /alert >}}
+
## Common job definitions
Most of the jobs [extend from a few CI definitions](../../ci/yaml/_index.md#extends)
diff --git a/doc/development/pipelines/performance.md b/doc/development/pipelines/performance.md
index 59df92008a8321e4bf640b9c41e15c4fd365ef1a..99d0d0612f37e9c2069c675a754b414bec95595c 100644
--- a/doc/development/pipelines/performance.md
+++ b/doc/development/pipelines/performance.md
@@ -125,9 +125,12 @@ We also changed the `setup-test-env` job to:
1. If the package is retrieved successfully, its content is placed in the right folder (for example, `tmp/tests/gitlab-workhorse`), preventing the building of the binaries when `scripts/setup-test-env` is run later on.
1. If the package URL returns a 404, the behavior doesn't change compared to the current one: the GitLab Workhorse binaries are built as part of `scripts/setup-test-env`.
-NOTE:
+{{< alert type="note" >}}
+
The version of the package is the workhorse tree SHA (for example, `git rev-parse HEAD:workhorse`).
+{{< /alert >}}
+
## `cache-assets`
In [this MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96297),
diff --git a/doc/development/profiling.md b/doc/development/profiling.md
index 634900e0afb243a7be2c84650fdaca8a9e58d12d..d729cd656560510a04946391389118bce2f0ec6d 100644
--- a/doc/development/profiling.md
+++ b/doc/development/profiling.md
@@ -217,9 +217,12 @@ Example output:
}
```
-NOTE:
+{{< alert type="note" >}}
+
This endpoint is only available for Rails web workers. Sidekiq workers cannot be inspected this way.
+{{< /alert >}}
+
## Settings that impact performance
### Application settings
diff --git a/doc/development/project_templates/_index.md b/doc/development/project_templates/_index.md
index adb70d2a6359ba7e464e6fb0fd7d23f0ad865dff..eb1f5b7e89c33df25d3e4dd75a8f3c95f192ae7c 100644
--- a/doc/development/project_templates/_index.md
+++ b/doc/development/project_templates/_index.md
@@ -14,10 +14,13 @@ designed, as code can change often. To understand how a specific part of the
feature works, view the code and the specs. The details here explain how the
major components of the templating feature work.
-NOTE:
+{{< alert type="note" >}}
+
This document should be updated when parts of the codebase referenced in this
document are updated, removed, or new parts are added.
+{{< /alert >}}
+
## Basic overview
A custom group-level project template is a regular project that is exported and
diff --git a/doc/development/project_templates/add_new_template.md b/doc/development/project_templates/add_new_template.md
index d937cedd3e78c77c0c0944c655b79200660045c2..e4f4a2dd1d5c5e64ccae5ec152325f9cc05720b7 100644
--- a/doc/development/project_templates/add_new_template.md
+++ b/doc/development/project_templates/add_new_template.md
@@ -1,7 +1,7 @@
---
stage: Create
group: Source Code
-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"
+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
title: Contribute to built-in project templates
---
@@ -57,9 +57,12 @@ follow the vendoring process to create a working template.
#### Standard template
-NOTE:
+{{< alert type="note" >}}
+
See merge request [25318](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) for an example.
+{{< /alert >}}
+
To contribute a standard template:
1. Add the details of the template in the `localized_templates_table` method in [`lib/gitlab/project_template.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/project_template.rb) using the following scheme:
@@ -73,9 +76,12 @@ To contribute a standard template:
#### Enterprise template
-NOTE:
+{{< alert type="note" >}}
+
See merge request [28187](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28187) for an example.
+{{< /alert >}}
+
To contribute an Enterprise template:
1. Add details of the template in the `localized_ee_templates_table` method in [`ee/lib/ee/gitlab/project_template.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/ee/gitlab/project_template.rb) using the following scheme:
diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md
index 9550a8f6832de89c9f7c21c440a47db6524241a9..5af0010f768399558b50bd537ec6cdc18a7e9ff7 100644
--- a/doc/development/pry_debugging.md
+++ b/doc/development/pry_debugging.md
@@ -16,10 +16,13 @@ You can then connect to this session by using the [pry-shell](https://github.com
You can watch [this video](https://www.youtube.com/watch?v=Lzs_PL_BySo), for more information about
how to use the `pry-shell`.
-WARNING:
+{{< alert type="warning" >}}
+
`binding.pry` can occasionally experience autoloading issues and fail during name resolution.
If needed, `binding.irb` can be used instead with a more limited feature set.
+{{< /alert >}}
+
## `byebug` vs `binding.pry` vs `binding.irb`
`byebug` has a very similar interface as `gdb`, but `byebug` does not
diff --git a/doc/development/push_rules/_index.md b/doc/development/push_rules/_index.md
index 7227ba3f813d18a7c71a0b15b3184c3ae26265ed..1d16fee6f9658621318e047e54d44b9355f891d2 100644
--- a/doc/development/push_rules/_index.md
+++ b/doc/development/push_rules/_index.md
@@ -14,10 +14,13 @@ designed, as code can change often. To understand how a specific part of the
feature works, view the code and the specs. The details here explain how the
major components of the push rules feature work.
-NOTE:
+{{< alert type="note" >}}
+
This document should be updated when parts of the codebase referenced in this
document are updated, removed, or new parts are added.
+{{< /alert >}}
+
## Business logic
The business logic is contained in two main places. The `PushRule` model stores
@@ -82,7 +85,10 @@ graph TD
EE::Gitlab::Checks::PushRuleCheck --> EE::Gitlab::Checks::PushRules::FileSizeCheck
```
-NOTE:
+{{< alert type="note" >}}
+
The `PushRuleCheck` only triggers checks in parallel if the
`parallel_push_checks` feature flag is enabled. Otherwise tag or branch check
runs first, then file size.
+
+{{< /alert >}}
diff --git a/doc/development/rails_endpoints/_index.md b/doc/development/rails_endpoints/_index.md
index 3d2ebe1c71512b68c39e83b1c87198323eb80a6b..333e2ac1064f891558657788c07d4f445ed50711 100644
--- a/doc/development/rails_endpoints/_index.md
+++ b/doc/development/rails_endpoints/_index.md
@@ -1,7 +1,7 @@
---
stage: Create
group: Source Code
-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"
+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
title: Rails Endpoints
---
diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md
index 88f82cdc90229a670604c5d2a332c9d29e352a87..0e8cc6f846dde39e8aa546c3031b7fbaf34a33d6 100644
--- a/doc/development/rake_tasks.md
+++ b/doc/development/rake_tasks.md
@@ -49,9 +49,12 @@ project.
#### Seeding issues for Insights charts
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can seed issues specifically for working with the
[Insights charts](../user/project/insights/_index.md) with the
@@ -527,9 +530,12 @@ For information on updating audit event types documentation, see
## Update OpenAPI client for Error Tracking feature
-NOTE:
+{{< alert type="note" >}}
+
This Rake task needs `docker` to be installed.
+{{< /alert >}}
+
To update generated code for OpenAPI client located in
`gems/error_tracking_open_api` run the following commands:
diff --git a/doc/development/real_time.md b/doc/development/real_time.md
index f4c340276ff265eb8fbecdf11f77e9d9084d0a9f..457645e97c923dac81f5ce1c81c0b8a16d4b2cdf 100644
--- a/doc/development/real_time.md
+++ b/doc/development/real_time.md
@@ -18,11 +18,14 @@ to receive state updates in real-time over a WebSocket.
The following documentation tells you how to build and deploy view components that
receive updates in real-time from the GitLab Ruby on Rails server.
-NOTE:
+{{< alert type="note" >}}
+
Action Cable and GraphQL subscriptions are a work-in-progress and under active development.
Developers must evaluate their use case to check if these are the right tools to use.
If you are not sure, ask for help in the [`#f_real-time` internal Slack channel](https://gitlab.slack.com/archives/CUX9Z2N66).
+{{< /alert >}}
+
## Build real-time view components
Prerequisites:
@@ -39,11 +42,14 @@ To build a real-time view component on GitLab, you must:
### Integrate a Vue component with Apollo subscriptions
-NOTE:
+{{< alert type="note" >}}
+
Our current real-time stack assumes that client code is built using Vue as the rendering layer and
Apollo as the state and networking layer. If you are working with a part of
the GitLab frontend that has not been migrated to Vue + Apollo yet, complete that task first.
+{{< /alert >}}
+
Consider a hypothetical `IssueView` Vue component that observes and renders GitLab `Issue` data.
For simplicity, we assume here that all it does is render an issue's title and description:
@@ -278,9 +284,12 @@ module Types
end
```
-NOTE:
+{{< alert type="note" >}}
+
If you are connecting an EE subscription, update `EE::Types::SubscriptionType` instead.
+{{< /alert >}}
+
Make sure the `:issue_updated` argument matches the name used in the `subscription` request sent by the frontend in camel-case (`issueUpdated`), or `graphql-ruby` does not know which subscribers to inform. The event can now trigger.
#### Add the new trigger
@@ -301,9 +310,12 @@ module GraphqlTriggers
end
```
-NOTE:
+{{< alert type="note" >}}
+
If the trigger is for an EE subscription, update `EE::GraphqlTriggers` instead.
+{{< /alert >}}
+
- The first argument, `:issue_updated`, must match the `field` name used in the previous
step.
- The argument hash specifies the issue for which we publish the event.
@@ -411,11 +423,14 @@ Because a push initiated by the server needs to propagate over the network and t
in the client without any user interaction whatsoever, real-time features can only be understood
by looking at the entire stack including frontend and backend.
-NOTE:
+{{< alert type="note" >}}
+
For historic reasons, the controller routes that service updates in response to clients polling
for changes are called `realtime_changes`. They use conditional GET requests and are unrelated
to the real-time behavior covered in this guide.
+{{< /alert >}}
+
Any real-time update pushed into a client originates from the GitLab Rails application. We use the following
technologies to initiate and service these updates:
@@ -504,13 +519,16 @@ Action Cable supports different implementations to track which client is subscri
Shared storage is necessary because different clients might connect to the same Action Cable channel
from different Puma instances.
-NOTE:
+{{< alert type="note" >}}
+
Do not confuse Action Cable channels with Redis PubSub channels. An Action Cable `Channel` object is a
programming abstraction to classify and handle the various kinds of data going over the WebSocket connection.
In Action Cable, the underlying PubSub channel is referred to as a broadcasting instead and the association
between a client and a broadcasting is called a subscription. In particular, there can be many broadcastings
(PubSub channels) and subscriptions for each Action Cable `Channel`.
+{{< /alert >}}
+
Because Action Cable allows us to express different kinds of behavior through its `Channel` API, and because
updates to any `Channel` can use the same WebSocket connection, we only require a single WebSocket connection
to be established for each GitLab page to enhance a view component on that page with real-time behavior.
@@ -572,10 +590,13 @@ It simplifies:
- Client-side state management and response caching.
- Integrating GraphQL with view components using a bridge module.
-NOTE:
+{{< alert type="note" >}}
+
When reading the Apollo Client documentation, it assumes that React.js is used for view rendering. We do not use React.js
at GitLab. We use Vue.js, which integrates with Apollo using the [Vue.js adapter](https://apollo.vuejs.org/).
+{{< /alert >}}
+
Apollo provides functions and hooks with which you define how:
- Views send queries, mutations or subscriptions.
diff --git a/doc/development/redis.md b/doc/development/redis.md
index 464e881fa13c385fa7d96f3f93517d05211eb1cd..be1f837fb003c24e71c15c1513aec6176fd7dfc7 100644
--- a/doc/development/redis.md
+++ b/doc/development/redis.md
@@ -122,10 +122,13 @@ requests that read the most data from the cache, we can just sort by
### The slow log
-NOTE:
+{{< alert type="note" >}}
+
There is a [video showing how to see the slow log](https://youtu.be/BBI68QuYRH8) (GitLab internal)
on GitLab.com
+{{< /alert >}}
+
<!-- vale gitlab_base.Substitutions = NO -->
On GitLab.com, entries from the [Redis slow log](https://redis.io/docs/latest/commands/slowlog/) are available in the
@@ -153,7 +156,11 @@ is run manually on an as-needed basis.
## N+1 calls problem
-> - Introduced in [`spec/support/helpers/redis_commands/recorder.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/helpers/redis_commands/recorder.rb) via [`f696f670`](https://gitlab.com/gitlab-org/gitlab/-/commit/f696f670005435472354a3dc0c01aa271aef9e32)
+{{< history >}}
+
+- Introduced in [`spec/support/helpers/redis_commands/recorder.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/helpers/redis_commands/recorder.rb) via [`f696f670`](https://gitlab.com/gitlab-org/gitlab/-/commit/f696f670005435472354a3dc0c01aa271aef9e32)
+
+{{< /history >}}
`RedisCommands::Recorder` is a tool for detecting Redis N+1 calls problem from tests.
diff --git a/doc/development/redis/new_redis_instance.md b/doc/development/redis/new_redis_instance.md
index 72fd7ffc0be0ec3217dae8356d68498808648106..35ca9704a7f61aa40f553c294d7aafa96614a59b 100644
--- a/doc/development/redis/new_redis_instance.md
+++ b/doc/development/redis/new_redis_instance.md
@@ -207,12 +207,17 @@ When a command outside of the supported list is used, `method_missing` will pass
This ensures that anything unexpected behaves like it would before. In development or test environment, an error would be raised for early
detection.
-NOTE:
+{{< alert type="note" >}}
+
By tracking `gitlab_redis_multi_store_method_missing_total` counter and `Gitlab::Redis::MultiStore::MethodMissingError`,
a developer will need to add an implementation for missing Redis commands before proceeding with the migration.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Variable assignments within `pipelined` and `multi` blocks are not advised as the block should be idempotent. Refer to the [corrective fix MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137734) removing non-idempotent blocks which previously led to incorrect application behavior during a migration.
+{{< /alert >}}
##### Errors
diff --git a/doc/development/repository_storage_moves/_index.md b/doc/development/repository_storage_moves/_index.md
index a02aaae257c428da7ee40e5c7b6ca5bbdf60adfc..17aee62a8e4102d921d826262eda97e880af8712 100644
--- a/doc/development/repository_storage_moves/_index.md
+++ b/doc/development/repository_storage_moves/_index.md
@@ -14,10 +14,13 @@ designed, as code can change often. To understand how a specific part of the
feature works, view the code and the specs. The details here explain how the
major components of the Code Owners feature work.
-NOTE:
+{{< alert type="note" >}}
+
This document should be updated when parts of the codebase referenced in this
document are updated, removed, or new parts are added.
+{{< /alert >}}
+
## Business logic
- `Projects::RepositoryStorageMove`: Tracks the move, includes state machine.
diff --git a/doc/development/rubocop_development_guide.md b/doc/development/rubocop_development_guide.md
index e4dbd4f845e9728ea170cb265a0865bd4fa7caca..c6b55e235c041ac73a2607fe1fc603b2606d67e1 100644
--- a/doc/development/rubocop_development_guide.md
+++ b/doc/development/rubocop_development_guide.md
@@ -183,5 +183,8 @@ To reveal existing RuboCop exceptions in the code that have been excluded via
This allows you to reveal existing RuboCop exceptions during your daily work cycle and fix them along the way.
-NOTE:
+{{< alert type="note" >}}
+
Define `Include`s and permanent `Exclude`s in `.rubocop.yml` instead of `.rubocop_todo/**/*.yml`.
+
+{{< /alert >}}
diff --git a/doc/development/ruby_upgrade.md b/doc/development/ruby_upgrade.md
index 2ed15fd99cc3cc3cc97940165b2fcefe5b1f915d..ef0c090cfa989195982d2e92d2b5a1d5c479777f 100644
--- a/doc/development/ruby_upgrade.md
+++ b/doc/development/ruby_upgrade.md
@@ -163,11 +163,14 @@ account of which repositories could be affected.
For smaller version upgrades, it can be acceptable to delay updating libraries that are non-essential or where
we are certain that the main application test suite would catch regressions under a new Ruby version.
-NOTE:
+{{< alert type="note" >}}
+
Consult with the respective code owners whether it is acceptable to merge these changes ahead
of updating the GitLab application. It might be best to get the necessary approvals
but wait to merge the change until everything is ready.
+{{< /alert >}}
+
### Prepare the GitLab application MR
With the dependencies updated and the new gem versions released, you can update the main Rails
@@ -175,11 +178,14 @@ application with any necessary changes, similar to the gems and related systems.
On top of that, update the documentation to reflect the version change in the installation
and update instructions ([example](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68363)).
-NOTE:
+{{< alert type="note" >}}
+
Be especially careful with timing this merge request, since as soon as it is merged, all GitLab contributors
will be affected by it and the changes will be deployed. You must ensure that this MR remains
open until everything else is ready, but it can be useful to get approval early to reduce lead time.
+{{< /alert >}}
+
### Give developers time to upgrade (grace period)
With the new Ruby made available as an option, and all merge requests either ready or merged,
diff --git a/doc/development/search/advanced_search_migration_styleguide.md b/doc/development/search/advanced_search_migration_styleguide.md
index 54f321b4805688929d6b87e9ab3f48fcedc0ee90..87b589c590607f42059f264d7e8f28f2a804a327 100644
--- a/doc/development/search/advanced_search_migration_styleguide.md
+++ b/doc/development/search/advanced_search_migration_styleguide.md
@@ -7,12 +7,19 @@ title: Advanced search migration style guide
## Create a new advanced search migration
-NOTE:
+{{< alert type="note" >}}
+
This functionality is only supported for indices created in GitLab 13.0 and later.
+{{< /alert >}}
+
### With a script
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414674) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414674) in GitLab 16.3.
+
+{{< /history >}}
Execute `scripts/elastic-migration` and follow the prompts to create:
@@ -22,7 +29,11 @@ Execute `scripts/elastic-migration` and follow the prompts to create:
### Manually
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/234046) in GitLab 13.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/234046) in GitLab 13.6.
+
+{{< /history >}}
In the [`ee/elastic/migrate/`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/elastic/migrate) folder, create a new file with the filename format `YYYYMMDDHHMMSS_migration_name.rb`. This format is the same for Rails database migrations.
@@ -237,9 +248,12 @@ Requires:
- The `target_class` and `document_type` methods
- Mappings and index settings for the class
-WARNING:
+{{< alert type="warning" >}}
+
You must perform a follow-up migration to populate the index in the same milestone.
+{{< /alert >}}
+
```ruby
class MigrationName < Elastic::Migration
include Elastic::MigrationCreateIndex
@@ -263,9 +277,12 @@ Reindexes all documents in the index that stores the specified document type and
Requires the `DOCUMENT_TYPE` and `NEW_SCHEMA_VERSION` constants.
The index mapping must have a `schema_version` integer field in a `YYWW` (year/week) format.
-NOTE:
+{{< alert type="note" >}}
+
Previously index mapping `schema_version` used `YYMM` format. New versions should use the `YYWW` format.
+{{< /alert >}}
+
```ruby
class MigrationName < Elastic::Migration
include Search::Elastic::MigrationReindexBasedOnSchemaVersion
@@ -287,9 +304,12 @@ Deletes all documents in the index that stores the specified document type and h
Requires the `DOCUMENT_TYPE` constant and `schema_version` method.
The index mapping must have a `schema_version` integer field in a `YYWW` (year/week) format.
-NOTE:
+{{< alert type="note" >}}
+
Previously index mapping `schema_version` used `YYMM` format. New versions should use the `YYWW` format.
+{{< /alert >}}
+
```ruby
class MigrationName < Elastic::Migration
include ::Search::Elastic::MigrationDeleteBasedOnSchemaVersion
diff --git a/doc/development/sec/analyzer_development_guide.md b/doc/development/sec/analyzer_development_guide.md
index 524f1239f51387aaf4f8d513283b3362c92e1fe0..a52cea6c1c7b11488d38cf29e2ca9af2aa032384 100644
--- a/doc/development/sec/analyzer_development_guide.md
+++ b/doc/development/sec/analyzer_development_guide.md
@@ -252,8 +252,11 @@ The `GITLAB_TOKEN` for the [@gl-service-dev-secure-analyzers-automation](https:/
1. Update the expiry date of the `GITLAB_TOKEN` field in the [Service account used in the automatic release process](#service-account-used-in-the-automatic-release-process) table.
1. Set the following variables to the new Personal Access Token created in step 2 above:
- NOTE:
- It's crucial to [mask and hide](../../ci/variables/_index.md#hide-a-cicd-variable) the following variables.
+ {{< alert type="note" >}}
+
+It's crucial to [mask and hide](../../ci/variables/_index.md#hide-a-cicd-variable) the following variables.
+
+ {{< /alert >}}
1. `GITLAB_TOKEN` CI/CD variable for the [`gitlab-org/security-products/analyzers`](https://gitlab.com/groups/gitlab-org/security-products/analyzers/-/settings/ci_cd#js-cicd-variables-settings) group.
@@ -434,8 +437,11 @@ In order to push images to this location:
1. Configure the following [`CI/CD` environment variables](../../ci/variables/_index.md) for the _analyzer project_, located at `https://gitlab.com/gitlab-org/security-products/analyzers/<ANALYZER_NAME>`:
- NOTE:
- It's crucial to [mask and hide](../../ci/variables/_index.md#hide-a-cicd-variable) the `SEC_REGISTRY_PASSWORD` variable.
+ {{< alert type="note" >}}
+
+It's crucial to [mask and hide](../../ci/variables/_index.md#hide-a-cicd-variable) the `SEC_REGISTRY_PASSWORD` variable.
+
+ {{< /alert >}}
| Key | Value |
|-------------------------|-----------------------------------------------------------------------------|
diff --git a/doc/development/sec/cyclonedx_property_taxonomy.md b/doc/development/sec/cyclonedx_property_taxonomy.md
index 1b23ed609ab4adbab3bdbf226c9feac0ce1a1508..b026a6020162c36322cf109b45f25807853071d6 100644
--- a/doc/development/sec/cyclonedx_property_taxonomy.md
+++ b/doc/development/sec/cyclonedx_property_taxonomy.md
@@ -8,10 +8,13 @@ title: GitLab CycloneDX property taxonomy
This document defines the namespaces and properties used by the `gitlab` namespace
in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy).
-NOTE:
+{{< alert type="note" >}}
+
Before making changes to this file, please reach out to the threat insights engineering team,
`@gitlab-org/govern/threat-insights`.
+{{< /alert >}}
+
## Where properties should be located
The `Property of` column describes what object a property may be attached to.
diff --git a/doc/development/sec/gemnasium_analyzer_data.md b/doc/development/sec/gemnasium_analyzer_data.md
index 7b545142c18958bdd162e71d4b6c128bcbc1b0be..fa1092ddcec2cf4e7567159c5024135dfd42e8a9 100644
--- a/doc/development/sec/gemnasium_analyzer_data.md
+++ b/doc/development/sec/gemnasium_analyzer_data.md
@@ -9,24 +9,24 @@ The following table lists the data available for the Gemnasium analyzer.
| Property \ Tool | Gemnasium |
|:----------------------------------------------|:---------:|
-| Severity | **{check-circle}** Yes |
-| Title | **{check-circle}** Yes |
-| File | **{check-circle}** Yes |
-| Start line | **{dotted-circle}** No |
-| End line | **{dotted-circle}** No |
-| External ID (for example, CVE) | **{check-circle}** Yes |
-| URLs | **{check-circle}** Yes |
-| Internal doc/explanation | **{check-circle}** Yes |
-| Solution | **{check-circle}** Yes |
-| Confidence | **{dotted-circle}** No |
-| Affected item (for example, class or package) | **{check-circle}** Yes |
-| Source code extract | **{dotted-circle}** No |
-| Internal ID | **{check-circle}** Yes |
-| Date | **{check-circle}** Yes |
-| Credits | **{check-circle}** Yes |
+| Severity | {{< icon name="check-circle" >}} Yes |
+| Title | {{< icon name="check-circle" >}} Yes |
+| File | {{< icon name="check-circle" >}} Yes |
+| Start line | {{< icon name="dotted-circle" >}} No |
+| End line | {{< icon name="dotted-circle" >}} No |
+| External ID (for example, CVE) | {{< icon name="check-circle" >}} Yes |
+| URLs | {{< icon name="check-circle" >}} Yes |
+| Internal doc/explanation | {{< icon name="check-circle" >}} Yes |
+| Solution | {{< icon name="check-circle" >}} Yes |
+| Confidence | {{< icon name="dotted-circle" >}} No |
+| Affected item (for example, class or package) | {{< icon name="check-circle" >}} Yes |
+| Source code extract | {{< icon name="dotted-circle" >}} No |
+| Internal ID | {{< icon name="check-circle" >}} Yes |
+| Date | {{< icon name="check-circle" >}} Yes |
+| Credits | {{< icon name="check-circle" >}} Yes |
-- **{check-circle}** Yes => we have that data
-- **{dotted-circle}** No => we don't have that data, or it would need to develop specific or inefficient/unreliable logic to obtain it.
+- {{< icon name="check-circle" >}} Yes => we have that data
+- {{< icon name="dotted-circle" >}} No => we don't have that data, or it would need to develop specific or inefficient/unreliable logic to obtain it.
The values provided by these tools are heterogeneous, so they are sometimes normalized into common
values (for example, `severity`, `confidence`, etc).
diff --git a/doc/development/sec/security_report_ingestion_overview.md b/doc/development/sec/security_report_ingestion_overview.md
index 6cb6b4864dc0d28acb8148d8a7abe6808acd2453..c5e2dbe56bbb7582bd8dfd59bd41b6c641d257b7 100644
--- a/doc/development/sec/security_report_ingestion_overview.md
+++ b/doc/development/sec/security_report_ingestion_overview.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Security report ingestion overview
---
-WARNING:
+{{< alert type="warning" >}}
+
The `Vulnerability::Feedback` model is currently undergoing deprecation and should be actively avoided in all further development. It is currently maintained with feature parity to enable revert should any issues arise, but is intended to be removed in 16.0. Any interactions relating to the Feedback model are superseded by the `StateTransition`, `IssueLink`, and `MergeRequestLink` models. You can find out more on [in this epic](https://gitlab.com/groups/gitlab-org/-/epics/5629).
+{{< /alert >}}
+
## Commonly used terms
### Feedback
diff --git a/doc/development/sec/token_revocation_api.md b/doc/development/sec/token_revocation_api.md
index 9cd864ce566c57aa47fb43c2cb10c3f2281fd537..95c557c17e78cd7e5ee8fb40996ea6126efcbc64 100644
--- a/doc/development/sec/token_revocation_api.md
+++ b/doc/development/sec/token_revocation_api.md
@@ -43,12 +43,15 @@ All endpoints may return these responses:
Returns the valid `type` values for use in the `revoke_tokens` endpoint.
-NOTE:
+{{< alert type="note" >}}
+
These values match the concatenation of [the `secrets` analyzer's](../../user/application_security/secret_detection/pipeline/_index.md)
[primary identifier](../integrations/secure.md#identifiers) by means
of concatenating the `primary_identifier.type` and `primary_identifier.value`.
For example, the value `gitleaks_rule_id_gitlab_personal_access_token` matches the following finding identifier:
+{{< /alert >}}
+
```json
{"type": "gitleaks_rule_id", "name": "Gitleaks rule ID GitLab Personal Access Token", "value": "GitLab Personal Access Token"}
```
diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md
index 123805ee72ca1b6ea33c5737d4e4e096990bab08..3d593ce0604b2ffb46f0513e7316b82bdb519252 100644
--- a/doc/development/secure_coding_guidelines.md
+++ b/doc/development/secure_coding_guidelines.md
@@ -1890,9 +1890,12 @@ In our Rails Controllers you must use `ActionController::StrongParameters`. This
Using `params[:key]` can lead to vulnerabilities when one part of the codebase expects a type like `String`, but gets passed (and handles unsafely and without error) an `Array`.
-NOTE:
+{{< alert type="note" >}}
+
This only applies to Rails Controllers. Our API and GraphQL endpoints enforce strong typing, and Go is statically typed.
+{{< /alert >}}
+
### Example
```ruby
diff --git a/doc/development/shell_scripting_guide/_index.md b/doc/development/shell_scripting_guide/_index.md
index b6cedab108e3bc7d208d3e774f2b3bc368394475..cfb6b746d55071d967ea2997bf5ccfa4f903c35b 100644
--- a/doc/development/shell_scripting_guide/_index.md
+++ b/doc/development/shell_scripting_guide/_index.md
@@ -20,9 +20,12 @@ deviations from this guide, they should be described in the
## Avoid using shell scripts
-WARNING:
+{{< alert type="warning" >}}
+
This is a must-read section.
+{{< /alert >}}
+
Having said all of the above, we recommend staying away from shell scripts
as much as possible. A language like Ruby or Python (if required for
consistency with codebases that we leverage) is almost always a better choice.
@@ -71,11 +74,14 @@ shell check:
- shellcheck scripts/**/*.sh # path to your shell scripts
```
-NOTE:
+{{< alert type="note" >}}
+
By default, ShellCheck uses the [shell detection](https://github.com/koalaman/shellcheck/wiki/SC2148#rationale)
to determine the shell dialect in use. If the shell file is out of your control and ShellCheck cannot
detect the dialect, use `-s` flag to specify it: `-s sh` or `-s bash`.
+{{< /alert >}}
+
### Formatting
It's recommended to use the [shfmt](https://github.com/mvdan/sh#shfmt) tool to maintain consistent formatting.
@@ -99,16 +105,22 @@ shfmt:
- shfmt -i 2 -ci -d scripts # path to your shell scripts
```
-NOTE:
+{{< alert type="note" >}}
+
By default, shfmt uses the [shell detection](https://github.com/mvdan/sh#shfmt) similar to one of ShellCheck
and ignore files starting with a period. To override this, use `-ln` flag to specify the shell dialect:
`-ln posix` or `-ln bash`.
+{{< /alert >}}
+
## Testing
-NOTE:
+{{< alert type="note" >}}
+
This is a work in progress.
+{{< /alert >}}
+
It is an [ongoing effort](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64016) to evaluate different tools for the
automated testing of shell scripts (like [BATS](https://github.com/bats-core/bats-core)).
diff --git a/doc/development/sidekiq/_index.md b/doc/development/sidekiq/_index.md
index c8ef0690cdaa4474d7de19707d82384ecc1cb3cf..6c236572034dca4f208a19c411c0a516aef05768 100644
--- a/doc/development/sidekiq/_index.md
+++ b/doc/development/sidekiq/_index.md
@@ -153,9 +153,12 @@ can schedule helps mitigate the risk of overwhelming the system, which could lea
This guidance applies both to .com and self-managed customers. A single worker scheduling thousands of jobs can easily disrupt the normal functioning of an SM instance.
-NOTE:
+{{< alert type="note" >}}
+
If Sidekiq only has 20 threads and the limit for a specific job is 200 then it will never be able to hit this 200 concurrency so it will not be limited.
+{{< /alert >}}
+
### Static Concurrency Limit
For a static limit, consider the following example:
@@ -176,9 +179,12 @@ Alternatively, you can set a fixed limit directly:
concurrency_limit -> { 250 }
```
-NOTE:
+{{< alert type="note" >}}
+
Keep in mind that using a static limit means any updates or changes require merging an MR and waiting for the next deployment to take effect.
+{{< /alert >}}
+
### Instance-Configurable Concurrency Limit
If you want to allow instance administrators to control the concurrency limit:
@@ -208,9 +214,12 @@ To determine an appropriate limit, you can use this PromQL query as a guide in [
)
```
-NOTE:
+{{< alert type="note" >}}
+
The [concurrency limit may be momentarily exceeded](https://gitlab.com/gitlab-org/gitlab/-/issues/490936#note_2172737349) and should not be relied on as a strict limit.
+{{< /alert >}}
+
## Deferring Sidekiq workers
Sidekiq workers are deferred by two ways,
diff --git a/doc/development/sidekiq/limited_capacity_worker.md b/doc/development/sidekiq/limited_capacity_worker.md
index 008d244dd8ee12714a292121f03d99a65616db75..c6c3ed341681c57e30dd36cb405545be2590822c 100644
--- a/doc/development/sidekiq/limited_capacity_worker.md
+++ b/doc/development/sidekiq/limited_capacity_worker.md
@@ -5,13 +5,16 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Sidekiq limited capacity worker
---
-NOTE:
+{{< alert type="note" >}}
+
The following documentation for limited capacity worker relates to a specific
type of worker that usually does not take arguments but instead gets work from
a custom queue (e.g. a PostgresSQL backlog of work). It cannot be used for
throttling normal Sidekiq workers. To restrict the concurrency of a normal
Sidekiq worker you can use a [concurrency limit](worker_attributes.md#concurrency-limit).
+{{< /alert >}}
+
It is possible to limit the number of concurrent running jobs for a worker class
by using the `LimitedCapacity::Worker` concern.
diff --git a/doc/development/sidekiq/worker_attributes.md b/doc/development/sidekiq/worker_attributes.md
index 3790da1d752fcd096d01a1776d0f1ced0f65c1c8..b2a23f02ecefb244d5c8501bcc88ee696bb9ee81 100644
--- a/doc/development/sidekiq/worker_attributes.md
+++ b/doc/development/sidekiq/worker_attributes.md
@@ -386,10 +386,13 @@ class PausedWorker
end
```
-WARNING:
+{{< alert type="warning" >}}
+
In case you want to remove the middleware for a worker, please set the strategy to `:deprecated` to disable it and wait until
a required stop before removing it completely. That ensures that all paused jobs are resumed correctly.
+{{< /alert >}}
+
## Concurrency limit
With the `concurrency_limit` property, you can limit the worker's concurrency. It will put the jobs that are over this limit in
@@ -410,10 +413,13 @@ Prometheus metrics are exposed to monitor workers using concurrency limit middle
- `sidekiq_concurrency_limit_max_concurrent_jobs`
- `sidekiq_concurrency_limit_current_concurrent_jobs_total`
-WARNING:
+{{< alert type="warning" >}}
+
If there is a sustained workload over the limit, the `LIST` is going to grow until the limit is disabled or
the workload drops under the limit.
+{{< /alert >}}
+
You should use a lambda to define the limit. If it returns `nil` or `0`, the limit won't be applied.
Negative numbers pause the execution.
diff --git a/doc/development/spam_protection_and_captcha/exploratory_testing.md b/doc/development/spam_protection_and_captcha/exploratory_testing.md
index 96f65ff8ab38d01ff783bc0bdaa1e3e0dc28e8e7..54edf85e7d5e6792b2a3167663b16c349672e144 100644
--- a/doc/development/spam_protection_and_captcha/exploratory_testing.md
+++ b/doc/development/spam_protection_and_captcha/exploratory_testing.md
@@ -83,13 +83,16 @@ no CAPTCHA popup displays. You are prevented from submitting the form at all.
### HTML page to render reCAPTCHA
-NOTE:
+{{< alert type="note" >}}
+
If you use **the Google official test reCAPTCHA credentials** listed in
[Set up Akismet and reCAPTCHA](#set-up-akismet-and-recaptcha), the
CAPTCHA response string does not matter. It can be any string. If you use a
real, valid key pair, you must solve the CAPTCHA to obtain a
valid CAPTCHA response to use. You can do this once only, and only before it expires.
+{{< /alert >}}
+
To directly test the GraphQL API via GraphQL Explorer (`http://gdk.test:3000/-/graphql-explorer`),
get a reCAPTCHA response string via this form: `public/recaptcha.html` (`http://gdk.test:3000/recaptcha.html`):
@@ -252,11 +255,14 @@ REST response:
GraphQL request:
-NOTE:
+{{< alert type="note" >}}
+
The GitLab GraphiQL implementation doesn't allow passing of headers, so we must write
this as a `curl` query. Here, `--data-binary` is used to properly handle escaped double quotes
in the JSON-embedded query.
+{{< /alert >}}
+
```shell
export CAPTCHA_RESPONSE="<CAPTCHA response obtained from HTML page to render CAPTCHA>"
export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
diff --git a/doc/development/spam_protection_and_captcha/graphql_api.md b/doc/development/spam_protection_and_captcha/graphql_api.md
index be3a70e662306939005d520aa396940ac49f50c0..50cee604997bce9baf40f7ea10a33088e0cc0f61 100644
--- a/doc/development/spam_protection_and_captcha/graphql_api.md
+++ b/doc/development/spam_protection_and_captcha/graphql_api.md
@@ -26,13 +26,16 @@ The main steps are:
For more details on these fields, refer to the section in the GraphQL API documentation on
[Resolve mutations detected as spam](../../api/graphql/_index.md#resolve-mutations-detected-as-spam).
- NOTE:
- If you use the standard ApolloLink or Axios interceptor CAPTCHA support described
+ {{< alert type="note" >}}
+
+If you use the standard ApolloLink or Axios interceptor CAPTCHA support described
above, you can ignore the field details, because they are handled
automatically. They become relevant if you attempt to use the GraphQL API directly to
process a failed check for potential spam, and resubmit the request with a solved
CAPTCHA response.
+ {{< /alert >}}
+
For example:
```ruby
diff --git a/doc/development/spam_protection_and_captcha/model_and_services.md b/doc/development/spam_protection_and_captcha/model_and_services.md
index aa264bb089107c5390c3a0ff94754d5b8c524f97..d80a668dd662c34282202ca71a46bf6b2b1ab569 100644
--- a/doc/development/spam_protection_and_captcha/model_and_services.md
+++ b/doc/development/spam_protection_and_captcha/model_and_services.md
@@ -75,10 +75,13 @@ to a controller. This controller allows administrators to manage spam for the as
end
```
-NOTE:
+{{< alert type="note" >}}
+
There may be other changes needed to controllers, depending on how the feature is
implemented. See [Web UI](web_ui.md) for more details.
+{{< /alert >}}
+
## Add a call to `check_for_spam` to the execute method of services
This approach applies to any service which can persist spammable attributes:
diff --git a/doc/development/spam_protection_and_captcha/rest_api.md b/doc/development/spam_protection_and_captcha/rest_api.md
index 312df8e676ceec9c04f88c2e26f1b1894a7efdad..47b0c6cac7d831572317d0a6623174d889c75489 100644
--- a/doc/development/spam_protection_and_captcha/rest_api.md
+++ b/doc/development/spam_protection_and_captcha/rest_api.md
@@ -33,13 +33,16 @@ The main steps are:
For more details on these fields, refer to the section in the REST API documentation on
[Resolve requests detected as spam](../../api/rest/troubleshooting.md#requests-detected-as-spam).
- NOTE:
- If you use the standard ApolloLink or Axios interceptor CAPTCHA support described
+ {{< alert type="note" >}}
+
+If you use the standard ApolloLink or Axios interceptor CAPTCHA support described
above, you can ignore the field details, because they are handled
automatically. They become relevant if you attempt to use the GraphQL API directly to
process a failed check for potential spam, and resubmit the request with a solved
CAPTCHA response.
+ {{< /alert >}}
+
Here is an example for the `post` and `put` actions on the `snippets` resource:
```ruby
diff --git a/doc/development/sql.md b/doc/development/sql.md
index 44fcad18abea08de6d69e3fa7c511c400779fcd0..65876eddb3a59457301cb2bbee96b39bbe627396 100644
--- a/doc/development/sql.md
+++ b/doc/development/sql.md
@@ -594,9 +594,12 @@ Limit (cost=817.27..818.12 rows=1 width=4)
Index Cond: (id = group_ids.id)
```
-NOTE:
+{{< alert type="note" >}}
+
Due to their complexity, using CTEs should be the last resort. Use CTEs only when simpler query changes don't produce a favorable execution plan.
+{{< /alert >}}
+
## `.find_or_create_by` is not atomic
The inherent pattern with methods like `.find_or_create_by` and
@@ -862,5 +865,8 @@ PersonalAccessToken
.update_all(revoked: true)
```
-NOTE:
+{{< alert type="note" >}}
+
Avoid updating large volumes of unbounded data. If there are no [application limits](application_limits.md) on the data, or you are unsure about the data volume, you should [update the data in batches](database/iterating_tables_in_batches.md).
+
+{{< /alert >}}
diff --git a/doc/development/stage_group_observability/gitlab_instrumentation_for_opentelemetry.md b/doc/development/stage_group_observability/gitlab_instrumentation_for_opentelemetry.md
index a54a1957ea2fb884d838b45f95a1e7683939f235..e69d821b79399f3d8176e0b88a8bc844af579a77 100644
--- a/doc/development/stage_group_observability/gitlab_instrumentation_for_opentelemetry.md
+++ b/doc/development/stage_group_observability/gitlab_instrumentation_for_opentelemetry.md
@@ -7,11 +7,14 @@ title: GitLab instrumentation for OpenTelemetry
## Enable OpenTelemetry tracing, metrics, and logs in GDK development
-NOTE:
+{{< alert type="note" >}}
+
Currently the default GDK environment is not set up by default to properly
collect and display OpenTelemetry data. Therefore, you should point the
`OTEL_EXPORTER_*_ENDPOINT` ENV vars to a GitLab project:
+{{< /alert >}}
+
1. Which has an Ultimate license, and where you have
1. In which you have at least the Maintainer role
1. In which you have access to enable top-level group feature flags (or is under the `gitlab-org` or `gitlab-com` top-level groups which already have the flags enabled)
diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md
index 1a56c9d862eb771bb3773798b5118df4f626645d..7e994e877cc4697fa7aaf84e0c26970ab3050f46 100644
--- a/doc/development/testing_guide/best_practices.md
+++ b/doc/development/testing_guide/best_practices.md
@@ -1,8 +1,8 @@
---
stage: none
group: unassigned
-info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines"
-description: "GitLab development guidelines - testing best practices."
+info: 'See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines'
+description: GitLab development guidelines - testing best practices.
title: Testing best practices
---
@@ -108,7 +108,11 @@ SILENCE_DEPRECATIONS=1 bin/rspec spec/models/project_spec.rb
### Test order
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93137) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93137) in GitLab 15.4.
+
+{{< /history >}}
All new spec files are run in [random order](https://gitlab.com/gitlab-org/gitlab/-/issues/337399)
to surface flaky tests that are dependent on test order.
@@ -383,14 +387,20 @@ Instead, you can use `stub_method` to stub the method:
end
```
-NOTE:
+{{< alert type="note" >}}
+
`stub_method` does not work when used in conjunction with `let_it_be_with_refind`. This is because `stub_method` will stub a method on an instance and `let_it_be_with_refind` will create a new instance of the object for each run.
+{{< /alert >}}
+
`stub_method` does not support method existence and method arity checks.
-WARNING:
+{{< alert type="warning" >}}
+
`stub_method` is supposed to be used in factories only. It's strongly discouraged to be used elsewhere. Consider using [RSpec mocks](https://rspec.info/features/3-12/rspec-mocks/) if available.
+{{< /alert >}}
+
#### Stubbing member access level
To stub [member access level](../../user/permissions.md#roles) for factory stubs like `Project` or `Group` use
@@ -408,10 +418,13 @@ it 'allows admin_project ability' do
end
```
-NOTE:
+{{< alert type="note" >}}
+
Refrain from using this stub helper if the test code relies on persisting
`project_authorizations` or `Member` records. Use `Project#add_member` or `Group#add_member` instead.
+{{< /alert >}}
+
#### Additional profiling metrics
We can use the `rspec_profiling` gem to diagnose, for instance, the number of SQL queries we're making when running a test.
@@ -568,10 +581,13 @@ Use the coverage reports to ensure your tests cover 100% of your code.
### System / Feature tests
-NOTE:
+{{< alert type="note" >}}
+
Before writing a new system test,
[consider this guide around their use](testing_levels.md#white-box-tests-at-the-system-level-formerly-known-as-system--feature-tests)
+{{< /alert >}}
+
- Feature specs should be named `ROLE_ACTION_spec.rb`, such as
`user_changes_password_spec.rb`.
- Use scenario titles that describe the success and failure paths.
@@ -873,11 +889,14 @@ you can follow.
Use `rubocop_spec_helper` for RuboCop related specs.
-WARNING:
+{{< alert type="warning" >}}
+
To verify that code and its specs are well-isolated from Rails, run the spec
individually via `bin/rspec`. Don't use `bin/spring rspec` as it loads
`spec_helper` automatically.
+{{< /alert >}}
+
#### Maintaining fast_spec_helper specs
There is a utility script `scripts/run-fast-specs.sh` which can be used to run
@@ -912,10 +931,13 @@ so we need to set some guidelines for their use going forward:
### Common test setup
-NOTE:
+{{< alert type="note" >}}
+
`let_it_be` and `before_all` do not work with DatabaseCleaner's deletion strategy. This includes migration specs, Rake task specs, and specs that have the `:delete` RSpec metadata tag.
For more information, see [issue 420379](https://gitlab.com/gitlab-org/gitlab/-/issues/420379).
+{{< /alert >}}
+
In some cases, there is no need to recreate the same object for tests
again for each example. For example, a project and a guest of that project
are needed to test issues on the same project, so one project and user are enough for the entire file.
@@ -1342,11 +1364,14 @@ Most tests for Elasticsearch logic relate to:
There are some exceptions, such as checking for structural changes rather than individual records in an index.
-NOTE:
+{{< alert type="note" >}}
+
Elasticsearch indexing uses [`Gitlab::Redis::SharedState`](../redis.md#gitlabrediscachesharedstatequeues).
Therefore, the Elasticsearch traits dynamically use the `:clean_gitlab_redis_shared_state` trait.
You do not need to add `:clean_gitlab_redis_shared_state` manually.
+{{< /alert >}}
+
Specs using Elasticsearch require that you:
- Create data in PostgreSQL and then index it into Elasticsearch.
@@ -1378,11 +1403,14 @@ This section describes how to test with events that have yet to convert to
##### Backend
-WARNING:
+{{< alert type="warning" >}}
+
Snowplow performs **runtime type checks** by using the [contracts gem](https://rubygems.org/gems/contracts).
Because Snowplow is **by default disabled in tests and development**, it can be hard to
**catch exceptions** when mocking `Gitlab::Tracking`.
+{{< /alert >}}
+
To catch runtime errors due to type checks you can use `expect_snowplow_event`, which checks for
calls to `Gitlab::Tracking#event`.
@@ -1533,11 +1561,14 @@ That indicates that you need to include the line `using RSpec::Parameterized::Ta
<!-- vale gitlab_base.Spelling = NO -->
-WARNING:
+{{< alert type="warning" >}}
+
Only use simple values as input in the `where` block. Using procs, stateful
objects, FactoryBot-created objects, and similar items can lead to
[unexpected results](https://github.com/tomykaira/rspec-parameterized/issues/8).
+{{< /alert >}}
+
<!-- vale gitlab_base.Spelling = YES -->
### Prometheus tests
diff --git a/doc/development/testing_guide/end_to_end/_index.md b/doc/development/testing_guide/end_to_end/_index.md
index 5abde2e5a7cb0f799efd2978077dc3d67c88697b..a20aeb163bd466cab3ef6e81472aca49519f640e 100644
--- a/doc/development/testing_guide/end_to_end/_index.md
+++ b/doc/development/testing_guide/end_to_end/_index.md
@@ -73,7 +73,8 @@ subgraph " `gitlab-org/gitlab-qa-mirror` pipeline"
1. Container for the Docker image stored in the [`gitlab-org/build/omnibus-gitlab-mirror`](https://gitlab.com/gitlab-org/build/omnibus-gitlab-mirror) registry is spun-up.
1. End-to-end tests are run with the `gitlab-qa` executable, which spin up a container for the end-to-end image from the [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) registry.
-NOTE:
+{{< alert type="note" >}}
+
You may have noticed that we use `gitlab-org/build/omnibus-gitlab-mirror` instead of
`gitlab-org/omnibus-gitlab`. This is due to technical limitations in the GitLab permission model: the ability to run a pipeline
against a protected branch is controlled by the ability to push/merge to this branch.
@@ -85,6 +86,8 @@ This problem was discovered in <https://gitlab.com/gitlab-org/gitlab-qa/-/issues
work-around was suggested in <https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4717>.
A feature proposal to segregate access control regarding running pipelines from ability to push/merge was also created at <https://gitlab.com/gitlab-org/gitlab/-/issues/24585>.
+{{< /alert >}}
+
For more technical details on CI/CD setup and documentation on adding new test jobs to `e2e:test-on-omnibus` pipeline, see [`e2e:test-on-omnibus` setup documentation](test_pipelines.md).
#### Using the `test-on-gdk` job
@@ -172,9 +175,12 @@ Examples could include:
Skip running end-to-end tests by applying the `pipeline:skip-e2e` label to the merge request.
-WARNING:
+{{< alert type="warning" >}}
+
There is a risk in skipping end-to-end tests. Use caution and discretion when applying this label. The end-to-end test suite is the last line of defense before changes are merged into the default branch. Skipping these tests increases the risk of introducing regressions into the codebase.
+{{< /alert >}}
+
## Test pipeline tools and configuration
### Test parallelization
diff --git a/doc/development/testing_guide/end_to_end/beginners_guide/_index.md b/doc/development/testing_guide/end_to_end/beginners_guide/_index.md
index 38a9501e387454699618e64af2d040e0ff88f883..c178f322f22c02ec946ee2293547384331ce3736 100644
--- a/doc/development/testing_guide/end_to_end/beginners_guide/_index.md
+++ b/doc/development/testing_guide/end_to_end/beginners_guide/_index.md
@@ -33,9 +33,12 @@ For information about the distribution of tests per level in GitLab, see [Testin
- Review how often the feature changes. Stable features that don't change very often might not be worth covering with end-to-end tests if they are already covered in lower level tests.
- Finally, discuss the proposed test with the developers involved in implementing the feature and the lower-level tests.
-WARNING:
+{{< alert type="warning" >}}
+
Check the [GitLab](https://gitlab-org.gitlab.io/gitlab/coverage-ruby/#_AllFiles) coverage project for previously written tests for this feature. To analyze code coverage, you must understand which application files implement specific features.
+{{< /alert >}}
+
In this tutorial we're writing a login end-to-end test, even though it has been sufficiently covered by lower-level testing, because it's the first step for most end-to-end flows, and is easiest to understand.
## Identify the DevOps stage
@@ -54,9 +57,12 @@ In the first part of this tutorial we are testing login, which is owned by the M
See the [`RSpec.describe` outer block](#the-outer-rspecdescribe-block)
-WARNING:
+{{< alert type="warning" >}}
+
The outer `context` [was deprecated](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/issues/550) in `13.2` in adherence to RSpec 4.0 specifications. Use `RSpec.describe` instead.
+{{< /alert >}}
+
### The outer `RSpec.describe` block
Specs have an outer `RSpec.describe` indicating the DevOps stage.
@@ -149,9 +155,12 @@ module QA
end
```
-NOTE:
+{{< alert type="note" >}}
+
For more information on Flows, see [Flows](flows.md)
+{{< /alert >}}
+
After [running the spec](#run-the-spec), our test should login and end; then we should answer the question "What do we test?"
```ruby
@@ -331,9 +340,12 @@ Before submitting the test for code review, there are a few housecleaning tasks
1. Ensure that the relevant [RSpec metadata](../best_practices/rspec_metadata_tests.md) are added to the spec.
1. Ensure the page object elements are named according to the [recommended naming convention](../style_guide.md#element-naming-convention).
-NOTE:
+{{< alert type="note" >}}
+
For more information, see [End-to-end testing best practices](../best_practices/_index.md) and [End-to-end testing style guide](../style_guide.md).
+{{< /alert >}}
+
## End-to-end test merge request template
When submitting a new end-to-end test, use the ["New End to End Test"](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/New%20End%20To%20End%20Test.md) merge request description template for additional steps that are required prior a successful merge.
diff --git a/doc/development/testing_guide/end_to_end/beginners_guide/page_objects.md b/doc/development/testing_guide/end_to_end/beginners_guide/page_objects.md
index d7f90b647a67929b21bda90c404a7e9c5d79e3ce..42b48ae6634b78249ca13f78c13a04984d3dce27 100644
--- a/doc/development/testing_guide/end_to_end/beginners_guide/page_objects.md
+++ b/doc/development/testing_guide/end_to_end/beginners_guide/page_objects.md
@@ -163,7 +163,11 @@ Things to note:
### `data-testid` vs `data-qa-selector`
-> - Introduced in GitLab 16.1
+{{< history >}}
+
+- Introduced in GitLab 16.1
+
+{{< /history >}}
Any existing `data-qa-selector` class should be considered deprecated
and we should use the `data-testid` method of definition.
diff --git a/doc/development/testing_guide/end_to_end/best_practices/_index.md b/doc/development/testing_guide/end_to_end/best_practices/_index.md
index 5f0e7d04e4336386de9a0a4f98c436cd15eb9536..f5af26aef76482c5074372eb6ab4f901b5b5d7a0 100644
--- a/doc/development/testing_guide/end_to_end/best_practices/_index.md
+++ b/doc/development/testing_guide/end_to_end/best_practices/_index.md
@@ -359,9 +359,12 @@ When you add a new test that requires administrator access, apply the RSpec meta
When running tests locally or configuring a pipeline, the environment variable `QA_CAN_TEST_ADMIN_FEATURES` can be set to `false` to skip tests that have the `:requires_admin` tag.
-NOTE:
+{{< alert type="note" >}}
+
If the _only_ action in the test that requires administrator access is to toggle a feature flag, use the `feature_flag` tag instead. More details can be found in [testing with feature flags](feature_flags.md).
+{{< /alert >}}
+
## Prefer `Commit` resource over `ProjectPush`
In line with [using the API](#prefer-api-over-ui), use a `Commit` resource whenever possible.
@@ -476,9 +479,12 @@ end
We are creating custom negatable matchers in `qa/spec/support/matchers`.
-NOTE:
+{{< alert type="note" >}}
+
We need to create custom negatable matchers only for the predicate methods we've added to the test framework, and only if we're using `not_to`. If we use `to have_no_*` a negatable matcher is not necessary but it increases code readability.
+{{< /alert >}}
+
### Why we need negatable matchers
Consider the following code, but assume that we _don't_ have a custom negatable matcher for `have_job`.
diff --git a/doc/development/testing_guide/end_to_end/best_practices/execution_context_selection.md b/doc/development/testing_guide/end_to_end/best_practices/execution_context_selection.md
index f2cfcf58c04ad4f5855e37717f732fcf99294e4a..6dd05d5f32e23fdb21c72cd7453a812a7f69ce16 100644
--- a/doc/development/testing_guide/end_to_end/best_practices/execution_context_selection.md
+++ b/doc/development/testing_guide/end_to_end/best_practices/execution_context_selection.md
@@ -18,11 +18,14 @@ Some tests are designed to be run against specific environments, or in specific
| `pipeline` | Match a pipeline | `Array` or `Static` |
| `job` | Match a job | `Array` or `Static` |
-WARNING:
+{{< alert type="warning" >}}
+
You cannot specify `:production` and `{ <switch>: 'value' }` simultaneously.
These options are mutually exclusive. If you want to specify production, you
can control the `tld` and `domain` independently.
+{{< /alert >}}
+
## Examples
### Only
diff --git a/doc/development/testing_guide/end_to_end/running_tests/_index.md b/doc/development/testing_guide/end_to_end/running_tests/_index.md
index 4745756877f43a2c9df2c65f14af26ea72876367..c2fce134993877bbc71273e05dc623ba4c8ed989 100644
--- a/doc/development/testing_guide/end_to_end/running_tests/_index.md
+++ b/doc/development/testing_guide/end_to_end/running_tests/_index.md
@@ -17,13 +17,15 @@ bundle install
bundle exec rspec <path/to/spec.rb>
```
-NOTE:
+{{< alert type="note" >}}
- If you want to run tests requiring SSH against GDK, you will need to [modify your GDK setup](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/run_qa_against_gdk.md).
- You may be able to use the password pre-set for `root` in your GDK installation [See GDK help](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/14bd8b6eb875d72eb1b482e0ec00cbf8fc3ebf99/HELP#L62). If you have changed your `root` password from the default, export the password as `GITLAB_ADMIN_PASSWORD`.
- By default the tests will run in a headless browser. If you'd like to watch the test execution, you can export `WEBDRIVER_HEADLESS=false`.
- Tests that are tagged `:orchestrated` require special setup (e.g., custom GitLab configuration, or additional services such as LDAP). All [orchestrated tests can be run via `gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md). There are also [setup instructions](running_tests_that_require_special_setup.md) for running some of those tests against GDK or another local GitLab instance.
+{{< /alert >}}
+
### Remote development
For [VSCode](https://code.visualstudio.com/) user, [.devcontainer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/.devcontainer/devcontainer.json) defines configuration to develop E2E tests inside a Docker container which by default is attached to the same network as environments started by [`gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa) gem. For more information on how to use `dev containers`, see [tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial).
@@ -66,8 +68,11 @@ See the section above for situations that might require adjustment to the comman
gitlab/gitlab-ee:nightly
```
- NOTE:
- If you are on a Mac with [Apple Silicon](https://support.apple.com/en-us/HT211814), you will also need to add: `--platform=linux/amd64`
+ {{< alert type="note" >}}
+
+If you are on a Mac with [Apple Silicon](https://support.apple.com/en-us/HT211814), you will also need to add: `--platform=linux/amd64`
+
+ {{< /alert >}}
1. Once GitLab is up and accessible on `http://127.0.0.1`, in another shell tab, navigate to the `qa` directory of the checkout of the GitLab repository on your computer and run the following commands.
@@ -93,8 +98,11 @@ See the section above for situations that might require adjustment to the comman
- [Ruby](https://rubyinstaller.org/downloads/). Refer to the [`.ruby-version` file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.ruby-version)
for the exact version of Ruby to install.
- NOTE:
- Be aware that [Docker Desktop must be set to use Linux containers](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux#run-your-first-linux-container).
+ {{< alert type="note" >}}
+
+Be aware that [Docker Desktop must be set to use Linux containers](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux#run-your-first-linux-container).
+
+ {{< /alert >}}
1. Use the following command to start an instance that you can visit at `http://127.0.0.1`. You might need to grant admin rights if asked:
@@ -179,9 +187,12 @@ bundle exec bin/qa Test::Instance::All http://localhost:3000 --disable-feature g
This will instruct the QA framework to disable the `gitaly_enforce_requests_limits` feature flag ([via the API](../../../../api/features.md)) if not already disabled, run all the tests in the `Test::Instance::All` scenario, and then enable the feature flag again if it was enabled earlier.
-NOTE:
+{{< alert type="note" >}}
+
You can also [toggle feature flags in the tests themselves](../best_practices/feature_flags.md).
+{{< /alert >}}
+
Note also that the `--` separator isn't used because `--enable-feature` and `--disable-feature` are QA framework options, not `rspec` options.
## Test configuration
diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md
index 20473d27cf77d0a117d7cc102597913dee737976..e3466e84ef7764759b343e4d7eee686045c60057 100644
--- a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md
+++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'running_tests/running_tests_that_require_special_setup.md'
-remove_date: '2025-01-18'
+redirect_to: running_tests/running_tests_that_require_special_setup.md
+remove_date: "2025-01-18"
---
<!-- markdownlint-disable -->
diff --git a/doc/development/testing_guide/end_to_end/style_guide.md b/doc/development/testing_guide/end_to_end/style_guide.md
index 8a0839edb9df551332723a51bb1c23816b439a17..dc3dea6324af23c6de30d8b0475c0527146b98c3 100644
--- a/doc/development/testing_guide/end_to_end/style_guide.md
+++ b/doc/development/testing_guide/end_to_end/style_guide.md
@@ -69,9 +69,12 @@ We follow a simple formula roughly based on Hungarian notation.
- `-tab`
- `-menu_item`
-NOTE:
+{{< alert type="note" >}}
+
If none of the listed types are suitable, open a merge request to add an appropriate type to the list.
+{{< /alert >}}
+
### Examples
**Good**
diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md
index 42abf730c40dfedf64a54403e523e97bcbd80dd6..739f8392ec60acd7402a11e55a2904e4e834c5b5 100644
--- a/doc/development/testing_guide/frontend_testing.md
+++ b/doc/development/testing_guide/frontend_testing.md
@@ -405,10 +405,13 @@ it('does something', () => {
### Mocking the current location in Jest
-NOTE:
+{{< alert type="note" >}}
+
The value of `window.location.href` is reset before every test to avoid earlier
tests affecting later ones.
+{{< /alert >}}
+
If your tests require `window.location.href` to take a particular value, use
the `setWindowLocation` helper:
@@ -1113,9 +1116,12 @@ it.each([
);
```
-NOTE:
+{{< alert type="note" >}}
+
Only use template literal block if pretty print is not needed for spec output. For example, empty strings, nested objects etc.
+{{< /alert >}}
+
For example, when testing the difference between an empty search string and a non-empty search string, the use of the array block syntax with the pretty print option would be preferred. That way the differences between an empty string (`''`) and a non-empty string (`'search string'`) would be visible in the spec output. Whereas with a template literal block, the empty string would be shown as a space, which could lead to a confusing developer experience.
```javascript
@@ -1223,11 +1229,14 @@ import Subject from '~/feature/the_subject.vue';
import _Thing from '~/feature/path/to/thing.vue';
```
-NOTE:
+{{< alert type="note" >}}
+
Do not disregard test timeouts. This could be a sign that there's
actually a production problem. Use this opportunity to analyze the production webpack bundles and
chunks and confirm that there is not a production issue with the asynchronous imports.
+{{< /alert >}}
+
## Overview of Frontend Testing Levels
Main information on frontend testing levels can be found in the [Testing Levels page](testing_levels.md).
@@ -1890,10 +1899,13 @@ RSpec.describe 'Pipeline', :js do
end
```
-NOTE:
+{{< alert type="note" >}}
+
`expect_page_to_have_no_console_errors` will not work on `WEBDRIVER=firefox`. Logs are only captured when
using the Chrome driver.
+{{< /alert >}}
+
Sometimes, there are known console errors that we want to ignore. To ignore a set of messages, such that the test
**will not** fail if the message is observed, you can pass an `allow:` parameter to
`expect_page_to_have_no_console_errors`:
diff --git a/doc/development/testing_guide/unhealthy_tests.md b/doc/development/testing_guide/unhealthy_tests.md
index 98318edd1ec2e12560e3afd452a8da9483aa6e40..8c640a8b560c4bccbdeb978d1a8b4c14b75d44ac 100644
--- a/doc/development/testing_guide/unhealthy_tests.md
+++ b/doc/development/testing_guide/unhealthy_tests.md
@@ -1,8 +1,8 @@
---
stage: none
group: unassigned
-info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines"
-description: "GitLab development guidelines - Unhealthy tests."
+info: 'See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines'
+description: GitLab development guidelines - Unhealthy tests.
title: Unhealthy tests
---
diff --git a/doc/development/token_authenticatable.md b/doc/development/token_authenticatable.md
index e9893829d8158cf81f6185ac8302156f132892d1..6b89f12344b5404667605e37f61041e0e605ca12 100644
--- a/doc/development/token_authenticatable.md
+++ b/doc/development/token_authenticatable.md
@@ -2,7 +2,7 @@
stage: none
group: unassigned
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-title: 'Using the `TokenAuthenticatable` concern'
+title: Using the `TokenAuthenticatable` concern
---
The `TokenAuthenticatable` module is a concern that provides token-based authentication functionality for `ActiveRecord` models.
@@ -46,9 +46,12 @@ end
- `digest: true`: Stores the token's digest in the database.
The `token_field_digest` column needs to exist.
-NOTE:
+{{< alert type="note" >}}
+
By default, tokens are stored as-is (not encrypted).
+{{< /alert >}}
+
### Other options
- `unique: false`: Doesn't enforce token uniqueness and disables the generation of `find_by_token_field` (where `token_field` is the attribute name). Default is `true`.
diff --git a/doc/development/tracing.md b/doc/development/tracing.md
index a64d7aa5c2b8cac8e613ac7485c346149d8ac1b5..5304e8d677361f965e5369e3e3548920f89453b0 100644
--- a/doc/development/tracing.md
+++ b/doc/development/tracing.md
@@ -5,24 +5,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Distributed tracing
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is not under active development.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124966) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `observability_tracing`. Disabled by default. This feature is in [beta](../policy/development_stages_support.md#beta).
-> - Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158786) in GitLab 17.3 to the `observability_features` [feature flag](../administration/feature_flags.md), disabled by default. The previous feature flag `observability_tracing` was removed.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/100) for GitLab Self-Managed in GitLab 17.3.
-> - [Changed](https://gitlab.com/gitlab-com/marketing/digital-experience/buyer-experience/-/issues/4198) to internal beta in GitLab 17.7.
+{{< /alert >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124966) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `observability_tracing`. Disabled by default. This feature is in [beta](../policy/development_stages_support.md#beta).
+- Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158786) in GitLab 17.3 to the `observability_features` [feature flag](../administration/feature_flags.md), disabled by default. The previous feature flag `observability_tracing` was removed.
+- [Introduced](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/100) for GitLab Self-Managed in GitLab 17.3.
+- [Changed](https://gitlab.com/gitlab-com/marketing/digital-experience/buyer-experience/-/issues/4198) to internal beta in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
With distributed tracing, you can troubleshoot application performance issues by inspecting how a request moves through different services and systems, the timing of each operation, and any errors or logs as they occur. Tracing is particularly useful in the context of microservice applications, which group multiple independent services collaborating to fulfill user requests.
This feature is in [beta](../policy/development_stages_support.md). For more information, see the [group direction page](https://about.gitlab.com/direction/monitor/platform-insights/). To leave feedback about tracing bugs or functionality, comment in the [feedback issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/2590) or open a [new issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/new).
diff --git a/doc/development/uploads/working_with_uploads.md b/doc/development/uploads/working_with_uploads.md
index a9ca5f209a0ad6511b56df717eaec2646bff777c..9cb985984815df4ceb252bf044314b3a3d72aa08 100644
--- a/doc/development/uploads/working_with_uploads.md
+++ b/doc/development/uploads/working_with_uploads.md
@@ -328,38 +328,38 @@ The Scalability::Frameworks team is making object storage and uploads more easy
| File | CarrierWave usage | Categorized |
|---------------------------------------------------------|----------------------------------------------------------------------------------|---------------------|
-| `app/models/project.rb` | `include Avatarable` | **{check-circle}** Yes |
-| `app/models/projects/topic.rb` | `include Avatarable` | **{check-circle}** Yes |
-| `app/models/group.rb` | `include Avatarable` | **{check-circle}** Yes |
-| `app/models/user.rb` | `include Avatarable` | **{check-circle}** Yes |
-| `app/models/terraform/state_version.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
-| `app/models/ci/job_artifact.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
-| `app/models/ci/pipeline_artifact.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
-| `app/models/pages_deployment.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
-| `app/models/lfs_object.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
-| `app/models/dependency_proxy/blob.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
-| `app/models/dependency_proxy/manifest.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
-| `app/models/packages/composer/cache_file.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
-| `app/models/packages/package_file.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
-| `app/models/concerns/packages/debian/component_file.rb` | `include FileStoreMounter` | **{check-circle}** Yes |
+| `app/models/project.rb` | `include Avatarable` | {{< icon name="check-circle" >}} Yes |
+| `app/models/projects/topic.rb` | `include Avatarable` | {{< icon name="check-circle" >}} Yes |
+| `app/models/group.rb` | `include Avatarable` | {{< icon name="check-circle" >}} Yes |
+| `app/models/user.rb` | `include Avatarable` | {{< icon name="check-circle" >}} Yes |
+| `app/models/terraform/state_version.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
+| `app/models/ci/job_artifact.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
+| `app/models/ci/pipeline_artifact.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
+| `app/models/pages_deployment.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
+| `app/models/lfs_object.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
+| `app/models/dependency_proxy/blob.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
+| `app/models/dependency_proxy/manifest.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
+| `app/models/packages/composer/cache_file.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
+| `app/models/packages/package_file.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
+| `app/models/concerns/packages/debian/component_file.rb` | `include FileStoreMounter` | {{< icon name="check-circle" >}} Yes |
| `ee/app/models/issuable_metric_image.rb` | `include FileStoreMounter` | |
| `ee/app/models/vulnerabilities/remediation.rb` | `include FileStoreMounter` | |
| `ee/app/models/vulnerabilities/export.rb` | `include FileStoreMounter` | |
-| `app/models/packages/debian/project_distribution.rb` | `include Packages::Debian::Distribution` | **{check-circle}** Yes |
-| `app/models/packages/debian/group_distribution.rb` | `include Packages::Debian::Distribution` | **{check-circle}** Yes |
-| `app/models/packages/debian/project_component_file.rb` | `include Packages::Debian::ComponentFile` | **{check-circle}** Yes |
-| `app/models/packages/debian/group_component_file.rb` | `include Packages::Debian::ComponentFile` | **{check-circle}** Yes |
-| `app/models/merge_request_diff.rb` | `mount_uploader :external_diff, ExternalDiffUploader` | **{check-circle}** Yes |
-| `app/models/note.rb` | `mount_uploader :attachment, AttachmentUploader` | **{check-circle}** Yes |
-| `app/models/appearance.rb` | `mount_uploader :logo, AttachmentUploader` | **{check-circle}** Yes |
-| `app/models/appearance.rb` | `mount_uploader :header_logo, AttachmentUploader` | **{check-circle}** Yes |
-| `app/models/appearance.rb` | `mount_uploader :favicon, FaviconUploader` | **{check-circle}** Yes |
+| `app/models/packages/debian/project_distribution.rb` | `include Packages::Debian::Distribution` | {{< icon name="check-circle" >}} Yes |
+| `app/models/packages/debian/group_distribution.rb` | `include Packages::Debian::Distribution` | {{< icon name="check-circle" >}} Yes |
+| `app/models/packages/debian/project_component_file.rb` | `include Packages::Debian::ComponentFile` | {{< icon name="check-circle" >}} Yes |
+| `app/models/packages/debian/group_component_file.rb` | `include Packages::Debian::ComponentFile` | {{< icon name="check-circle" >}} Yes |
+| `app/models/merge_request_diff.rb` | `mount_uploader :external_diff, ExternalDiffUploader` | {{< icon name="check-circle" >}} Yes |
+| `app/models/note.rb` | `mount_uploader :attachment, AttachmentUploader` | {{< icon name="check-circle" >}} Yes |
+| `app/models/appearance.rb` | `mount_uploader :logo, AttachmentUploader` | {{< icon name="check-circle" >}} Yes |
+| `app/models/appearance.rb` | `mount_uploader :header_logo, AttachmentUploader` | {{< icon name="check-circle" >}} Yes |
+| `app/models/appearance.rb` | `mount_uploader :favicon, FaviconUploader` | {{< icon name="check-circle" >}} Yes |
| `app/models/project.rb` | `mount_uploader :bfg_object_map, AttachmentUploader` | |
-| `app/models/import_export_upload.rb` | `mount_uploader :import_file, ImportExportUploader` | **{check-circle}** Yes |
-| `app/models/import_export_upload.rb` | `mount_uploader :export_file, ImportExportUploader` | **{check-circle}** Yes |
+| `app/models/import_export_upload.rb` | `mount_uploader :import_file, ImportExportUploader` | {{< icon name="check-circle" >}} Yes |
+| `app/models/import_export_upload.rb` | `mount_uploader :export_file, ImportExportUploader` | {{< icon name="check-circle" >}} Yes |
| `app/models/ci/deleted_object.rb` | `mount_uploader :file, DeletedObjectUploader` | |
-| `app/models/design_management/action.rb` | `mount_uploader :image_v432x230, DesignManagement::DesignV432x230Uploader` | **{check-circle}** Yes |
-| `app/models/concerns/packages/debian/distribution.rb` | `mount_uploader :signed_file, Packages::Debian::DistributionReleaseFileUploader` | **{check-circle}** Yes |
-| `app/models/bulk_imports/export_upload.rb` | `mount_uploader :export_file, ExportUploader` | **{check-circle}** Yes |
+| `app/models/design_management/action.rb` | `mount_uploader :image_v432x230, DesignManagement::DesignV432x230Uploader` | {{< icon name="check-circle" >}} Yes |
+| `app/models/concerns/packages/debian/distribution.rb` | `mount_uploader :signed_file, Packages::Debian::DistributionReleaseFileUploader` | {{< icon name="check-circle" >}} Yes |
+| `app/models/bulk_imports/export_upload.rb` | `mount_uploader :export_file, ExportUploader` | {{< icon name="check-circle" >}} Yes |
| `ee/app/models/user_permission_export_upload.rb` | `mount_uploader :file, AttachmentUploader` | |
| `app/models/ci/secure_file.rb` | `include FileStoreMounter` | |
diff --git a/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md b/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md
index 5597b4c468e00c4bc2b07654c760ed4bdfd86e1a..5f2111c6184c27f31e05a7936559275df2b315e0 100644
--- a/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md
+++ b/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md
@@ -5,12 +5,7 @@ info: Any user with at least the Maintainer role can merge updates to this conte
title: Aggregated Value Stream Analytics
---
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the
-sole discretion of GitLab Inc.
+{{< alert type="disclaimer" />}}
This page provides a high-level overview of the aggregated backend for
Value Stream Analytics (VSA).
diff --git a/doc/development/vs_code_debugging.md b/doc/development/vs_code_debugging.md
index 68ef145817085d3f081abb84be10cf6b521335f2..1295e62235d973b51262403b1c55f8082dac0bb9 100644
--- a/doc/development/vs_code_debugging.md
+++ b/doc/development/vs_code_debugging.md
@@ -85,9 +85,12 @@ The examples below contain launch configurations for `rails-web` and `rails-back
}
```
-WARNING:
+{{< alert type="warning" >}}
+
The VS Code Ruby extension might have issues finding the correct Ruby installation and the appropriate `rdbg` command. In this case, add `"rdbgPath": "/home/user/.asdf/shims/` (in the case of asdf) to the launch configuration above.
+{{< /alert >}}
+
## Debugging
### Prerequisites
@@ -98,4 +101,4 @@ To start debugging, do one of the following:
- Press <kbd>F5</kbd>.
- Run the `Debug: Start Debugging` command.
-- Open the [Run and Debug view](https://code.visualstudio.com/docs/editor/debugging#_run-and-debug-view), select one of the launch profiles, then select **Play** (**{play}**).
+- Open the [Run and Debug view](https://code.visualstudio.com/docs/editor/debugging#_run-and-debug-view), select one of the launch profiles, then select **Play** ({{< icon name="play" >}}).
diff --git a/doc/development/webhooks.md b/doc/development/webhooks.md
index 403eb2966583c5e0e4af3e4379b9de16e99c4a83..3995e41b4dfff7eda71d9306c77a96bddd7426bc 100644
--- a/doc/development/webhooks.md
+++ b/doc/development/webhooks.md
@@ -2,7 +2,7 @@
stage: Foundations
group: Import and Integrate
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "GitLab's development guidelines for webhooks"
+description: GitLab's development guidelines for webhooks
title: Webhooks developer guide
---
diff --git a/doc/development/wikis.md b/doc/development/wikis.md
index afb22edd758a29e17a806e5064738bdcf2b98181..1c86c679291f7058aadbc39432f568725dbaf6e7 100644
--- a/doc/development/wikis.md
+++ b/doc/development/wikis.md
@@ -2,7 +2,7 @@
stage: Plan
group: Knowledge
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-description: "GitLab's development guidelines for Wikis"
+description: GitLab's development guidelines for Wikis
title: Wikis development guidelines
---
diff --git a/doc/development/windows.md b/doc/development/windows.md
index 57ea8566cec367fc786bac0776f1ee21c00f4a7a..1b84f1944227ffa909775da81744e34797480df8 100644
--- a/doc/development/windows.md
+++ b/doc/development/windows.md
@@ -1,6 +1,6 @@
---
-redirect_to: '_index.md'
-remove_date: '2025-01-31'
+redirect_to: _index.md
+remove_date: "2025-01-31"
---
<!-- markdownlint-disable -->
diff --git a/doc/development/work_items.md b/doc/development/work_items.md
index 5fbc99513dce165fa38724a8805b1f3f75d4409c..16ffe14149b7e3c85d3ef45417896aa2bed358c0 100644
--- a/doc/development/work_items.md
+++ b/doc/development/work_items.md
@@ -109,10 +109,13 @@ move the `issue_type` to a separate table: `work_item_types`. The migration proc
to `work_item_types` will involve creating the set of WITs for all root-level groups as described in
[this epic](https://gitlab.com/groups/gitlab-org/-/epics/6536).
-NOTE:
+{{< alert type="note" >}}
+
At first, defining a WIT will only be possible at the root-level group, which would then be inherited by subgroups.
We will investigate the possibility of defining new WITs at subgroup levels at a later iteration.
+{{< /alert >}}
+
## Introducing `work_item_types` table
For example, suppose there are three root-level groups with IDs: `11`, `12`, and `13`. Also,
diff --git a/doc/development/work_items_widgets.md b/doc/development/work_items_widgets.md
index 46b232da4825a5ece990d2d449fba2cffe867483..eae11aff246dc5909ab718265934c04ce2f30678 100644
--- a/doc/development/work_items_widgets.md
+++ b/doc/development/work_items_widgets.md
@@ -156,10 +156,13 @@ Now you can update tests for existing files and write tests for the new files:
1. `spec/frontend/work_items/graphql/resolvers_spec.js` or `ee/spec/frontend/work_items/graphql/resolvers_spec.js`.
1. `spec/features/work_items/work_item_detail_spec.rb` or `ee/spec/features/work_items/work_item_detail_spec.rb`.
-NOTE:
+{{< alert type="note" >}}
+
You may find some feature specs failing because of excessive SQL queries.
To resolve this, update the mocked `Gitlab::QueryLimiting::Transaction.threshold` in `spec/support/shared_examples/features/work_items/rolledup_dates_shared_examples.rb`.
+{{< /alert >}}
+
## Steps to implement a new work item widget on frontend in the create view
1. Make sure that you know the scope and have the designs ready for the new widget
diff --git a/doc/development/workhorse/configuration.md b/doc/development/workhorse/configuration.md
index 5c79581b88b8194b662df7510bead6ceed8873b9..0125c4de102906d168bb709b35330279ad72c4de 100644
--- a/doc/development/workhorse/configuration.md
+++ b/doc/development/workhorse/configuration.md
@@ -223,9 +223,9 @@ You can also set the `GITLAB_WORKHORSE_SENTRY_ENVIRONMENT` environment variable
use the Sentry environment feature to separate staging, production and
development.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```ruby
gitlab_workhorse['env'] = {
@@ -234,14 +234,18 @@ gitlab_workhorse['env'] = {
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```plaintext
export GITLAB_WORKHORSE_SENTRY_DSN='https://foobar'
export GITLAB_WORKHORSE_SENTRY_ENVIRONMENT='production'
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Distributed tracing
@@ -299,9 +303,12 @@ that can be trusted. For example:
trusted_cidrs_for_propagation = ["10.0.0.0/8", "127.0.0.1/32"]
```
-NOTE:
+{{< alert type="note" >}}
+
The `-propagateCorrelationID` flag must be used for the `trusted_cidrs_for_propagation` option to work.
+{{< /alert >}}
+
### Trusted proxies
If Workhorse is behind a reverse proxy such as NGINX, the
diff --git a/doc/devsecops.md b/doc/devsecops.md
index fac63b109b7ff5b77eb719602600ca0ca357d40e..c1db9a17de280890a53da61b78ef94ae58e65d12 100644
--- a/doc/devsecops.md
+++ b/doc/devsecops.md
@@ -2,7 +2,7 @@
stage: none
group: unassigned
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
-description: 'Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.'
+description: Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.
title: 'GitLab: The DevSecOps platform'
---
diff --git a/doc/downgrade_ee_to_ce/_index.md b/doc/downgrade_ee_to_ce/_index.md
index 86e5bc3e075ad77e91c2634469de7698a9783b20..a601a7888935a461dd66b64b062fdd10e7459e31 100644
--- a/doc/downgrade_ee_to_ce/_index.md
+++ b/doc/downgrade_ee_to_ce/_index.md
@@ -52,9 +52,9 @@ The `subclass` in the error message can be any of the following:
All integrations are created automatically for every project you have.
To avoid getting this error, you must remove all EE-only integration records from your database.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rails runner "Integration.where(type_new: ['Integrations::Github']).delete_all"
@@ -63,7 +63,9 @@ sudo gitlab-rails runner "Integration.where(type_new: ['Integrations::GoogleClou
sudo gitlab-rails runner "Integration.where(type_new: ['Integrations::GoogleCloudPlatform::WorkloadIdentityFederation']).delete_all"
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
bundle exec rails runner "Integration.where(type_new: ['Integrations::Github']).delete_all" production
@@ -72,7 +74,9 @@ bundle exec rails runner "Integration.where(type_new: ['Integrations::GoogleClou
bundle exec rails runner "Integration.where(type_new: ['Integrations::GoogleCloudPlatform::WorkloadIdentityFederation']).delete_all" production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Variables environment scopes
diff --git a/doc/drawers/advanced_search_syntax.md b/doc/drawers/advanced_search_syntax.md
index 287c61b687a9202b24daae9ba9270f8daf10bb3f..a95b1574ad8c5440539dde575b978807f489b4af 100644
--- a/doc/drawers/advanced_search_syntax.md
+++ b/doc/drawers/advanced_search_syntax.md
@@ -1,12 +1,10 @@
---
stage: Foundations
group: Global Search
-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"
-source: /doc/user/search/advanced_search.md
+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
+title: Syntax options
---
-# Syntax options
-
<!-- Remember to also update the tables in `doc/user/search/advanced_search.md` -->
| Syntax | Description | Example |
diff --git a/doc/drawers/exact_code_search_syntax.md b/doc/drawers/exact_code_search_syntax.md
index a5f645accee1e4a2fe6fec99f078fa1eb2f228c5..3566bb32b66c3c2671e898cfc84c1386f62d2299 100644
--- a/doc/drawers/exact_code_search_syntax.md
+++ b/doc/drawers/exact_code_search_syntax.md
@@ -1,12 +1,10 @@
---
stage: Foundations
group: Global Search
-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"
-source: /doc/user/search/exact_code_search.md
+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
+title: Syntax options
---
-# Syntax options
-
<!-- Remember to also update the table in `doc/user/search/exact_code_search.md` -->
| Query | Exact match mode | Regular expression mode |
diff --git a/doc/editor_extensions/_index.md b/doc/editor_extensions/_index.md
index c014656edbf91f477521b49b098cd6cffa910f90..8ba85dfa4161d6553f4a219dfb5d24daf4a36271 100644
--- a/doc/editor_extensions/_index.md
+++ b/doc/editor_extensions/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Extend the features of GitLab to Visual Studio Code, JetBrains IDEs, Visual Studio, and Neovim."
+description: Extend the features of GitLab to Visual Studio Code, JetBrains IDEs, Visual Studio, and Neovim.
title: Editor Extensions
---
diff --git a/doc/editor_extensions/eclipse/_index.md b/doc/editor_extensions/eclipse/_index.md
index daf35b3cd82f0f030fba91c11ffb3f5bf7e0c3d1..2af51439a2c0c67dbc2f9f54a33faf23bb62f2e3 100644
--- a/doc/editor_extensions/eclipse/_index.md
+++ b/doc/editor_extensions/eclipse/_index.md
@@ -2,21 +2,19 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in Eclipse."
+description: Connect and use GitLab Duo in Eclipse.
title: GitLab for Eclipse
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
-
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the
-sole discretion of GitLab Inc.
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
+
+{{< alert type="disclaimer" />}}
The GitLab for Eclipse plugin integrates with GitLab Duo.
This feature is an [experiment](../../policy/development_stages_support.md).
diff --git a/doc/editor_extensions/eclipse/setup.md b/doc/editor_extensions/eclipse/setup.md
index 60d36a5300e3e4ab2fb19cbd67bc1abaa06e3947..ed08722a7a3ed9f9b9526b820d32d1c0c973a9f4 100644
--- a/doc/editor_extensions/eclipse/setup.md
+++ b/doc/editor_extensions/eclipse/setup.md
@@ -2,21 +2,19 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in Eclipse."
+description: Connect and use GitLab Duo in Eclipse.
title: Install and set up GitLab for Eclipse
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
-
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the
-sole discretion of GitLab Inc.
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
+
+{{< alert type="disclaimer" />}}
## Install the GitLab for Eclipse plugin
diff --git a/doc/editor_extensions/eclipse/troubleshooting.md b/doc/editor_extensions/eclipse/troubleshooting.md
index 259ac05270a96a549ae4681b7d40c21bdb6c3879..fa5b036ba5108af06c4fa094164933d2e77d88e6 100644
--- a/doc/editor_extensions/eclipse/troubleshooting.md
+++ b/doc/editor_extensions/eclipse/troubleshooting.md
@@ -2,21 +2,19 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in Eclipse."
+description: Connect and use GitLab Duo in Eclipse.
title: Eclipse troubleshooting
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
-
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the
-sole discretion of GitLab Inc.
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
+
+{{< alert type="disclaimer" />}}
If the steps on this page don't solve your problem, check the
[list of open issues](https://gitlab.com/gitlab-org/editor-extensions/gitlab-eclipse-plugin/-/issues/?sort=created_date&state=opened&first_page_size=100)
diff --git a/doc/editor_extensions/gitlab_cli/_index.md b/doc/editor_extensions/gitlab_cli/_index.md
index b4d15db682bd684fead5ec7bd1ae22c1f25bde8d..807aa705a94f2f83534fdaae579049000d503995 100644
--- a/doc/editor_extensions/gitlab_cli/_index.md
+++ b/doc/editor_extensions/gitlab_cli/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Use the GitLab CLI (glab) to perform common GitLab actions in your terminal."
+description: Use the GitLab CLI (glab) to perform common GitLab actions in your terminal.
title: GitLab CLI - `glab`
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
`glab` is an open source GitLab CLI tool. It brings GitLab to your terminal:
next to where you are already working with Git and your code, without
@@ -71,12 +74,19 @@ glab mr merge
## GitLab Duo for the CLI
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**LLM:** Anthropic [Claude 3 Haiku](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-haiku)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- LLM: Anthropic [Claude 3 Haiku](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-haiku)
+
+{{< /details >}}
+
+{{< history >}}
+
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+{{< /history >}}
The GitLab CLI includes features powered by [GitLab Duo](../../user/ai_features.md). These include:
diff --git a/doc/editor_extensions/jetbrains_ide/_index.md b/doc/editor_extensions/jetbrains_ide/_index.md
index 2647e861a03140e6280f39fec980c92916686fcd..422a45316e46ab57c16866912a61ee03d06cd4a3 100644
--- a/doc/editor_extensions/jetbrains_ide/_index.md
+++ b/doc/editor_extensions/jetbrains_ide/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in JetBrains IDEs."
+description: Connect and use GitLab Duo in JetBrains IDEs.
title: GitLab plugin for JetBrains IDEs
---
@@ -24,11 +24,18 @@ Some features in the plugin are in experiment or beta status. To use them, you m
## Integrate with 1Password CLI
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/issues/291) in GitLab Duo 2.1 for GitLab 16.11 and later.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/issues/291) in GitLab Duo 2.1 for GitLab 16.11 and later.
+
+{{< /history >}}
You can configure the plugin to use 1Password secret references for authentication, instead of hard-coding personal access tokens.
diff --git a/doc/editor_extensions/jetbrains_ide/jetbrains_troubleshooting.md b/doc/editor_extensions/jetbrains_ide/jetbrains_troubleshooting.md
index dcb9d6a75f388e2ddb4564b222d76bf406877dcc..888f583fdcaf13172411a52de85d7657f0a1bcc8 100644
--- a/doc/editor_extensions/jetbrains_ide/jetbrains_troubleshooting.md
+++ b/doc/editor_extensions/jetbrains_ide/jetbrains_troubleshooting.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in JetBrains IDEs."
+description: Connect and use GitLab Duo in JetBrains IDEs.
title: JetBrains troubleshooting
---
diff --git a/doc/editor_extensions/jetbrains_ide/setup.md b/doc/editor_extensions/jetbrains_ide/setup.md
index 96f5610eaa11c541f17bbebe1276689fe3369063..2cc4da13a542a32e4b3f8644a8d57c75f6d96b56 100644
--- a/doc/editor_extensions/jetbrains_ide/setup.md
+++ b/doc/editor_extensions/jetbrains_ide/setup.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in JetBrains IDEs."
+description: Connect and use GitLab Duo in JetBrains IDEs.
title: Install and set up the GitLab plugin for JetBrains IDEs
---
diff --git a/doc/editor_extensions/language_server/_index.md b/doc/editor_extensions/language_server/_index.md
index 8388a5d3f1a1c1eae65625b624c176898842c481..4625db391a8f94fd4005596b84a96b3b6c16d2a9 100644
--- a/doc/editor_extensions/language_server/_index.md
+++ b/doc/editor_extensions/language_server/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Learn about the GitLab Language Server."
+description: Learn about the GitLab Language Server.
title: GitLab Language Server
---
@@ -20,22 +20,26 @@ NPM module to determine proxy settings from these environment variables:
To configure the Language Server to use a proxy:
-::Tabs
+{{< tabs >}}
-:::TabTitle Visual Studio Code
+{{< tab title="Visual Studio Code" >}}
1. In Visual Studio Code, open your [user or workspace settings](https://code.visualstudio.com/docs/getstarted/settings).
1. Configure [`http.proxy`](https://code.visualstudio.com/docs/setup/network#_legacy-proxy-server-support)
to point at your HTTP proxy.
1. Restart Visual Studio Code to ensure connections to GitLab use the latest proxy settings.
-:::TabTitle JetBrains IDEs
+{{< /tab >}}
+
+{{< tab title="JetBrains IDEs" >}}
1. In your JetBrains IDE, configure the [HTTP Proxy](https://www.jetbrains.com/help/idea/settings-http-proxy.html) settings.
1. Restart your IDE to ensure connections to GitLab use the latest proxy settings.
1. From the **Tools > GitLab Duo** menu, select **Verify setup**. Make sure the health check passes.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Troubleshooting
@@ -50,29 +54,39 @@ Fetching resource from https://gitlab.com/api/v4/personal_access_tokens/self fai
To enable proxy authentication in the Language Server, follow the steps for your IDE:
-::Tabs
+{{< tabs >}}
-:::TabTitle Visual Studio Code
+{{< tab title="Visual Studio Code" >}}
1. Open your user or workspace [settings](https://code.visualstudio.com/docs/getstarted/settings).
1. Configure [`http.proxy`](https://code.visualstudio.com/docs/setup/network#_legacy-proxy-server-support),
including username and password, to authenticate with your HTTP proxy.
1. Restart Visual Studio Code to ensure connections to GitLab use the latest proxy settings.
-NOTE:
+{{< alert type="note" >}}
+
The VS Code extension does not support the legacy
[`http.proxyAuthorization`](https://code.visualstudio.com/docs/setup/network#_legacy-proxy-server-support)
setting in VS Code for authenticating the language server with an HTTP proxy. Support is proposed in
[issue 1672](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues/1672).
-:::TabTitle JetBrains IDEs
+{{< /alert >}}
+
+{{< /tab >}}
+
+{{< tab title="JetBrains IDEs" >}}
1. Configure [HTTP Proxy](https://www.jetbrains.com/help/idea/settings-http-proxy.html) settings in your JetBrains IDE.
1. If using **Manual proxy configuration**, enter your credentials under **Proxy authentication** and select **Remember**.
1. Restart your JetBrains IDE to ensure connections to GitLab use the latest proxy settings.
1. From the **Tools > GitLab Duo** menu, select **Verify setup**. Make sure the health check passes.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
+
+{{< alert type="note" >}}
-NOTE:
Bearer authentication is proposed in [issue 548](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/issues/548).
+
+{{< /alert >}}
diff --git a/doc/editor_extensions/neovim/_index.md b/doc/editor_extensions/neovim/_index.md
index 92e7c001e0ea8c9d474c133aa4bfcbfa68b2e15d..3ffb609cc5ec4245aa6f40f8c2b396d4f4915a8c 100644
--- a/doc/editor_extensions/neovim/_index.md
+++ b/doc/editor_extensions/neovim/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in Neovim."
+description: Connect and use GitLab Duo in Neovim.
title: GitLab plugin for Neovim - `gitlab.vim`
---
diff --git a/doc/editor_extensions/neovim/neovim_troubleshooting.md b/doc/editor_extensions/neovim/neovim_troubleshooting.md
index ea9a810ff4ab9a17a4e4ffc56112b12a41c7ee3d..16f48b6621b43301c4e7822ef68cef8a7289cb48 100644
--- a/doc/editor_extensions/neovim/neovim_troubleshooting.md
+++ b/doc/editor_extensions/neovim/neovim_troubleshooting.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in Neovim."
+description: Connect and use GitLab Duo in Neovim.
title: Neovim troubleshooting
---
diff --git a/doc/editor_extensions/neovim/setup.md b/doc/editor_extensions/neovim/setup.md
index ec811128ad306e2c2fb0c15ad04e93a428f3c288..10f361b2ef80c61e0298fd41ec3ba9f005dd3a65 100644
--- a/doc/editor_extensions/neovim/setup.md
+++ b/doc/editor_extensions/neovim/setup.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in Neovim."
+description: Connect and use GitLab Duo in Neovim.
title: Install and set up the GitLab plugin for Neovim
---
@@ -15,9 +15,9 @@ Prerequisites:
To install the extension, follow the installation steps for your chosen plugin manager:
-::Tabs
+{{< tabs >}}
-:::TabTitle No plugin manager
+{{< tab title="No plugin manager" >}}
Run this command to include this project with
[`packadd`](https://neovim.io/doc/user/repeat.html#%3Apackadd) on startup:
@@ -26,7 +26,9 @@ Run this command to include this project with
git clone https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim.git ~/.local/share/nvim/site/pack/gitlab/start/gitlab.vim
```
-:::TabTitle `lazy.nvim`
+{{< /tab >}}
+
+{{< tab title="`lazy.nvim`" >}}
Add this plugin to your [lazy.nvim](https://github.com/folke/lazy.nvim) configuration:
@@ -52,7 +54,9 @@ Add this plugin to your [lazy.nvim](https://github.com/folke/lazy.nvim) configur
}
```
-:::TabTitle `packer.nvim`
+{{< /tab >}}
+
+{{< tab title="`packer.nvim`" >}}
Declare the plugin in your [packer.nvim](https://github.com/wbthomason/packer.nvim) configuration:
@@ -62,7 +66,9 @@ use {
}
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Authenticate with GitLab
diff --git a/doc/editor_extensions/visual_studio/_index.md b/doc/editor_extensions/visual_studio/_index.md
index 90e5c1c1c6dabc782d0a3697926b20be74818648..fc8b41d16bfdc571cfdb2a4731474f5d2d2b421c 100644
--- a/doc/editor_extensions/visual_studio/_index.md
+++ b/doc/editor_extensions/visual_studio/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in Visual Studio."
+description: Connect and use GitLab Duo in Visual Studio.
title: GitLab extension for Visual Studio
---
diff --git a/doc/editor_extensions/visual_studio/setup.md b/doc/editor_extensions/visual_studio/setup.md
index 7403650dbaa2971b1b927fa5ceeed0afe73c11e4..312fc0de04a29f415f466e103ea754337971d00c 100644
--- a/doc/editor_extensions/visual_studio/setup.md
+++ b/doc/editor_extensions/visual_studio/setup.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in Visual Studio."
+description: Connect and use GitLab Duo in Visual Studio.
title: Install and set up the GitLab extension for Visual Studio
---
diff --git a/doc/editor_extensions/visual_studio/visual_studio_troubleshooting.md b/doc/editor_extensions/visual_studio/visual_studio_troubleshooting.md
index c6208f1c418beaecf7027907404f14402e5a8959..c6270b2cc12292ad701a1577e231282aeca3e3c2 100644
--- a/doc/editor_extensions/visual_studio/visual_studio_troubleshooting.md
+++ b/doc/editor_extensions/visual_studio/visual_studio_troubleshooting.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Connect and use GitLab Duo in Neovim."
+description: Connect and use GitLab Duo in Neovim.
title: Visual Studio troubleshooting
---
diff --git a/doc/editor_extensions/visual_studio_code/_index.md b/doc/editor_extensions/visual_studio_code/_index.md
index 38b721a9e495e47d263c0b6d0a3420ebe8202b75..582ff50256d849fdeb8185149bc74e4fff8ed364 100644
--- a/doc/editor_extensions/visual_studio_code/_index.md
+++ b/doc/editor_extensions/visual_studio_code/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Use the GitLab Workflow extension for VS Code to handle common GitLab tasks directly in VS Code."
+description: Use the GitLab Workflow extension for VS Code to handle common GitLab tasks directly in VS Code.
title: GitLab Workflow extension for VS Code
---
@@ -48,7 +48,7 @@ You can assign different keyboard shortcuts for **Accept Inline Suggestion**, **
or **Accept Next Line Of Inline Suggestion**:
1. In VS Code, run the `Preferences: Open Keyboard Shortcuts` command.
-1. Find the shortcut you want to edit, and select **Change keybinding** (**{pencil}**).
+1. Find the shortcut you want to edit, and select **Change keybinding** ({{< icon name="pencil" >}}).
1. Assign your preferred shortcuts to **Accept Inline Suggestion**, **Accept Next Word Of Inline Suggestion**,
or **Accept Next Line Of Inline Suggestion**.
1. Press <kbd>Enter</kbd> to save your changes.
@@ -83,7 +83,7 @@ In these cases, the extension adds a **(multiple projects)** label to show you m
To select an account:
-1. On the vertical menu bar, select **GitLab Workflow** (**{tanuki}**) to display the extension sidebar.
+1. On the vertical menu bar, select **GitLab Workflow** ({{< icon name="tanuki" >}}) to display the extension sidebar.
1. Expand **Issues and Merge Requests**.
1. Select the line containing **(multiple projects)** to expand the list of accounts.
1. Select your desired project:
@@ -95,7 +95,7 @@ The **Issues and Merge requests** list updates with your selected project's info
To change your project selection:
-1. On the vertical menu bar, select **GitLab Workflow** (**{tanuki}**) to display the extension sidebar.
+1. On the vertical menu bar, select **GitLab Workflow** ({{< icon name="tanuki" >}}) to display the extension sidebar.
1. Expand **Issues and Merge Requests** to show the project list.
1. Right-click the project's name.
1. Select **Clear selected project**.
@@ -164,7 +164,7 @@ To insert an existing single-file or [multi-file](../../user/snippets.md#add-or-
To view issues and merge requests for a specific project:
-1. On the menu bar, select **GitLab Workflow** (**{tanuki}**) to display the extension sidebar.
+1. On the menu bar, select **GitLab Workflow** ({{< icon name="tanuki" >}}) to display the extension sidebar.
1. On the sidebar, expand **Issues and merge requests**.
1. Select your desired project to expand it.
1. Choose one of the following result types:
@@ -225,9 +225,12 @@ To open a file from your current GitLab project in the GitLab UI, with specific
## View security findings
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
@@ -239,7 +242,7 @@ Prerequisites:
To view security findings:
-1. On the vertical menu bar, select **GitLab Workflow** (**{tanuki}**) to display the extension sidebar.
+1. On the vertical menu bar, select **GitLab Workflow** ({{< icon name="tanuki" >}}) to display the extension sidebar.
1. On the sidebar, expand **Security scanning**.
1. Select either **New findings** or **Fixed findings**.
1. Select a desired severity level.
@@ -247,12 +250,19 @@ To view security findings:
## Perform SAST scanning
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues/1675) in VS Code extension version 5.31.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues/1675) in VS Code extension version 5.31.
+{{< /history >}}
Static application security testing (SAST) in VS Code detects vulnerabilities in the active file.
With early detection, you can remediate vulnerabilities before you merge your changes into the
diff --git a/doc/editor_extensions/visual_studio_code/cicd.md b/doc/editor_extensions/visual_studio_code/cicd.md
index c63eab76bd6a262828e20cc335b434d110ac0b22..2c11e8e2997f9b4865f0130b334bd9d9da9e4366 100644
--- a/doc/editor_extensions/visual_studio_code/cicd.md
+++ b/doc/editor_extensions/visual_studio_code/cicd.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Use the GitLab Workflow extension for VS Code to handle common GitLab tasks directly in VS Code."
+description: Use the GitLab Workflow extension for VS Code to handle common GitLab tasks directly in VS Code.
title: CI/CD pipelines in the VS Code extension
---
@@ -62,7 +62,7 @@ To show alerts for your current Git branch:
To view the output for a CI/CD job for your current branch:
-1. On the left vertical menu bar, select **GitLab Workflow** (**{tanuki}**) to display the extension sidebar.
+1. On the left vertical menu bar, select **GitLab Workflow** ({{< icon name="tanuki" >}}) to display the extension sidebar.
1. On the sidebar, expand **For current branch** to show its most recent pipeline.
1. Select your desired job to open it in a new VS Code tab:
diff --git a/doc/editor_extensions/visual_studio_code/custom_queries.md b/doc/editor_extensions/visual_studio_code/custom_queries.md
index c4261a2616d1448d8a36bb2eaa84360e7ce36fc3..d1153eb09d1c031622d63359b6eab6bedb0b7289 100644
--- a/doc/editor_extensions/visual_studio_code/custom_queries.md
+++ b/doc/editor_extensions/visual_studio_code/custom_queries.md
@@ -26,7 +26,7 @@ Prerequisites:
To see search results from your project:
-1. On the left vertical menu bar, select **GitLab Workflow** (**{tanuki}**) to display the extension sidebar.
+1. On the left vertical menu bar, select **GitLab Workflow** ({{< icon name="tanuki" >}}) to display the extension sidebar.
1. On the sidebar, expand **Issues and merge requests**.
1. Select a project to view its queries, then select the query you want to run.
1. Below the query title, select the search result you want to see.
@@ -74,37 +74,37 @@ Not all item types support all parameters. These parameters apply to all query t
| Parameter | Required | Default | Definition |
|--------------|----------|-------------------|------------|
-| `name` | **{check-circle}** Yes | not applicable | The label to show in the GitLab panel. |
-| `noItemText` | **{dotted-circle}** No | `No items found.` | The text to show if the query returns no items. |
-| `type` | **{dotted-circle}** No | `merge_requests` | Which item types to return. Possible values: `issues`, `merge_requests`, `epics`, `snippets`, `vulnerabilities`. Snippets [don't support](../../api/project_snippets.md) any other filters. Epics are available only on GitLab Premium and Ultimate.|
+| `name` | {{< icon name="check-circle" >}} Yes | not applicable | The label to show in the GitLab panel. |
+| `noItemText` | {{< icon name="dotted-circle" >}} No | `No items found.` | The text to show if the query returns no items. |
+| `type` | {{< icon name="dotted-circle" >}} No | `merge_requests` | Which item types to return. Possible values: `issues`, `merge_requests`, `epics`, `snippets`, `vulnerabilities`. Snippets [don't support](../../api/project_snippets.md) any other filters. Epics are available only on GitLab Premium and Ultimate.|
### Supported parameters for issue, epic, and merge request queries
| Parameter | Required | Default | Definition |
|--------------------|------------------------|--------------|------------|
-| `assignee` | **{dotted-circle}** No | not applicable | Return items assigned to the given username. `None` returns unassigned GitLab items. `Any` returns GitLab items with an assignee. Not available for epics and vulnerabilities. |
-| `author` | **{dotted-circle}** No | not applicable | Return items created by the given username. |
-| `confidential` | **{dotted-circle}** No | not applicable | Filter confidential or public issues. Available only for issues. |
-| `createdAfter` | **{dotted-circle}** No | not applicable | Return items created after the given date. |
-| `createdBefore` | **{dotted-circle}** No | not applicable | Return items created before the given date. |
-| `draft` | **{dotted-circle}** No | `no` | Filter merge requests against their draft status: `yes` returns only merge requests in [draft status](../../user/project/merge_requests/drafts.md), `no` returns only merge requests not in draft status. Available only for merge requests. |
-| `excludeAssignee` | **{dotted-circle}** No | not applicable | Return items not assigned to the given username. Available only for issues. For the current user, set to `<current_user>`. |
-| `excludeAuthor` | **{dotted-circle}** No | not applicable | Return items not created by the given username. Available only for issues. For the current user, set to `<current_user>`. |
-| `excludeLabels` | **{dotted-circle}** No | `[]` | Array of label names. Available only for issues. Items returned have none of the labels in the array. Predefined names are case-insensitive. |
-| `excludeMilestone` | **{dotted-circle}** No | not applicable | The milestone title to exclude. Available only for issues. |
-| `excludeSearch` | **{dotted-circle}** No | not applicable | Search GitLab items that doesn't have the search key in their title or description. Works only with issues. |
-| `labels` | **{dotted-circle}** No | `[]` | Array of label names. Items returned have all labels in the array. `None` returns items with no labels. `Any` returns items with at least one label. Predefined names are case-insensitive. |
-| `maxResults` | **{dotted-circle}** No | 20 | The number of results to show. |
-| `milestone` | **{dotted-circle}** No | not applicable | The milestone title. `None` lists all items with no milestone. `Any` lists all items with an assigned milestone. Not available for epics and vulnerabilities. |
-| `orderBy` | **{dotted-circle}** No | `created_at` | Return entities ordered by the selected value. Possible values: `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight`. Some values are specific to issues, and some to merge requests. For more information, see [List merge requests](../../api/merge_requests.md#list-merge-requests). |
-| `reviewer` | **{dotted-circle}** No | not applicable | Return merge requests assigned for review to this username. For the current user, set to `<current_user>`. `None` returns items without a reviewer. `Any` returns items with a reviewer. |
-| `scope` | **{dotted-circle}** No | `all` | Return GitLab items for the given scope. Not applicable for epics. Possible values: `assigned_to_me`, `created_by_me`, `all`. |
-| `search` | **{dotted-circle}** No | not applicable | Search GitLab items against their title and description. |
-| `searchIn` | **{dotted-circle}** No | `all` | Change the scope of the `excludeSearch` search attribute. Possible values: `all`, `title`, `description`. Works only with issues. |
-| `sort` | **{dotted-circle}** No | `desc` | Return issues sorted in ascending or descending order. Possible values: `asc`, `desc`. |
-| `state` | **{dotted-circle}** No | `opened` | Return all issues, or only those matching a particular state. Possible values: `all`, `opened`, `closed`. |
-| `updatedAfter` | **{dotted-circle}** No | not applicable | Return items updated after the given date. |
-| `updatedBefore` | **{dotted-circle}** No | not applicable | Return items updated before the given date. |
+| `assignee` | {{< icon name="dotted-circle" >}} No | not applicable | Return items assigned to the given username. `None` returns unassigned GitLab items. `Any` returns GitLab items with an assignee. Not available for epics and vulnerabilities. |
+| `author` | {{< icon name="dotted-circle" >}} No | not applicable | Return items created by the given username. |
+| `confidential` | {{< icon name="dotted-circle" >}} No | not applicable | Filter confidential or public issues. Available only for issues. |
+| `createdAfter` | {{< icon name="dotted-circle" >}} No | not applicable | Return items created after the given date. |
+| `createdBefore` | {{< icon name="dotted-circle" >}} No | not applicable | Return items created before the given date. |
+| `draft` | {{< icon name="dotted-circle" >}} No | `no` | Filter merge requests against their draft status: `yes` returns only merge requests in [draft status](../../user/project/merge_requests/drafts.md), `no` returns only merge requests not in draft status. Available only for merge requests. |
+| `excludeAssignee` | {{< icon name="dotted-circle" >}} No | not applicable | Return items not assigned to the given username. Available only for issues. For the current user, set to `<current_user>`. |
+| `excludeAuthor` | {{< icon name="dotted-circle" >}} No | not applicable | Return items not created by the given username. Available only for issues. For the current user, set to `<current_user>`. |
+| `excludeLabels` | {{< icon name="dotted-circle" >}} No | `[]` | Array of label names. Available only for issues. Items returned have none of the labels in the array. Predefined names are case-insensitive. |
+| `excludeMilestone` | {{< icon name="dotted-circle" >}} No | not applicable | The milestone title to exclude. Available only for issues. |
+| `excludeSearch` | {{< icon name="dotted-circle" >}} No | not applicable | Search GitLab items that doesn't have the search key in their title or description. Works only with issues. |
+| `labels` | {{< icon name="dotted-circle" >}} No | `[]` | Array of label names. Items returned have all labels in the array. `None` returns items with no labels. `Any` returns items with at least one label. Predefined names are case-insensitive. |
+| `maxResults` | {{< icon name="dotted-circle" >}} No | 20 | The number of results to show. |
+| `milestone` | {{< icon name="dotted-circle" >}} No | not applicable | The milestone title. `None` lists all items with no milestone. `Any` lists all items with an assigned milestone. Not available for epics and vulnerabilities. |
+| `orderBy` | {{< icon name="dotted-circle" >}} No | `created_at` | Return entities ordered by the selected value. Possible values: `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight`. Some values are specific to issues, and some to merge requests. For more information, see [List merge requests](../../api/merge_requests.md#list-merge-requests). |
+| `reviewer` | {{< icon name="dotted-circle" >}} No | not applicable | Return merge requests assigned for review to this username. For the current user, set to `<current_user>`. `None` returns items without a reviewer. `Any` returns items with a reviewer. |
+| `scope` | {{< icon name="dotted-circle" >}} No | `all` | Return GitLab items for the given scope. Not applicable for epics. Possible values: `assigned_to_me`, `created_by_me`, `all`. |
+| `search` | {{< icon name="dotted-circle" >}} No | not applicable | Search GitLab items against their title and description. |
+| `searchIn` | {{< icon name="dotted-circle" >}} No | `all` | Change the scope of the `excludeSearch` search attribute. Possible values: `all`, `title`, `description`. Works only with issues. |
+| `sort` | {{< icon name="dotted-circle" >}} No | `desc` | Return issues sorted in ascending or descending order. Possible values: `asc`, `desc`. |
+| `state` | {{< icon name="dotted-circle" >}} No | `opened` | Return all issues, or only those matching a particular state. Possible values: `all`, `opened`, `closed`. |
+| `updatedAfter` | {{< icon name="dotted-circle" >}} No | not applicable | Return items updated after the given date. |
+| `updatedBefore` | {{< icon name="dotted-circle" >}} No | not applicable | Return items updated before the given date. |
### Supported parameters for vulnerability report queries
@@ -114,7 +114,7 @@ with other entry types. Each parameter listed in this table works with vulnerabi
| Parameter | Required | Default | Definition |
|--------------------|------------------------|----------------|------------|
-| `confidenceLevels` | **{dotted-circle}** No | `all` | Returns vulnerabilities belonging to specified confidence levels. Possible values: `undefined`, `ignore`, `unknown`, `experimental`, `low`, `medium`, `high`, `confirmed`. |
-| `reportTypes` | **{dotted-circle}** No | Not applicable | Returns vulnerabilities belonging to specified report types. Possible values: `sast`, `dast`, `dependency_scanning`, `container_scanning`. |
-| `scope` | **{dotted-circle}** No | `dismissed` | Returns vulnerability findings for the given scope. Possible values: `all`, `dismissed`. For more information, see the [Vulnerability findings API](../../api/vulnerability_findings.md). |
-| `severityLevels` | **{dotted-circle}** No | `all` | Returns vulnerabilities belonging to specified severity levels. Possible values: `undefined`, `info`, `unknown`, `low`, `medium`, `high`, `critical`. |
+| `confidenceLevels` | {{< icon name="dotted-circle" >}} No | `all` | Returns vulnerabilities belonging to specified confidence levels. Possible values: `undefined`, `ignore`, `unknown`, `experimental`, `low`, `medium`, `high`, `confirmed`. |
+| `reportTypes` | {{< icon name="dotted-circle" >}} No | Not applicable | Returns vulnerabilities belonging to specified report types. Possible values: `sast`, `dast`, `dependency_scanning`, `container_scanning`. |
+| `scope` | {{< icon name="dotted-circle" >}} No | `dismissed` | Returns vulnerability findings for the given scope. Possible values: `all`, `dismissed`. For more information, see the [Vulnerability findings API](../../api/vulnerability_findings.md). |
+| `severityLevels` | {{< icon name="dotted-circle" >}} No | `all` | Returns vulnerabilities belonging to specified severity levels. Possible values: `undefined`, `info`, `unknown`, `low`, `medium`, `high`, `critical`. |
diff --git a/doc/editor_extensions/visual_studio_code/settings.md b/doc/editor_extensions/visual_studio_code/settings.md
index c544e72977b34b3fb3e21063329384f4ddd67171..a9d180dc1b8f13ecf91d2ed4cec1b9ac76a8bbd0 100644
--- a/doc/editor_extensions/visual_studio_code/settings.md
+++ b/doc/editor_extensions/visual_studio_code/settings.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Settings and commands in the GitLab Workflow extension for VS Code."
+description: Settings and commands in the GitLab Workflow extension for VS Code.
title: GitLab Workflow extension settings and commands
---
diff --git a/doc/editor_extensions/visual_studio_code/setup.md b/doc/editor_extensions/visual_studio_code/setup.md
index 870621d5b219ba10562652de4427514b70e0f2bf..5ee4b77a2b110eb8d8f5c2a8994f3d29772139c5 100644
--- a/doc/editor_extensions/visual_studio_code/setup.md
+++ b/doc/editor_extensions/visual_studio_code/setup.md
@@ -2,7 +2,7 @@
stage: Create
group: Editor Extensions
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
-description: "Use the GitLab Workflow extension for VS Code to handle common GitLab tasks directly in VS Code."
+description: Use the GitLab Workflow extension for VS Code to handle common GitLab tasks directly in VS Code.
title: Install and set up the GitLab Workflow extension for VS Code
---
diff --git a/doc/editor_extensions/visual_studio_code/ssl.md b/doc/editor_extensions/visual_studio_code/ssl.md
index e681c816997548c58384982c99cc63fa6d072cc2..5faacce2883ae672a1f137e47ae1aac0886bcb1b 100644
--- a/doc/editor_extensions/visual_studio_code/ssl.md
+++ b/doc/editor_extensions/visual_studio_code/ssl.md
@@ -33,9 +33,12 @@ Prerequisites:
### Windows
-NOTE:
+{{< alert type="note" >}}
+
These instructions were tested on Windows 10 and VS Code 1.60.0.
+{{< /alert >}}
+
Make sure you can see your self-signed CA in your certificate store:
1. Open the command prompt.
@@ -44,9 +47,12 @@ Make sure you can see your self-signed CA in your certificate store:
### Linux
-NOTE:
+{{< alert type="note" >}}
+
These instructions were tested on Arch Linux `5.14.3-arch1-1` and VS Code 1.60.0.
+{{< /alert >}}
+
1. Use your operating system's tools to confirm you can add our self-signed CA to your system:
- `update-ca-trust` (Fedora, RHEL, CentOS)
- `update-ca-certificates` (Ubuntu, Debian, OpenSUSE, SLES)
@@ -56,10 +62,13 @@ These instructions were tested on Arch Linux `5.14.3-arch1-1` and VS Code 1.60.0
### MacOS
-NOTE:
+{{< alert type="note" >}}
+
These instructions are untested, but should work as intended. If you can confirm this setup,
create a documentation issue with more information.
+{{< /alert >}}
+
Make sure you see the self-signed CA in your keychain:
1. Go to **Finder > Applications > Utilities > Keychain Access**.
diff --git a/doc/editor_extensions/visual_studio_code/troubleshooting.md b/doc/editor_extensions/visual_studio_code/troubleshooting.md
index 34898415a059fed7615358e693c3bc1ee1f90b31..ea86faacc6057c716084df756135031656b9ee66 100644
--- a/doc/editor_extensions/visual_studio_code/troubleshooting.md
+++ b/doc/editor_extensions/visual_studio_code/troubleshooting.md
@@ -83,7 +83,7 @@ Both have the `gitlab.com` and `gitlab-org/gitlab-vscode-extension` path.
To fix this problem, check if your SSH URL is on a different host, or if it has extra segments in a path.
If either is true, you can manually assign a Git repository to a GitLab project:
-1. In VS Code, on the left sidebar, select **GitLab Workflow** (**{tanuki}**).
+1. In VS Code, on the left sidebar, select **GitLab Workflow** ({{< icon name="tanuki" >}}).
1. Select the project marked `(no GitLab project)`, then select **Manually assign GitLab project**:
1. Select the correct project from the list.
diff --git a/doc/install/aws/_index.md b/doc/install/aws/_index.md
index 7f2e9840666ff0824fde58ce6fc8976511c2bc1d..91478b15469964d5e6edcf40d20b30aea200c508 100644
--- a/doc/install/aws/_index.md
+++ b/doc/install/aws/_index.md
@@ -6,21 +6,30 @@ description: Read through the GitLab installation methods.
title: Installing a GitLab POC on Amazon Web Services (AWS)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page offers a walkthrough of a common configuration for GitLab on AWS using the official Linux package. You should customize it to accommodate your needs.
-NOTE:
+{{< alert type="note" >}}
+
For organizations with 1,000 users or less, the recommended AWS installation method is to launch an EC2 single box [Linux package installation](https://about.gitlab.com/install/) and implement a snapshot strategy for backing up the data. See the [20 RPS or 1,000 user reference architecture](../../administration/reference_architectures/1k_users.md) for more information.
+{{< /alert >}}
+
## Getting started for production-grade GitLab
-NOTE:
+{{< alert type="note" >}}
+
This document is an installation guide for a proof of concept instance. It is not a reference architecture, and it does not result in a highly available configuration.
It's highly recommended to use the [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/gitlab-environment-toolkit) instead.
+{{< /alert >}}
+
Following this guide exactly results in a proof of concept instance that roughly equates to a **scaled down** version of a **two availability zone implementation** of the **Non-HA** [40 RPS or 2,000 User Reference Architecture](../../administration/reference_architectures/2k_users.md). The 2K reference architecture is not HA because it is primarily intended to provide some scaling while keeping costs and complexity low. The [60 RPS or 3,000 User Reference Architecture](../../administration/reference_architectures/3k_users.md) is the smallest size that is GitLab HA. It has additional service roles to achieve HA, most notably it uses Gitaly Cluster to achieve HA for Git repository storage and specifies triple redundancy.
GitLab maintains and tests two main types of Reference Architectures. The **Linux package architectures** are implemented on instance compute while **Cloud Native Hybrid architectures** maximize the use of a Kubernetes cluster. Cloud Native Hybrid reference architecture specifications are addendum sections to the Reference Architecture size pages that start by describing the Linux package architecture. For example, the 60 RPS or 3,000 User Cloud Native Reference Architecture is in the subsection titled [Cloud Native Hybrid reference architecture with Helm Charts (alternative)](../../administration/reference_architectures/3k_users.md#cloud-native-hybrid-reference-architecture-with-helm-charts-alternative) in the 60 RPS or 3,000 User Reference Architecture page.
@@ -55,9 +64,12 @@ In addition to having a basic familiarity with [AWS](https://docs.aws.amazon.com
- A domain name for the GitLab instance
- An SSL/TLS certificate to secure your domain. If you do not already own one, you can provision a free public SSL/TLS certificate through [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/)(ACM) for use with the [Elastic Load Balancer](#load-balancer) we create.
-NOTE:
+{{< alert type="note" >}}
+
It can take a few hours to validate a certificate provisioned through ACM. To avoid delays later, request your certificate as soon as possible.
+{{< /alert >}}
+
## Architecture
Below is a diagram of the recommended architecture.
@@ -349,9 +361,12 @@ We need a security group for our database that allows inbound traffic from the i
### Create the database
-WARNING:
+{{< alert type="warning" >}}
+
Avoid using burstable instances (t class instances) for the database as this could lead to performance issues due to CPU credits running out during sustained periods of high load.
+{{< /alert >}}
+
Now, it's time to create the database:
1. Go to the RDS dashboard, select **Databases** from the left menu, and select **Create database**.
@@ -446,9 +461,12 @@ to these instances with SSH for actions that include making configuration change
and performing upgrades. One way of doing this is by using a [bastion host](https://en.wikipedia.org/wiki/Bastion_host),
sometimes also referred to as a jump box.
-NOTE:
+{{< alert type="note" >}}
+
If you do not want to maintain bastion hosts, you can set up [AWS Systems Manager Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) for access to instances. This is beyond the scope of this document.
+{{< /alert >}}
+
### Create Bastion Host A
1. Go to the EC2 Dashboard and select **Launch instance**.
@@ -618,10 +636,13 @@ gitlab=# \q
#### Set up Gitaly
-WARNING:
+{{< alert type="warning" >}}
+
In this architecture, having a single Gitaly server creates a single point of failure. Use
[Gitaly Cluster](../../administration/gitaly/praefect.md) to remove this limitation.
+{{< /alert >}}
+
Gitaly is a service that provides high-level RPC access to Git repositories.
It should be enabled and configured on a separate EC2 instance in one of the
[private subnets](#subnets) we configured previously.
@@ -645,9 +666,12 @@ Let's create an EC2 instance where we install Gitaly:
1. For **IOPS** set `1000` (20 GiB x 50 IOPS). You can provision up to 50 IOPS per GiB. If you select a larger volume, increase the IOPS accordingly. Workloads where many small files are written in a serialized manner, like `git`, requires performant storage, hence the choice of `Provisioned IOPS SSD (io1)`.
1. Review all your settings and, if you're happy, select **Launch Instance**.
-NOTE:
+{{< alert type="note" >}}
+
Instead of storing configuration _and_ repository data on the root volume, you can also choose to add an additional EBS volume for repository storage. Follow the same guidance as above. See the [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/). We do not recommend using EFS as it may negatively impact the performance of GitLab. You can review the [relevant documentation](../../administration/nfs.md#avoid-using-cloud-based-file-systems) for more details.
+{{< /alert >}}
+
Now that we have our EC2 instance ready, follow the [documentation to install GitLab and set up Gitaly on its own server](../../administration/gitaly/configure_gitaly.md#run-gitaly-on-its-own-server). Perform the client setup steps from that document on the [GitLab instance we created](#install-gitlab) above.
#### Add Support for Proxied SSL
@@ -699,9 +723,12 @@ HostKey /etc/ssh_static/ssh_host_ed25519_key
Because we're not using NFS for shared storage, we use [Amazon S3](https://aws.amazon.com/s3/) buckets to store backups, artifacts, LFS objects, uploads, merge request diffs, container registry images, and more. Our documentation includes [instructions on how to configure object storage](../../administration/object_storage.md) for each of these data types, and other information about using object storage with GitLab.
-NOTE:
+{{< alert type="note" >}}
+
Because we are using the [AWS IAM profile](#create-an-iam-role) we created earlier, be sure to omit the AWS access key and secret access key/value pairs when configuring object storage. Instead, use `'use_iam_profile' => true` in your configuration as shown in the object storage documentation linked above.
+{{< /alert >}}
+
Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `gitlab.rb` file.
---
diff --git a/doc/install/azure/_index.md b/doc/install/azure/_index.md
index dd02a105c059ee98d541170b8db6228cfbfb08e0..f402a881cd338449411fa5d7f8867aa8ebb122db 100644
--- a/doc/install/azure/_index.md
+++ b/doc/install/azure/_index.md
@@ -2,13 +2,16 @@
stage: Systems
group: Distribution
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
-description: 'Learn how to spin up a pre-configured GitLab VM on Microsoft Azure.'
+description: Learn how to spin up a pre-configured GitLab VM on Microsoft Azure.
title: Install GitLab on Microsoft Azure
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
For users of the Microsoft Azure business cloud, GitLab has a pre-configured offering in
the [Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/).
@@ -41,7 +44,8 @@ create a new VM:
For the sake of this guide, let's create the VM from scratch, so
select **Create**.
-NOTE:
+{{< alert type="note" >}}
+
Be aware that Azure incurs compute charges whenever your VM is
active (known as "allocated"), even if you're using free trial
credits.
@@ -49,6 +53,8 @@ credits.
See the [Azure pricing calculator](https://azure.microsoft.com/en-us/pricing/calculator/)
to learn how much resources can cost.
+{{< /alert >}}
+
After you create the virtual machine, use the information in the following
sections to configure it.
@@ -183,10 +189,13 @@ To set up the GitLab external URL:
ssh -i <private key path> gitlab-azure@gitlab-prod.eastus.cloudapp.azure.com
```
- NOTE:
- If you need to reset your credentials, read
+ {{< alert type="note" >}}
+
+If you need to reset your credentials, read
[how to reset SSH credentials for a user on an Azure VM](https://learn.microsoft.com/en-us/troubleshoot/azure/virtual-machines/linux/troubleshoot-ssh-connection#reset-ssh-credentials-for-a-user).
+ {{< /alert >}}
+
1. Open `/etc/gitlab/gitlab.rb` with your editor.
1. Find `external_url` and replace it with your own domain name. For the sake
of this example, use the default domain name Azure sets up.
@@ -272,11 +281,14 @@ To update GitLab to the latest version:
and can take time to complete. During this time, the terminal shows various update tasks being
completed in your terminal.
- NOTE:
- If you get an error like
+ {{< alert type="note" >}}
+
+If you get an error like
`E: The repository 'https://packages.gitlab.com/gitlab/gitlab-ee/debian buster InRelease' is not signed.`,
see the [troubleshooting section](#update-the-gpg-key-for-the-gitlab-repositories).
+ {{< /alert >}}
+
1. After the update process is complete, a message like the
following appears:
@@ -303,10 +315,13 @@ This section describes common errors you can encounter.
### Update the GPG key for the GitLab repositories
-NOTE:
+{{< alert type="note" >}}
+
This is a temporary fix until the GitLab image is updated with the new
GPG key.
+{{< /alert >}}
+
The pre-configured GitLab image in Azure (provided by Bitnami) uses
a GPG key [deprecated in April 2020](https://about.gitlab.com/blog/2020/03/30/gpg-key-for-gitlab-package-repositories-metadata-changing/).
diff --git a/doc/install/cloud_providers.md b/doc/install/cloud_providers.md
index 839b3d28d79fddf0d51431e8b53b503defb28141..313c8deb34b09696af6fa88c0afb7bb1756228a5 100644
--- a/doc/install/cloud_providers.md
+++ b/doc/install/cloud_providers.md
@@ -1,14 +1,17 @@
---
stage: Systems
group: Distribution
-description: AWS, Google Cloud Platform, Azure.
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
+description: AWS, Google Cloud Platform, Azure.
title: Install GitLab on a cloud provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can install GitLab on several cloud providers.
diff --git a/doc/install/docker/_index.md b/doc/install/docker/_index.md
index b54a81d1083201179b4fa13e3f17b82863434eb7..56788cb15874b9c151a52906b7346df62bead131 100644
--- a/doc/install/docker/_index.md
+++ b/doc/install/docker/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Install GitLab in a Docker container
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To run GitLab in a Docker container, use a GitLab image, which contains all of the
necessary services in a single container.
diff --git a/doc/install/docker/backup.md b/doc/install/docker/backup.md
index 941833d779b7a62ee170d2e4b5907341a1e15700..48002dd444fe7deb788a9380d6caa1eee44df7e2 100644
--- a/doc/install/docker/backup.md
+++ b/doc/install/docker/backup.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Back up GitLab running in a Docker container
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can create a GitLab backup with:
@@ -17,19 +20,25 @@ docker exec -t <container name> gitlab-backup create
For more information, see [Back up and restore GitLab](../../administration/backup_restore/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
If your GitLab configuration is provided entirely using the `GITLAB_OMNIBUS_CONFIG` environment variable
(by using the ["Pre-configure Docker Container"](configuration.md#pre-configure-docker-container) steps),
the configuration settings are not stored in the `gitlab.rb` file so you do not need
to back up the `gitlab.rb` file.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
To avoid [complicated steps](../../administration/backup_restore/troubleshooting_backup_gitlab.md#when-the-secrets-file-is-lost) when recovering
GitLab from a backup, you should also follow the instructions in
[Backing up the GitLab secrets file](../../administration/backup_restore/backup_gitlab.md#storing-configuration-files).
The secrets file is stored either in the `/etc/gitlab/gitlab-secrets.json` file inside the container or in the
`$GITLAB_HOME/config/gitlab-secrets.json` file [on the container host](installation.md#create-a-directory-for-the-volumes).
+{{< /alert >}}
+
## Create a database backup
Before you upgrade GitLab, create a database-only backup. If you encounter issues during the GitLab upgrade, you can restore the database backup to roll back the upgrade. To create a database backup, run this command:
diff --git a/doc/install/docker/configuration.md b/doc/install/docker/configuration.md
index ae651979b7dd60c23aad542bd4ba29340ebf8361..d5bf99aa48f15363b445f247824b897cdbea37e1 100644
--- a/doc/install/docker/configuration.md
+++ b/doc/install/docker/configuration.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure GitLab running in a Docker container
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This container uses the official Linux package, so you can use
the unique configuration file `/etc/gitlab/gitlab.rb` to configure the instance.
@@ -135,11 +138,14 @@ port `2424`:
gitlab/gitlab-ee:<version>-ee.0
```
- NOTE:
- The format to publish ports is `hostPort:containerPort`. Read more in the
+ {{< alert type="note" >}}
+
+The format to publish ports is `hostPort:containerPort`. Read more in the
Docker documentation about
[exposing incoming ports](https://docs.docker.com/network/#published-ports).
+ {{< /alert >}}
+
1. Enter the running container:
```shell
diff --git a/doc/install/docker/installation.md b/doc/install/docker/installation.md
index ca75bd38d4f471c21bffc7ea623116867a0afc51..4b32828b3566a4f3c6c9d48c8a5037d7ef6012eb 100644
--- a/doc/install/docker/installation.md
+++ b/doc/install/docker/installation.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Install GitLab in a Docker container
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To install GitLab in a Docker container, use Docker Compose, Docker Engine, or Docker Swarm mode.
@@ -166,10 +169,13 @@ install, and upgrade your Docker-based GitLab installation:
shm_size: '256m'
```
- NOTE:
- Read the [Pre-configure Docker container](configuration.md#pre-configure-docker-container) section
+ {{< alert type="note" >}}
+
+Read the [Pre-configure Docker container](configuration.md#pre-configure-docker-container) section
to see how the `GITLAB_OMNIBUS_CONFIG` variable works.
+ {{< /alert >}}
+
Here is another `docker-compose.yml` example with GitLab running on a custom
HTTP and SSH port. Notice that the `GITLAB_OMNIBUS_CONFIG` variables match the
`ports` section:
@@ -273,9 +279,12 @@ and the password from the following command:
/etc/gitlab/initial_root_password
```
-NOTE:
+{{< alert type="note" >}}
+
The password file is automatically deleted in the first container restart after 24 hours.
+{{< /alert >}}
+
### Install GitLab by using Docker Swarm mode
With [Docker Swarm mode](https://docs.docker.com/engine/swarm/), you can
diff --git a/doc/install/docker/troubleshooting.md b/doc/install/docker/troubleshooting.md
index bd44d419ed5033edee14cee36ca75141ed661f2c..ad33159db470b4705603a7cff7d0f7ea0ba78c30 100644
--- a/doc/install/docker/troubleshooting.md
+++ b/doc/install/docker/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting GitLab running in a Docker container
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When installing GitLab in a Docker container, you might encounter the following problems.
diff --git a/doc/install/docker/upgrade.md b/doc/install/docker/upgrade.md
index 67a7bd4ef80d13696c2b1f005309b776e01dfad4..8fcd2d2e5a403bc24fd7b5edca99384f17ecd259 100644
--- a/doc/install/docker/upgrade.md
+++ b/doc/install/docker/upgrade.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Upgrade
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
In most cases, upgrading GitLab is as easy as downloading the newest Docker
image tag.
@@ -102,10 +105,13 @@ The following steps assume that you are converting to the same version.
The restore overwrites all newer GitLab database content with the older state.
A downgrade is only recommended where necessary. For example, if post-upgrade tests reveal problems that cannot be resolved quickly.
-WARNING:
+{{< alert type="warning" >}}
+
You must have at least a database backup created with the exact same version and edition you are downgrading to.
The backup is required to revert the schema changes (migrations) made during the upgrade.
+{{< /alert >}}
+
To downgrade GitLab shortly after an upgrade:
1. Follow the upgrade procedure, by [specifying an earlier version](installation.md#find-the-gitlab-version-and-edition-to-use)
diff --git a/doc/install/google_cloud_platform/_index.md b/doc/install/google_cloud_platform/_index.md
index 84c61b1b1667f53376ce905387515c444addda93..3afa5f2f6901ba83168515a77c327d14d37fc1b5 100644
--- a/doc/install/google_cloud_platform/_index.md
+++ b/doc/install/google_cloud_platform/_index.md
@@ -2,17 +2,21 @@
stage: Systems
group: Distribution
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
-description: 'Learn how to install a GitLab instance on Google Cloud Platform.'
+description: Learn how to install a GitLab instance on Google Cloud Platform.
title: Installing GitLab on Google Cloud Platform
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can install GitLab on a [Google Cloud Platform (GCP)](https://cloud.google.com/) using the official Linux package. You should customize it to accommodate your needs.
-NOTE:
+{{< alert type="note" >}}
+
To deploy production-ready GitLab on
Google Kubernetes Engine,
you can follow Google Cloud Platform's
@@ -20,6 +24,8 @@ you can follow Google Cloud Platform's
It's an alternative to using a GCP VM, and uses
the [Cloud native GitLab Helm chart](https://docs.gitlab.com/charts/).
+{{< /alert >}}
+
## Prerequisites
There are two prerequisites to install GitLab on GCP:
diff --git a/doc/install/install_ai_gateway.md b/doc/install/install_ai_gateway.md
index 1f044dc52e8021164f4ef8c201221e56be4f9223..5b7ff50437998ac01cf863a98418ec819adefaf1 100644
--- a/doc/install/install_ai_gateway.md
+++ b/doc/install/install_ai_gateway.md
@@ -1,8 +1,8 @@
---
stage: AI-Powered
group: AI Framework
-description: Set up your self-hosted model GitLab AI gateway
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
+description: Set up your self-hosted model GitLab AI gateway
title: Install the GitLab AI gateway
---
@@ -34,9 +34,12 @@ Find the GitLab official Docker image at:
Use the image tag that corresponds to your GitLab version. For example, if your GitLab version is `v17.9.0`, use the `self-hosted-17.9.0-ee` tag. It is critical to ensure that the image version matches your GitLab version to avoid compatibility issues. Nightly builds are available to have access to newer features, but backwards compatibility is not guaranteed.
-NOTE:
+{{< alert type="note" >}}
+
Using the `:latest` tag is **not recommended** as it can cause incompatibility if your GitLab version lags behind or jumps ahead of the AI Gateway release. Always use an explicit version tag.
+{{< /alert >}}
+
### Start a Container from the Image
1. Run the following command, replacing `<your_gitlab_instance>` and `<your_gitlab_domain>` with your GitLab instance's URL and domain:
diff --git a/doc/install/install_methods.md b/doc/install/install_methods.md
index 7bd8dd98c94d0b2c307048a78a39a61e19c76b3b..20e1a5d6e4e395f3a4d6c792efc5858c49a5fcb9 100644
--- a/doc/install/install_methods.md
+++ b/doc/install/install_methods.md
@@ -1,14 +1,17 @@
---
stage: Systems
group: Distribution
-description: Linux, Helm, Docker, Operator, source, or scripts.
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
+description: Linux, Helm, Docker, Operator, source, or scripts.
title: Installation methods
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can install GitLab on several [cloud providers](cloud_providers.md),
or use one of the following methods.
diff --git a/doc/install/installation.md b/doc/install/installation.md
index 58241197b5c5c41bac1b241761ee6f4cd5f8584f..958b1fa15202c60337161a0a2092c15440cca593 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Self-compiled installation
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This is the official installation guide to set up a production GitLab server
using the source files. It was created for and tested on **Debian/Ubuntu** operating systems.
@@ -125,10 +128,13 @@ sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdb
runit-systemd
```
-NOTE:
+{{< alert type="note" >}}
+
GitLab requires OpenSSL version 1.1. If your Linux distribution includes a different version of OpenSSL,
you might have to install 1.1 manually.
+{{< /alert >}}
+
### Git
You should use the
@@ -294,10 +300,13 @@ sudo adduser --disabled-login --gecos 'GitLab' git
## 7. Database
-NOTE:
+{{< alert type="note" >}}
+
Only PostgreSQL is supported.
In GitLab 17.0 and later, we [require PostgreSQL 14+](requirements.md#postgresql).
+{{< /alert >}}
+
1. Install the database packages.
For Ubuntu 22.04 and later:
@@ -536,9 +545,12 @@ Make sure to replace `<X-Y-stable>` with the stable branch that matches the
version you want to install. For example, if you want to install 11.8 you would
use the branch name `11-8-stable`.
-WARNING:
+{{< alert type="warning" >}}
+
You can change `<X-Y-stable>` to `master` if you want the *bleeding edge* version, but never install `master` on a production server!
+{{< /alert >}}
+
### Configure It
```shell
@@ -603,10 +615,13 @@ If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional ste
### Configure GitLab DB Settings
-NOTE:
+{{< alert type="note" >}}
+
From [GitLab 15.9](https://gitlab.com/gitlab-org/gitlab/-/issues/387898), `database.yml` with only a section: `main:` is deprecated.
In GitLab 17.0 and later, you must have the two `main:` and `ci:` sections in your `database.yml`.
+{{< /alert >}}
+
```shell
sudo -u git cp config/database.yml.postgresql config/database.yml
@@ -646,9 +661,12 @@ connection [must be to the same database](../administration/postgresql/multiple_
### Install Gems
-NOTE:
+{{< alert type="note" >}}
+
As of Bundler 1.5.2, you can invoke `bundle install -jN` (where `N` is the number of your processor cores) and enjoy parallel gems installation with measurable difference in completion time (~60% faster). Check the number of your cores with `nproc`. For more information, see this [post](https://thoughtbot.com/blog/parallel-gem-installing-using-bundler).
+{{< /alert >}}
+
Make sure you have `bundle` (run `bundle -v`):
- `>= 1.5.2`, because some [issues](https://devcenter.heroku.com/changelog-items/411) were [fixed](https://github.com/rubygems/bundler/pull/2817) in 1.5.2.
@@ -699,9 +717,12 @@ sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workh
### Install GitLab-Elasticsearch-indexer on Enterprise Edition
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab-Elasticsearch-Indexer uses [GNU Make](https://www.gnu.org/software/make/). The
following command-line installs GitLab-Elasticsearch-Indexer in `/home/git/gitlab-elasticsearch-indexer`
@@ -1028,9 +1049,12 @@ sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
If all items are green, congratulations on successfully installing GitLab!
-NOTE:
+{{< alert type="note" >}}
+
Supply the `SANITIZE=true` environment variable to `gitlab:check` to omit project names from the output of the check command.
+{{< /alert >}}
+
### Initial Login
Visit YOUR_SERVER in your web browser for your first GitLab login.
diff --git a/doc/install/next_steps.md b/doc/install/next_steps.md
index 0fdd529a73f97f02f18ab753b4e897138404d697..e2dae545db39a2d8ef0f346827877062b59d99ce 100644
--- a/doc/install/next_steps.md
+++ b/doc/install/next_steps.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Steps after installing GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Here are a few resources you might want to check out after completing the
installation.
diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md
index a3d04b04ff707645efdba5fd67c61fbcf7cce6ee..2a7333cf39d681872c39b1f8ccffe7280fe09fb0 100644
--- a/doc/install/postgresql_extensions.md
+++ b/doc/install/postgresql_extensions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Managing PostgreSQL extensions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This guide documents how to manage PostgreSQL extensions for installations with an external
PostgreSQL database.
diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md
index e3ea5d1c2df5e844105cddff0ca23a35091b021d..bd3094a56bd1db12cbc3ed6d5b9c93a9a0d12b89 100644
--- a/doc/install/relative_url.md
+++ b/doc/install/relative_url.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Install GitLab under a relative URL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
While you should install GitLab on its own (sub)domain, sometimes
this is not possible due to a variety of reasons. In that case, GitLab can also
@@ -49,10 +52,13 @@ See the [requirements](requirements.md) document for more information.
## Enable relative URL in GitLab
-NOTE:
+{{< alert type="note" >}}
+
Do not make any changes to your web server configuration file regarding
relative URL. The relative URL support is implemented by GitLab Workhorse.
+{{< /alert >}}
+
---
Before following the steps below to enable relative URL in GitLab, some
@@ -114,10 +120,13 @@ Make sure to follow all steps below:
-authBackend http://127.0.0.1:8080/gitlab
```
- NOTE:
- If you are using a custom init script, make sure to edit the above
+ {{< alert type="note" >}}
+
+If you are using a custom init script, make sure to edit the above
GitLab Workhorse setting as needed.
+ {{< /alert >}}
+
1. [Restart GitLab](../administration/restart_gitlab.md#self-compiled-installations) for the changes to take effect.
## Disable relative URL in GitLab
diff --git a/doc/install/requirements.md b/doc/install/requirements.md
index e70969a2ff90297fb2f74590f7cdc4ae58f6bc80..aaf1df4e8aa2c1bce63fecc1994724733a2c945c 100644
--- a/doc/install/requirements.md
+++ b/doc/install/requirements.md
@@ -1,14 +1,17 @@
---
stage: Systems
group: Distribution
-description: Prerequisites for installation.
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
+description: Prerequisites for installation.
title: GitLab installation requirements
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page contains information about the system requirements to install GitLab.
diff --git a/doc/integration/_index.md b/doc/integration/_index.md
index 79c93d033bebd744b77f811efa784f03d6378ae2..5c3d98fc0921bedf9b7b660fce707fd6037d4da7 100644
--- a/doc/integration/_index.md
+++ b/doc/integration/_index.md
@@ -1,8 +1,8 @@
---
stage: Foundations
group: Import and Integrate
-description: Projects, issues, authentication, security providers.
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
+description: Projects, issues, authentication, security providers.
title: Integrate with GitLab
---
diff --git a/doc/integration/advanced_search/elasticsearch.md b/doc/integration/advanced_search/elasticsearch.md
index 8ff457702bd025e2de1aabb6f9e1d29aefccd07a..2277e89c137e9bbe01dff24dad35c9003f0b28ef 100644
--- a/doc/integration/advanced_search/elasticsearch.md
+++ b/doc/integration/advanced_search/elasticsearch.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Elasticsearch
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page describes how to enable advanced search. When enabled,
advanced search provides faster search response times and [improved search features](../../user/search/advanced_search.md).
@@ -17,10 +20,13 @@ To enable advanced search, you must:
1. [Install an Elasticsearch or AWS OpenSearch cluster](#install-an-elasticsearch-or-aws-opensearch-cluster).
1. [Enable advanced search](#enable-advanced-search).
-NOTE:
+{{< alert type="note" >}}
+
Advanced search stores all projects in the same Elasticsearch indices.
However, private projects appear in search results only to users who have access.
+{{< /alert >}}
+
## Elasticsearch glossary
This glossary provides definitions for terms related to Elasticsearch.
@@ -51,15 +57,22 @@ Running the search cluster on the same server as GitLab might lead to performanc
For a search cluster with a single node, the cluster status is always yellow because the primary shard is allocated.
The cluster cannot assign replica shards to the same node as primary shards.
-NOTE:
+{{< alert type="note" >}}
+
Before you use a new Elasticsearch cluster in production, see
[important Elasticsearch configuration](https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html).
+{{< /alert >}}
+
### Version requirements
#### Elasticsearch
-> - Support for Elasticsearch 6.8 [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350275) in GitLab 15.0.
+{{< history >}}
+
+- Support for Elasticsearch 6.8 [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350275) in GitLab 15.0.
+
+{{< /history >}}
Advanced search works with the following versions of Elasticsearch.
@@ -256,11 +269,14 @@ use AWS OpenSearch Service with IAM credentials on your GitLab instance:
1. In **AWS access key** and **AWS secret access key**,
enter your access keys for authentication.
- NOTE:
+ {{< alert type="note" >}}
+
For GitLab deployments on EC2 instances, you do not have to enter access keys.
Your GitLab instance obtains these keys automatically from the
[AWS Instance Metadata Service (IMDS)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html).
+ {{< /alert >}}
+
1. Select **Save changes**.
###### Create a master user
@@ -283,7 +299,11 @@ the master username and password on your GitLab instance:
### Upgrade to a new Elasticsearch major version
-> - Support for Elasticsearch 6.8 [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350275) in GitLab 15.0.
+{{< history >}}
+
+- Support for Elasticsearch 6.8 [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350275) in GitLab 15.0.
+
+{{< /history >}}
When you upgrade Elasticsearch, you do not have to change the GitLab configuration.
@@ -329,9 +349,12 @@ sudo yum install libicu-devel
##### macOS
-NOTE:
+{{< alert type="note" >}}
+
You must first [install Homebrew](https://brew.sh/).
+{{< /alert >}}
+
To install on macOS, run:
```shell
@@ -364,11 +387,14 @@ PREFIX=/usr sudo -E make install
After installation, be sure to [enable Elasticsearch](#enable-advanced-search).
-NOTE:
+{{< alert type="note" >}}
+
If you see an error such as `Permission denied - /home/git/gitlab-elasticsearch-indexer/` while indexing, you
may need to set the `production -> elasticsearch -> indexer_path` setting in your `gitlab.yml` file to
`/usr/local/bin/gitlab-elasticsearch-indexer`, which is where the binary is installed.
+{{< /alert >}}
+
### View indexing errors
Errors from the [GitLab Elasticsearch Indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer) are reported in
@@ -391,19 +417,26 @@ To enable advanced search:
1. Optional. [Check indexing status](#check-indexing-status).
1. After the indexing is complete, select the **Search with Elasticsearch enabled** checkbox, then select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
When your Elasticsearch cluster is down while Elasticsearch is enabled,
you might have problems updating documents such as issues because your
instance queues a job to index the change, but cannot find a valid
Elasticsearch cluster.
+{{< /alert >}}
+
For GitLab instances with more than 50 GB of repository data, see [Index large instances efficiently](#index-large-instances-efficiently).
### Index the instance
#### From the user interface
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271532) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271532) in GitLab 17.3.
+
+{{< /history >}}
Prerequisites:
@@ -511,12 +544,15 @@ The following Elasticsearch settings are available:
| `Code indexing concurrency` | Maximum number of Elasticsearch code indexing background jobs allowed to run concurrently. This only applies to repository indexing operations. |
| `Retry on failure` | Maximum number of possible retries for Elasticsearch search requests. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/486935) in GitLab 17.6. |
-WARNING:
+{{< alert type="warning" >}}
+
Increasing the values of `Maximum bulk request size (MiB)` and `Bulk request concurrency` can negatively impact
Sidekiq performance. Return them to their default values if you see increased `scheduling_latency_s` durations
in your Sidekiq logs. For more information, see
[issue 322147](https://gitlab.com/gitlab-org/gitlab/-/issues/322147).
+{{< /alert >}}
+
### Limit the amount of namespace and project data to index
When you select the **Limit the amount of namespace and project data to index**
@@ -527,16 +563,23 @@ Advanced search only provides cross-group code/commit search (global) if all nam
If you do not specify any namespace or project, [only project records are indexed](#all-project-records-are-indexed).
-WARNING:
+{{< alert type="warning" >}}
+
If you have already indexed your instance, you must regenerate the index to delete all existing data
for filtering to work correctly. To do this, run the Rake tasks `gitlab:elastic:recreate_index` and
`gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list deletes the data
from the Elasticsearch index as expected.
+{{< /alert >}}
+
#### All project records are indexed
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428070) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `search_index_all_projects`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148111) in GitLab 16.11. Feature flag `search_index_all_projects` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428070) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `search_index_all_projects`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148111) in GitLab 16.11. Feature flag `search_index_all_projects` removed.
+
+{{< /history >}}
When you select the **Limit the amount of namespace and project data to index** checkbox:
@@ -711,8 +754,12 @@ To abandon an unfinished reindexing job and resume indexing:
## Index integrity
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112369) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `search_index_integrity`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392981) in GitLab 16.4. Feature flag `search_index_integrity` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112369) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `search_index_integrity`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392981) in GitLab 16.4. Feature flag `search_index_integrity` removed.
+
+{{< /history >}}
Index integrity detects and fixes missing repository data.
This feature is automatically used when code searches
@@ -726,7 +773,11 @@ advanced search, which means adding or changing the way content is indexed.
### Migration dictionary files
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414674) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414674) in GitLab 16.3.
+
+{{< /history >}}
Every migration has a corresponding dictionary file in the `ee/elastic/docs/` folder with the following information:
@@ -938,7 +989,11 @@ To update the shard size for an index, change the setting and trigger [zero-down
##### Indices with database data
-> - `gitlab:elastic:estimate_shard_sizes` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146108) in GitLab 16.11.
+{{< history >}}
+
+- `gitlab:elastic:estimate_shard_sizes` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146108) in GitLab 16.11.
+
+{{< /history >}}
For indices that contain database data:
@@ -980,12 +1035,15 @@ Prerequisites:
- You must have administrator access to the instance.
-WARNING:
+{{< alert type="warning" >}}
+
Indexing a large instance generates a lot of Sidekiq jobs.
Make sure to prepare for this task by having a
[scalable setup](../../administration/reference_architectures/_index.md) or by creating
[extra Sidekiq processes](../../administration/sidekiq/extra_sidekiq_processes.md).
+{{< /alert >}}
+
If [enabling advanced search](#enable-advanced-search) causes problems
due to large volumes of data being indexed:
@@ -1019,8 +1077,11 @@ due to large volumes of data being indexed:
You can expect a 20% decrease in indexing time. After the indexing is complete, you can set `refresh_interval` and `number_of_replicas` back to their desired values.
- NOTE:
- This step is optional but may help significantly speed up large indexing operations.
+ {{< alert type="note" >}}
+
+This step is optional but may help significantly speed up large indexing operations.
+
+ {{< /alert >}}
```shell
curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
@@ -1069,11 +1130,14 @@ due to large volumes of data being indexed:
Where `ID_FROM` and `ID_TO` are project IDs. Both parameters are optional.
The above example indexes all projects from ID `1001` up to (and including) ID `2000`.
- NOTE:
- Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects`
+ {{< alert type="note" >}}
+
+Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects`
can get interrupted. This may happen for many reasons, but it's always safe
to run the indexing task again.
+ {{< /alert >}}
+
You can also use the `gitlab:elastic:clear_index_status` Rake task to force the
indexer to "forget" all progress, so it retries the indexing process from the
start.
@@ -1169,10 +1233,13 @@ However, some larger installations may wish to tune the merge policy settings:
## Index large instances with dedicated Sidekiq nodes or processes
-WARNING:
+{{< alert type="warning" >}}
+
Most instances should not need to configure this. The steps below use an advanced setting of Sidekiq called [routing rules](../../administration/sidekiq/processing_specific_job_classes.md#routing-rules).
Be sure to fully understand about the implication of using routing rules to avoid losing jobs entirely.
+{{< /alert >}}
+
Indexing a large instance can be a lengthy and resource-intensive process that has the potential
of overwhelming Sidekiq nodes and processes. This negatively affects the GitLab performance and
availability.
@@ -1197,15 +1264,21 @@ For the steps below, consider the entry of `sidekiq['routing_rules']`:
At least one process in `sidekiq['queue_groups']` has to include the `mailers` queue, otherwise mailers jobs are not processed at all.
-NOTE:
+{{< alert type="note" >}}
+
Routing rules (`sidekiq['routing_rules']`) must be the same across all GitLab nodes (especially GitLab Rails and Sidekiq nodes).
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
When starting multiple processes, the number of processes cannot exceed the number of CPU
cores you want to dedicate to Sidekiq. Each Sidekiq process can use only one CPU core, subject
to the available workload and concurrency settings. For more details, see how to
[run multiple Sidekiq processes](../../administration/sidekiq/extra_sidekiq_processes.md).
+{{< /alert >}}
+
### Single node, two processes
To create both an indexing and a non-indexing Sidekiq process in one node:
@@ -1241,10 +1314,13 @@ To create both an indexing and a non-indexing Sidekiq process in one node:
1. On all other Rails and Sidekiq nodes, ensure that `sidekiq['routing_rules']` is the same as above.
1. Run the Rake task to [migrate existing jobs](../../administration/sidekiq/sidekiq_job_migration.md):
-NOTE:
+{{< alert type="note" >}}
+
It is important to run the Rake task immediately after reconfiguring GitLab.
After reconfiguring GitLab, existing jobs are not processed until the Rake task starts to migrate the jobs.
+{{< /alert >}}
+
### Two nodes, one process for each
To handle these queue groups on two nodes:
@@ -1311,10 +1387,13 @@ To handle these queue groups on two nodes:
sudo gitlab-rake gitlab:sidekiq:migrate_jobs:retry gitlab:sidekiq:migrate_jobs:schedule gitlab:sidekiq:migrate_jobs:queued
```
-NOTE:
+{{< alert type="note" >}}
+
It is important to run the Rake task immediately after reconfiguring GitLab.
After reconfiguring GitLab, existing jobs are not processed until the Rake task starts to migrate the jobs.
+{{< /alert >}}
+
## Reverting to Basic Search
Sometimes there may be issues with your Elasticsearch index data and as such
diff --git a/doc/integration/advanced_search/elasticsearch_troubleshooting.md b/doc/integration/advanced_search/elasticsearch_troubleshooting.md
index d11b7f06bd1c8da051d4500ba821a79bcdf871cd..5c16c7a02f275553702b19dd061c80cf970634f8 100644
--- a/doc/integration/advanced_search/elasticsearch_troubleshooting.md
+++ b/doc/integration/advanced_search/elasticsearch_troubleshooting.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../elasticsearch/troubleshooting/_index.md'
-remove_date: '2025-03-09'
+redirect_to: ../elasticsearch/troubleshooting/_index.md
+remove_date: "2025-03-09"
---
<!-- markdownlint-disable -->
diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md
index 1914ab972337943513c6289e951979f08459e788..cd332834910399c44d6b877a930593fbf6840ddf 100644
--- a/doc/integration/akismet.md
+++ b/doc/integration/akismet.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Akismet
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab uses [Akismet](https://akismet.com/) to prevent the creation of
spam issues on public projects. Issues created through the web UI or the API can be submitted to
@@ -19,17 +22,23 @@ Detected spam is rejected, and an entry is added in the **Spam log** section of
Privacy note: GitLab submits the user's IP and user agent to Akismet.
-NOTE:
+{{< alert type="note" >}}
+
GitLab submits all issues to Akismet.
+{{< /alert >}}
+
Akismet configuration is available to users on GitLab Self-Managed. Akismet is already enabled on
GitLab SaaS (GitLab.com), where its configuration and management are handled by GitLab Inc.
## Configure Akismet
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To use Akismet:
@@ -48,9 +57,12 @@ To use Akismet:
## Train the Akismet filter
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To better differentiate between spam and ham, you can train the Akismet
filter whenever there is a false positive or false negative.
diff --git a/doc/integration/alicloud.md b/doc/integration/alicloud.md
index 256670f1ccb793fcda8e99c8331b03331b7e5c78..79c5c35cbf4f236e0bf5c83d2d4e19ffb659ec98 100644
--- a/doc/integration/alicloud.md
+++ b/doc/integration/alicloud.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use AliCloud as an OmniAuth authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
You can enable the AliCloud OAuth 2.0 OmniAuth provider and sign in to
GitLab using your AliCloud account.
diff --git a/doc/integration/arkose.md b/doc/integration/arkose.md
index fd295a25972f121f70fe6beac412581fcb955d16..337a1791c159e52b0494e87dc645abf91462328a 100644
--- a/doc/integration/arkose.md
+++ b/doc/integration/arkose.md
@@ -5,12 +5,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Arkose Protect
---
-WARNING:
+{{< alert type="warning" >}}
+
Arkose Protect is used on GitLab.com and is not supported for GitLab Self-Managed
instances. The following documents the internal requirements for maintaining
Arkose Protect on GitLab.com. While this feature is theoretically usable in GitLab Self-Managed instances, it
is not recommended at the moment.
+{{< /alert >}}
+
GitLab integrates [Arkose Protect](https://www.arkoselabs.com/platform/) to guard against
malicious users from creating accounts.
@@ -117,7 +120,11 @@ This job is performed by the `Arkose::BlockedUsersReportWorker` class.
## Test your integration
-> - Requesting specific behaviors with Data Exchange [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435275) in GitLab 16.8 [with a flag](../administration/feature_flags.md) named `arkose_labs_signup_data_exchange`. Disabled by default.
+{{< history >}}
+
+- Requesting specific behaviors with Data Exchange [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435275) in GitLab 16.8 [with a flag](../administration/feature_flags.md) named `arkose_labs_signup_data_exchange`. Disabled by default.
+
+{{< /history >}}
In staging and development environments only, you can suppress a challenge, or force one to appear.
You can use this feature if you want to receive a specific risk band.
diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md
index d278c3fd09aa2dff8e8fe14c96cb1935cc0005c1..99b4a354228923b2ff03c02bd6cc3401cba498bc 100644
--- a/doc/integration/auth0.md
+++ b/doc/integration/auth0.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Auth0 as an OAuth 2.0 authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an
application.
diff --git a/doc/integration/azure.md b/doc/integration/azure.md
index 367e3e4905c39b53ad02b8a06a91bf0167a924e5..179443c91a755179dde35a4fb42d0f3fff81026a 100644
--- a/doc/integration/azure.md
+++ b/doc/integration/azure.md
@@ -5,18 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Microsoft Azure as an OAuth 2.0 authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can enable the Microsoft Azure OAuth 2.0 OmniAuth provider and sign in to
GitLab with your Microsoft Azure credentials.
-NOTE:
+{{< alert type="note" >}}
+
If you're integrating GitLab with Azure/Entra ID for the first time,
configure the [OpenID Connect protocol](../administration/auth/oidc.md#configure-microsoft-azure),
which uses the Microsoft identity platform (v2.0) endpoint.
+{{< /alert >}}
+
## Migrate to Generic OpenID Connect configuration
In GitLab 17.0 and later, instances using `azure_oauth2` must migrate to the Generic OpenID Connect configuration. For more information, see [Migrating to the OpenID Connect protocol](../administration/auth/oidc.md#migrate-to-generic-openid-connect-configuration).
@@ -55,11 +61,14 @@ Alternatively, add the `User.Read.All` application permission.
## Enable Microsoft OAuth in GitLab
-NOTE:
+{{< alert type="note" >}}
+
For new projects, you should use the
[OpenID Connect protocol](../administration/auth/oidc.md#configure-microsoft-azure),
which uses the Microsoft identity platform (v2.0) endpoint.
+{{< /alert >}}
+
1. On your GitLab server, open the configuration file.
- For Linux package installations:
diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md
index a9388ffc1ed252b5b1aef375689ea3a4a9641ae3..e7e23f264a8946a4faf1c37542314a439ed549c2 100644
--- a/doc/integration/bitbucket.md
+++ b/doc/integration/bitbucket.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Integrate your GitLab server with Bitbucket Cloud
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can set up Bitbucket.org as an OAuth 2.0 provider to use your Bitbucket.org
account credentials to sign in to GitLab. You can also import your projects from
@@ -43,11 +46,14 @@ you to use.
Leaving this field empty
results in an `Invalid redirect_uri` message.
- WARNING:
+ {{< alert type="warning" >}}
+
To help prevent an [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/)
vulnerability in which users' GitLab accounts could be compromised, append `/users/auth`
to the end of the Bitbucket authorization callback URL.
+ {{< /alert >}}
+
- **URL:** The URL to your GitLab installation, such as `https://gitlab.example.com`.
1. Grant at least the following permissions:
@@ -125,9 +131,12 @@ sign-in form. Select the icon to begin the authentication process. Bitbucket ask
the user to sign in and authorize the GitLab application. If successful, the user
is returned to GitLab and signed in.
-NOTE:
+{{< alert type="note" >}}
+
For multi-node architectures, the Bitbucket provider configuration must also be included on the Sidekiq nodes to be able to import projects.
+{{< /alert >}}
+
## Bitbucket project import
After the above configuration is set up, you can use Bitbucket to sign in to
diff --git a/doc/integration/clickhouse.md b/doc/integration/clickhouse.md
index 9e3f6785c34bbcc5262f350a10d020442679b3dc..cbe2c08d7878e3374846d2c61d696ff836a6dfa3 100644
--- a/doc/integration/clickhouse.md
+++ b/doc/integration/clickhouse.md
@@ -5,8 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: ClickHouse integration guidelines
---
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
This feature is an [experiment](../policy/development_stages_support.md).
@@ -30,9 +33,12 @@ When you run ClickHouse on a hosted server, various data points might impact the
of builds that run on your instance each month, the selected hardware, the data center choice to host ClickHouse, and more.
Regardless, the cost should not be significant.
-NOTE:
+{{< alert type="note" >}}
+
ClickHouse is a secondary data store for GitLab. Only specific data is stored in ClickHouse for analytics purposes.
+{{< /alert >}}
+
To create necessary user and database objects:
1. Generate a secure password and save it.
@@ -50,9 +56,9 @@ To create necessary user and database objects:
### Configure the GitLab connection to ClickHouse
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package
+{{< tab title="Linux package" >}}
To provide GitLab with ClickHouse credentials:
@@ -71,7 +77,9 @@ To provide GitLab with ClickHouse credentials:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Save the ClickHouse password as a Kubernetes Secret:
@@ -106,7 +114,9 @@ To provide GitLab with ClickHouse credentials:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To verify that your connection is set up successfully:
diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md
index eefc4d039bba55466bada84fe7fc87e80c575a74..7d67bbc26d1dda5d3b850f56e5889f5ab143898f 100644
--- a/doc/integration/datadog.md
+++ b/doc/integration/datadog.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Datadog
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Datadog integration enables you to connect your GitLab projects to [Datadog](https://www.datadoghq.com/),
synchronizing repository metadata to enrich your Datadog telemetry, have Datadog comment on Merge Requests, and send CI/CD pipeline and job information to Datadog.
@@ -42,10 +45,13 @@ failures and performance issues.
For more information, see the [Datadog CI Visibility documentation](https://docs.datadoghq.com/continuous_integration/pipelines/?tab=gitlab).
-WARNING:
+{{< alert type="warning" >}}
+
Datadog CI Visibility is priced per committer. Using this feature might affect your Datadog bill.
For details, see the [Datadog pricing page](https://www.datadoghq.com/pricing/?product=ci-pipeline-visibility#products).
+{{< /alert >}}
+
This feature is based on [Webhooks](../user/project/integrations/webhooks.md),
and only requires configuration in GitLab:
diff --git a/doc/integration/diffblue_cover.md b/doc/integration/diffblue_cover.md
index 2a3d888ae5459a82dfc33a424a4d0e6fc59ac000..27225c23520907b6f84e2d978ef183577b898029 100644
--- a/doc/integration/diffblue_cover.md
+++ b/doc/integration/diffblue_cover.md
@@ -1,16 +1,17 @@
---
stage: Verify
group: Pipeline Execution
-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"
-description: >-
- How to configure the Diffblue Cover GitLab integration - Cover Pipeline for
- GitLab
+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
+description: How to configure the Diffblue Cover GitLab integration - Cover Pipeline for GitLab
title: Diffblue Cover
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can integrate the [Diffblue Cover](https://www.diffblue.com/) reinforcement learning AI tool into your CI/CD pipelines, to automatically write and maintain Java unit tests for your GitLab projects.
The Diffblue Cover Pipeline for GitLab integration allows you to automatically:
@@ -46,10 +47,13 @@ To integrate Diffblue Cover into your pipeline:
In general, use a GitLab [project access token](../user/project/settings/project_access_tokens.md) with the `Developer` role, plus `api` and `write_repository` scopes.
If necessary you can use a [group access token](../user/group/settings/group_access_tokens.md) or a [personal access token](../user/profile/personal_access_tokens.md), again with the `Developer` role, plus `api` and `write_repository` scopes.
- NOTE:
+ {{< alert type="note" >}}
+
Using an access token with excessive permissions is a security risk.
If you use a Personal access token, consider creating a dedicated user with access limited to just the project, minimizing the impact of the token being leaked.
+ {{< /alert >}}
+
1. Select **Save changes**.
Your Diffblue Cover integration is now <mark style="color:green;">**Active**</mark> and ready for use in your project.
@@ -61,10 +65,13 @@ Here we'll create a merge request pipeline for the project that will download th
1. Copy the contents of the [`Diffblue-Cover.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Diffblue-Cover.gitlab-ci.yml)
into your project's `.gitlab-ci.yml` file.
- NOTE:
- When using the Diffblue Cover pipeline template with your own project and existing pipeline file, add the Diffblue template content to your file and modify as needed.
+ {{< alert type="note" >}}
+
+When using the Diffblue Cover pipeline template with your own project and existing pipeline file, add the Diffblue template content to your file and modify as needed.
For more information, see [Cover Pipeline for GitLab](https://docs.diffblue.com/features/cover-pipeline/cover-pipeline-for-gitlab) in the Diffblue documentation.
+ {{< /alert >}}
+
1. Enter a commit message.
1. Enter a new **Branch** name. For example, `add-diffblue-cover-pipeline`.
1. Select **Start a new merge request with these changes**.
diff --git a/doc/integration/elasticsearch/troubleshooting/_index.md b/doc/integration/elasticsearch/troubleshooting/_index.md
index 204e66b22d99c52e199b29b6c132b84f01d054cd..05acd4076a725931956eed2d92135e9cddf9c585 100644
--- a/doc/integration/elasticsearch/troubleshooting/_index.md
+++ b/doc/integration/elasticsearch/troubleshooting/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Elasticsearch
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with Elasticsearch, you might encounter issues with:
diff --git a/doc/integration/elasticsearch/troubleshooting/access.md b/doc/integration/elasticsearch/troubleshooting/access.md
index f94cb0aa97e523375f2c4a97f64861135f2c6e6f..743fd32e961f4d8f0f63988062fa92df896bb79c 100644
--- a/doc/integration/elasticsearch/troubleshooting/access.md
+++ b/doc/integration/elasticsearch/troubleshooting/access.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Elasticsearch access
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with Elasticsearch access, you might encounter the following issues.
diff --git a/doc/integration/elasticsearch/troubleshooting/indexing.md b/doc/integration/elasticsearch/troubleshooting/indexing.md
index 4de42d81557b3ffdd162c824beefd9764abfd600..518baca488df53b225cfbb2b459f08992a29b76c 100644
--- a/doc/integration/elasticsearch/troubleshooting/indexing.md
+++ b/doc/integration/elasticsearch/troubleshooting/indexing.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Elasticsearch indexing
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with Elasticsearch indexing, you might encounter the following issues.
@@ -82,9 +85,12 @@ If the results:
- Sync up, check that you are using [supported syntax](../../../user/search/advanced_search.md#syntax). Advanced search does not support [exact substring matching](https://gitlab.com/gitlab-org/gitlab/-/issues/325234).
- Do not match up, this indicates a problem with the documents generated from the project. It is best to [re-index that project](../../advanced_search/elasticsearch.md#indexing-a-range-of-projects-or-a-specific-project).
-NOTE:
+{{< alert type="note" >}}
+
The above instructions are not to be used for scenarios that only index a [subset of namespaces](../../advanced_search/elasticsearch.md#limit-the-amount-of-namespace-and-project-data-to-index).
+{{< /alert >}}
+
See [Elasticsearch Index Scopes](../../advanced_search/elasticsearch.md#advanced-search-index-scopes) for more information on searching for specific types of data.
## No search results after switching Elasticsearch servers
@@ -159,16 +165,18 @@ while the indexing is running.
If you are sure you've read the above caveats and want to proceed, then you
should run the following Rake task to recreate the entire index from scratch.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
# WARNING: DO NOT RUN THIS UNTIL YOU READ THE DESCRIPTION ABOVE
sudo gitlab-rake gitlab:elastic:index
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
# WARNING: DO NOT RUN THIS UNTIL YOU READ THE DESCRIPTION ABOVE
@@ -176,7 +184,9 @@ cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:index
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Improve Elasticsearch performance
diff --git a/doc/integration/elasticsearch/troubleshooting/migrations.md b/doc/integration/elasticsearch/troubleshooting/migrations.md
index d4594fd75fb687f9af41f9a008a5d57096790a19..4e988677c358d1f5ab94b437aa5c7ccb165c38e1 100644
--- a/doc/integration/elasticsearch/troubleshooting/migrations.md
+++ b/doc/integration/elasticsearch/troubleshooting/migrations.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Elasticsearch migrations
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with Elasticsearch migrations, you might encounter the following issues.
@@ -40,9 +43,12 @@ with the IP address of your Elasticsearch host.
For a single-node Elasticsearch cluster, the functional cluster health status is yellow (never green). The reason is that the primary shard is allocated, but replicas cannot be as no other node to which Elasticsearch can assign a replica exists. This also applies if you are using the [Amazon OpenSearch](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/aes-handling-errors.html#aes-handling-errors-yellow-cluster-status) service.
-WARNING:
+{{< alert type="warning" >}}
+
Setting the number of replicas to `0` is discouraged (this is not allowed in the GitLab Elasticsearch Integration menu). If you are planning to add more Elasticsearch nodes (for a total of more than 1 Elasticsearch) the number of replicas needs to be set to an integer value larger than `0`. Failure to do so results in lack of redundancy (losing one node corrupts the index).
+{{< /alert >}}
+
If you want to have a green status for your single-node Elasticsearch cluster, understand the risks and run the following query to set the number of replicas to `0`. The cluster no longer tries to create any shard replicas.
```shell
diff --git a/doc/integration/exact_code_search/zoekt.md b/doc/integration/exact_code_search/zoekt.md
index fb925688e62a13ed1c42ea5c4dfc0456fb9375c3..f0e280f1d3c4ca67c28349eaa65e4d96ff41e2a4 100644
--- a/doc/integration/exact_code_search/zoekt.md
+++ b/doc/integration/exact_code_search/zoekt.md
@@ -5,19 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Zoekt
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 15.9 [with flags](../../administration/feature_flags.md) named `index_code_with_zoekt` and `search_code_with_zoekt`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/388519) in GitLab 16.6.
-> - Feature flags `index_code_with_zoekt` and `search_code_with_zoekt` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148378) in GitLab 17.1.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 15.9 [with flags](../../administration/feature_flags.md) named `index_code_with_zoekt` and `search_code_with_zoekt`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/388519) in GitLab 16.6.
+- Feature flags `index_code_with_zoekt` and `search_code_with_zoekt` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148378) in GitLab 17.1.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature is in [beta](../../policy/development_stages_support.md#beta) and subject to change without notice.
For more information, see [epic 9404](https://gitlab.com/groups/gitlab-org/-/epics/9404).
+{{< /alert >}}
+
Zoekt is an open-source search engine designed specifically to search for code.
With this integration, you can use [exact code search](../../user/search/exact_code_search.md)
diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md
index 0b11b259f200171de46326ca097e533d1f2de98a..977a92345358240fa71d80c1c8118700b0f58bb1 100644
--- a/doc/integration/external-issue-tracker.md
+++ b/doc/integration/external-issue-tracker.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: External issue trackers
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab has its own [issue tracker](../user/project/issues/_index.md),
but you can also configure an external issue tracker per GitLab project.
diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md
index fc91f382b1bad79fd824464bf3d0c75f55f95ad1..468083bce309f370e9fe4059920f0cda568b28ae 100644
--- a/doc/integration/facebook.md
+++ b/doc/integration/facebook.md
@@ -1,15 +1,18 @@
---
+redirect_to: omniauth.md#supported-providers
+remove_date: "2025-01-29"
stage: Software Supply Chain Security
group: Authentication
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
-remove_date: '2025-01-29'
-redirect_to: 'omniauth.md#supported-providers'
title: Use Facebook as an OAuth 2.0 authentication provider (removed)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/416000) in GitLab 16.2
and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/416281) in 17.0.
diff --git a/doc/integration/github.md b/doc/integration/github.md
index 165bbb49fa60756c8d88d0d44b16f69e89bd4bda..5779d7d12e1e989e0e6182ae7163603f7afbeac8 100644
--- a/doc/integration/github.md
+++ b/doc/integration/github.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use GitHub as an OAuth 2.0 authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can integrate your GitLab instance with GitHub.com and GitHub Enterprise.
You can import projects from GitHub, or sign in to GitLab
diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md
index d1d875f7fc2a342acbef60205542834b9ef57907..2932cf773fbd79c0212ae4d7fdebb65ac2def4db 100644
--- a/doc/integration/gitlab.md
+++ b/doc/integration/gitlab.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Integrate your server with GitLab.com
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account.
@@ -107,10 +110,13 @@ GitLab.com generates an application ID and secret key for you to use.
args: { "client_options": { "site": 'https://gitlab.example.com' } }
```
- NOTE:
- In GitLab 15.1 and earlier, the `site` parameter requires an `/api/v4` suffix.
+ {{< alert type="note" >}}
+
+In GitLab 15.1 and earlier, the `site` parameter requires an `/api/v4` suffix.
We recommend you drop this suffix after you upgrade to GitLab 15.2 or later.
+ {{< /alert >}}
+
1. Change `'YOUR_APP_ID'` to the Application ID from the GitLab.com application page.
1. Change `'YOUR_APP_SECRET'` to the secret from the GitLab.com application page.
1. Save the configuration file.
@@ -126,9 +132,13 @@ signed in.
## Reduce access privileges on sign in
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337663) in GitLab 14.8 [with a flag](../administration/feature_flags.md) named `omniauth_login_minimal_scopes`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/351331) in GitLab 14.9.
-> - [Feature flag `omniauth_login_minimal_scopes`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83453) removed in GitLab 15.2
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337663) in GitLab 14.8 [with a flag](../administration/feature_flags.md) named `omniauth_login_minimal_scopes`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/351331) in GitLab 14.9.
+- [Feature flag `omniauth_login_minimal_scopes`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83453) removed in GitLab 15.2
+
+{{< /history >}}
If you use a GitLab instance for authentication, you can reduce access rights when an OAuth application is used for sign in.
diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md
index da33bda1d49ef7d7f7200d7784cce09bde125a2c..a80a86f651f796547a6d635fcfa69b2229ce833d 100644
--- a/doc/integration/gitpod.md
+++ b/doc/integration/gitpod.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Remote Development
-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"
-description: "Use Gitpod to build and configure prebuilt development environments for your GitLab project."
+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
+description: Use Gitpod to build and configure prebuilt development environments for your GitLab project.
title: Gitpod
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
With [Gitpod](https://www.gitpod.io/), you can describe your development environment as code to get fully
set up, compiled, and tested development environments for any GitLab project. The development
@@ -40,9 +43,12 @@ With the Gitpod integration enabled for your GitLab instance, to enable it for y
## Configure a GitLab Self-Managed instance
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
For GitLab Self-Managed, a GitLab administrator must:
diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md
index 1128ff18e233791775a7634a17dc6a1f1f1028ac..8e2d9b161396ef3b3dbcc20b213e80f5195f8d38 100644
--- a/doc/integration/gmail_action_buttons_for_gitlab.md
+++ b/doc/integration/gmail_action_buttons_for_gitlab.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Gmail actions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview).
When you configure this integration, emails that require an action are marked in Gmail.
diff --git a/doc/integration/google.md b/doc/integration/google.md
index c4d2507aa1d230ea7fbacede4a56cdc779b1c748..c7442952e5c9bd6cd343234d25a2560243d30b46 100644
--- a/doc/integration/google.md
+++ b/doc/integration/google.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Google OAuth 2.0 as an OAuth 2.0 authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To enable the Google OAuth 2.0 OmniAuth provider you must register your application
with Google. Google generates a client ID and secret key for you to use.
diff --git a/doc/integration/google_cloud_iam.md b/doc/integration/google_cloud_iam.md
index f1d706ed1beb1a814ef93b2bfb9f420073d70a65..f71e01c341ed30dc9f663396f1f7f1030f1fb3f6 100644
--- a/doc/integration/google_cloud_iam.md
+++ b/doc/integration/google_cloud_iam.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Google Cloud Workload Identity Federation and IAM policies
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141127) in GitLab 16.10 [with a flag](../administration/feature_flags.md) named `google_cloud_support_feature_flag`.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141127) in GitLab 16.10 [with a flag](../administration/feature_flags.md) named `google_cloud_support_feature_flag`.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+
+{{< /history >}}
To use Google Cloud integrations like the
[Google Artifact Management integration](../user/project/integrations/google_artifact_management.md),
@@ -93,11 +100,14 @@ To use the GitLab UI to set up the Workload Identity Federation:
1. Locate the Google Cloud IAM integration and select **Configure**.
1. Select **Guided setup** and follow the instructions.
-NOTE:
+{{< alert type="note" >}}
+
Due to a known issue, the fields in the page for the Google Cloud IAM integration might not
populate after you run the script in the guided setup. If the fields are empty, refresh the page.
For more information, see [issue 448831](https://gitlab.com/gitlab-org/gitlab/-/issues/448831).
+{{< /alert >}}
+
### With the Google Cloud CLI
Prerequisites:
@@ -255,7 +265,7 @@ artifacts to the Google Artifact Registry from the GitLab project `gitlab-org/my
1. In the **Display name** column, select your workload identity pool.
1. In the **Providers** section, next to the workload identity provider you want to edit,
- select **Edit** (**{pencil}**) to open **Provider details**.
+ select **Edit** ({{< icon name="pencil" >}}) to open **Provider details**.
1. In the **Attribute mapping** section, select **Add mapping**.
1. In the **Google N** text box, enter:
diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md
index 5f337445cc39302b217f7566a86487b81f5d2fd4..6fd8f3c013aca08f701c4ea893b984016b10fdc9 100644
--- a/doc/integration/jenkins.md
+++ b/doc/integration/jenkins.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Jenkins
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to GitLab Free in 13.7.
diff --git a/doc/integration/jira/_index.md b/doc/integration/jira/_index.md
index 855c398b7462bdc3578faebbc2ae75b0fbe27056..700bf0206637e337bd202a0a19481bde06803cbc 100644
--- a/doc/integration/jira/_index.md
+++ b/doc/integration/jira/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Jira
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can [import your Jira issues to GitLab](../../user/project/import/jira.md).
If you want to continue to use Jira, you can integrate Jira with GitLab instead.
@@ -19,7 +22,11 @@ GitLab offers two Jira integrations. You can use one or both integrations
### Jira issues integration
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166555) feature name to Jira issues integration in GitLab 17.6.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166555) feature name to Jira issues integration in GitLab 17.6.
+
+{{< /history >}}
You can use the [Jira issues integration](configure.md) developed by GitLab with
Jira Cloud, Jira Data Center, or Jira Server. With this integration, you can:
@@ -43,16 +50,16 @@ This table shows the features available with the Jira issues integration and the
| Feature | Jira issues integration | Jira development panel |
|-|-|-|
-| Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created. | **{check-circle}** Yes | **{dotted-circle}** No |
-| Mention a Jira issue ID in GitLab, and the Jira issue shows the GitLab issue or merge request. | **{check-circle}** Yes, a Jira comment with the GitLab issue or merge request title links to GitLab. The first mention is also added to **Web links** in the Jira issue. | **{check-circle}** Yes, in the Jira issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). |
-| Mention a Jira issue ID in a GitLab commit, and the Jira issue shows the commit message. | **{check-circle}** Yes, the entire commit message is displayed in the Jira issue as a comment and in **Web links**. Each message links back to the commit in GitLab. | **{check-circle}** Yes, in the Jira issue's development panel. A custom comment is possible with [Jira Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). |
-| Mention a Jira issue ID in a GitLab branch name, and the Jira issue shows the branch name. | **{dotted-circle}** No | **{check-circle}** Yes, in the Jira issue's development panel. |
-| Add time tracking to a Jira issue. | **{dotted-circle}** No | **{check-circle}** Yes, with Jira Smart Commits. |
-| Use a GitLab commit or merge request to transition a Jira issue. |**{check-circle}** Yes, only a single transition. Typically used to close the Jira issue. | **{check-circle}** Yes, transition the Jira issue to any state with Jira Smart Commits. |
-| [View a list of Jira issues](configure.md#view-jira-issues). | **{check-circle}** Yes | **{dotted-circle}** No |
-| [Create a Jira issue for a vulnerability](configure.md#create-a-jira-issue-for-a-vulnerability). | **{check-circle}** Yes | **{dotted-circle}** No |
-| Create a GitLab branch from a Jira issue. | **{dotted-circle}** No | **{check-circle}** Yes, in the Jira issue's development panel. |
-| Mention a Jira issue ID in a GitLab merge request, branch name, or any of the last 5,000 commits to the branch after the last successful deployment to the environment to sync a GitLab deployment to a Jira issue. | **{dotted-circle}** No | **{check-circle}** Yes, in the Jira issue's development panel. |
+| Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created. | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| Mention a Jira issue ID in GitLab, and the Jira issue shows the GitLab issue or merge request. | {{< icon name="check-circle" >}} Yes, a Jira comment with the GitLab issue or merge request title links to GitLab. The first mention is also added to **Web links** in the Jira issue. | {{< icon name="check-circle" >}} Yes, in the Jira issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). |
+| Mention a Jira issue ID in a GitLab commit, and the Jira issue shows the commit message. | {{< icon name="check-circle" >}} Yes, the entire commit message is displayed in the Jira issue as a comment and in **Web links**. Each message links back to the commit in GitLab. | {{< icon name="check-circle" >}} Yes, in the Jira issue's development panel. A custom comment is possible with [Jira Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). |
+| Mention a Jira issue ID in a GitLab branch name, and the Jira issue shows the branch name. | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes, in the Jira issue's development panel. |
+| Add time tracking to a Jira issue. | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes, with Jira Smart Commits. |
+| Use a GitLab commit or merge request to transition a Jira issue. |{{< icon name="check-circle" >}} Yes, only a single transition. Typically used to close the Jira issue. | {{< icon name="check-circle" >}} Yes, transition the Jira issue to any state with Jira Smart Commits. |
+| [View a list of Jira issues](configure.md#view-jira-issues). | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [Create a Jira issue for a vulnerability](configure.md#create-a-jira-issue-for-a-vulnerability). | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| Create a GitLab branch from a Jira issue. | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes, in the Jira issue's development panel. |
+| Mention a Jira issue ID in a GitLab merge request, branch name, or any of the last 5,000 commits to the branch after the last successful deployment to the environment to sync a GitLab deployment to a Jira issue. | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes, in the Jira issue's development panel. |
## Privacy considerations
diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md
index 8fd4d2f5105aa4d287ebdaddcdee98e4aa5e3d09..e81e932b32c82beef4c9ad54b34454eef1a240eb 100644
--- a/doc/integration/jira/configure.md
+++ b/doc/integration/jira/configure.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Jira issues integration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> - Name [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166555) to Jira issues integration in GitLab 17.6.
@@ -17,12 +20,16 @@ The supported Jira versions are `6.x`, `7.x`, `8.x`, and `9.x`.
## Configure the integration
-> - Authentication with Jira personal access tokens [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8222) in GitLab 16.0.
-> - **Jira issues** and **Jira issues for vulnerabilities** sections [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440430) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `jira_multiple_project_keys`. Disabled by default.
-> - **Jira issues** and **Jira issues for vulnerabilities** sections [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151753) in GitLab 17.0. Feature flag `jira_multiple_project_keys` removed.
-> - **Enable Jira issues** checkbox [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149055) to **View Jira issues** in GitLab 17.0.
-> - **Enable Jira issue creation from vulnerabilities** checkbox [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149055) to **Create Jira issues for vulnerabilities** in GitLab 17.0.
-> - **Customize Jira issues** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/478824) in GitLab 17.5.
+{{< history >}}
+
+- Authentication with Jira personal access tokens [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8222) in GitLab 16.0.
+- **Jira issues** and **Jira issues for vulnerabilities** sections [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440430) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `jira_multiple_project_keys`. Disabled by default.
+- **Jira issues** and **Jira issues for vulnerabilities** sections [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151753) in GitLab 17.0. Feature flag `jira_multiple_project_keys` removed.
+- **Enable Jira issues** checkbox [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149055) to **View Jira issues** in GitLab 17.0.
+- **Enable Jira issue creation from vulnerabilities** checkbox [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149055) to **Create Jira issues for vulnerabilities** in GitLab 17.0.
+- **Customize Jira issues** setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/478824) in GitLab 17.5.
+
+{{< /history >}}
Prerequisites:
@@ -79,21 +86,27 @@ To configure your project settings in GitLab:
in the **Jira issues** section:
1. Select the **View Jira issues** checkbox.
- WARNING:
+ {{< alert type="warning" >}}
+
When you enable this setting, all users with access to your GitLab project
can view all issues from the Jira projects you've specified.
+ {{< /alert >}}
+
1. Enter one or more Jira project keys.
Leave blank to include all available keys.
1. Optional. To [create Jira issues for vulnerabilities](#create-a-jira-issue-for-a-vulnerability),
in the **Jira issues for vulnerabilities** section:
1. Select the **Create Jira issues for vulnerabilities** checkbox.
- NOTE:
+ {{< alert type="note" >}}
+
You can enable this setting only for individual projects and groups.
+ {{< /alert >}}
+
1. Enter a Jira project key.
- 1. Select **Fetch issue types for this project key** (**{retry}**),
+ 1. Select **Fetch issue types for this project key** ({{< icon name="retry" >}}),
then select the type of Jira issues to create.
1. Optional. Select the **Customize Jira issues** checkbox to be able to review, modify, or add details
to a Jira issue when it's created for a vulnerability.
@@ -102,12 +115,19 @@ To configure your project settings in GitLab:
## View Jira issues
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
-> - Enabling Jira issues for a group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325715) in GitLab 16.9.
-> - Viewing issues from multiple Jira projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440430) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `jira_multiple_project_keys`. Disabled by default.
-> - Viewing issues from multiple Jira projects [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151753) in GitLab 17.0. Feature flag `jira_multiple_project_keys` removed.
+{{< /details >}}
+
+{{< history >}}
+
+- Enabling Jira issues for a group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325715) in GitLab 16.9.
+- Viewing issues from multiple Jira projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440430) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `jira_multiple_project_keys`. Disabled by default.
+- Viewing issues from multiple Jira projects [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151753) in GitLab 17.0. Feature flag `jira_multiple_project_keys` removed.
+
+{{< /history >}}
Prerequisites:
@@ -133,11 +153,18 @@ Issues are grouped into the following tabs based on their
### Filter Jira issues
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
-> - Filtering Jira issues by project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440430) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `jira_multiple_project_keys`. Disabled by default.
-> - Filtering Jira issues by project [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151753) in GitLab 17.0. Feature flag `jira_multiple_project_keys` removed.
+{{< history >}}
+
+- Filtering Jira issues by project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440430) in GitLab 16.10 [with a flag](../../administration/feature_flags.md) named `jira_multiple_project_keys`. Disabled by default.
+- Filtering Jira issues by project [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151753) in GitLab 17.0. Feature flag `jira_multiple_project_keys` removed.
+
+{{< /history >}}
Prerequisites:
@@ -162,8 +189,11 @@ You can also filter the issues by:
## Create a Jira issue for a vulnerability
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
Prerequisites:
diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md
index 523cead97fb4d507cc2cce88cc1b0889e77765a6..b69c193ead717e07772dba6b7841cd799f966678 100644
--- a/doc/integration/jira/connect-app.md
+++ b/doc/integration/jira/connect-app.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab for Jira Cloud app
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This page contains user documentation for the GitLab for Jira Cloud app. For administrator documentation, see [GitLab for Jira Cloud app administration](../../administration/settings/jira_cloud_app.md).
+{{< /alert >}}
+
With the [GitLab for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?tab=overview&hosting=cloud) app, you can connect GitLab and Jira Cloud to sync development information in real time. You can view this information in the [Jira development panel](development_panel.md).
You can use the GitLab for Jira Cloud app to link top-level groups or subgroups. It's not possible to directly link projects or personal namespaces.
@@ -43,9 +49,12 @@ After you link a group, the following GitLab data is synced to Jira for all proj
## Install the GitLab for Jira Cloud app
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Prerequisites:
@@ -68,11 +77,18 @@ For an overview, see
## Configure the GitLab for Jira Cloud app
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
-> - **Add namespace** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/331432) to **Link groups** in GitLab 16.1.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- **Add namespace** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/331432) to **Link groups** in GitLab 16.1.
+
+{{< /history >}}
Prerequisites:
@@ -94,10 +110,13 @@ To configure the GitLab for Jira Cloud app:
1. Enter your **GitLab instance URL**, then select **Save**.
1. Select **Sign in to GitLab**.
- NOTE:
- [Enterprise users](../../user/enterprise_user/_index.md) with [disabled password authentication for their group](../../user/group/saml_sso/_index.md#disable-password-authentication-for-enterprise-users)
+ {{< alert type="note" >}}
+
+[Enterprise users](../../user/enterprise_user/_index.md) with [disabled password authentication for their group](../../user/group/saml_sso/_index.md#disable-password-authentication-for-enterprise-users)
must first sign in to GitLab with their group's single sign-on URL.
+ {{< /alert >}}
+
1. Select **Authorize**. A list of groups is now visible.
1. Select **Link groups**.
1. To link to a group, select **Link**.
@@ -113,12 +132,19 @@ After you link to a GitLab group:
## Configure Jira Service Management
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460663) in GitLab 17.2 [with a flag](../../administration/feature_flags.md) named `enable_jira_connect_configuration`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467117) in GitLab 17.4. Feature flag `enable_jira_connect_configuration` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460663) in GitLab 17.2 [with a flag](../../administration/feature_flags.md) named `enable_jira_connect_configuration`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/467117) in GitLab 17.4. Feature flag `enable_jira_connect_configuration` removed.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature was added as a community contribution and is developed and maintained by the GitLab community only.
+{{< /alert >}}
+
Prerequisites:
- The GitLab for Jira Cloud app must be [installed](#install-the-gitlab-for-jira-cloud-app).
@@ -152,15 +178,25 @@ For more information about deployment tracking in Jira, see [Set up deployment t
### Set up deployment gating with GitLab
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/473774) in GitLab 17.6.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/473774) in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature was added as a community contribution and is developed and maintained by the GitLab community only.
+{{< /alert >}}
+
You can set up deployment gating to bring change requests from GitLab to Jira Service Management for approval.
With deployment gating, any GitLab deployments to your selected environments are automatically sent
to Jira Service Management and are only deployed if they're approved.
diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md
index 5d98d0c017424125f723e9bbcb4e382ee57326c8..100ca67a6652c36c96f8029a120e586669e953cc 100644
--- a/doc/integration/jira/development_panel.md
+++ b/doc/integration/jira/development_panel.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Jira development panel
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use the Jira development panel to view GitLab activity for a Jira issue directly in Jira.
To set up the Jira development panel:
@@ -20,25 +23,29 @@ For an overview, see [Jira development panel integration](https://www.youtube.co
## Feature availability
-> - Ability to delete branches [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148712) in GitLab 17.1 [with a flag](../../administration/feature_flags.md) named `jira_connect_remove_branches`. Disabled by default.
-> - Ability to delete branches made [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158224) in GitLab 17.2. Feature flag `jira_connect_remove_branches` removed.
+{{< history >}}
+
+- Ability to delete branches [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148712) in GitLab 17.1 [with a flag](../../administration/feature_flags.md) named `jira_connect_remove_branches`. Disabled by default.
+- Ability to delete branches made [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158224) in GitLab 17.2. Feature flag `jira_connect_remove_branches` removed.
+
+{{< /history >}}
This table shows the features available with the Jira DVCS connector and the GitLab for Jira Cloud app:
| Feature | Jira DVCS connector | GitLab for Jira Cloud app |
|:-------------------------------------|:-----------------------|:--------------------------|
-| Smart Commits | **{check-circle}** Yes | **{check-circle}** Yes |
-| Sync merge requests | **{check-circle}** Yes | **{check-circle}** Yes |
-| Sync branches | **{check-circle}** Yes | **{check-circle}** Yes |
-| Sync commits | **{check-circle}** Yes | **{check-circle}** Yes |
-| Sync existing data | **{check-circle}** Yes | **{check-circle}** Yes (see [GitLab data synced to Jira](connect-app.md#gitlab-data-synced-to-jira)) |
-| Sync builds | **{dotted-circle}** No | **{check-circle}** Yes |
-| Sync deployments | **{dotted-circle}** No | **{check-circle}** Yes |
-| Sync feature flags | **{dotted-circle}** No | **{check-circle}** Yes |
+| Smart Commits | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Sync merge requests | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Sync branches | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Sync commits | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Sync existing data | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes (see [GitLab data synced to Jira](connect-app.md#gitlab-data-synced-to-jira)) |
+| Sync builds | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Sync deployments | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Sync feature flags | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
| Sync interval | Up to 60 minutes | Real time |
-| Delete branches | **{dotted-circle}** No | **{check-circle}** Yes |
-| Create a merge request from a branch | **{check-circle}** Yes | **{check-circle}** Yes |
-| Create a branch from a Jira issue | **{dotted-circle}** No | **{check-circle}** Yes |
+| Delete branches | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Create a merge request from a branch | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Create a branch from a Jira issue | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
## Connected projects in GitLab
diff --git a/doc/integration/jira/dvcs/_index.md b/doc/integration/jira/dvcs/_index.md
index c7749dd2b4866ff1a320f44920c82781d97d85dc..9003548e73cc09634b5362cc7f728981c63be100 100644
--- a/doc/integration/jira/dvcs/_index.md
+++ b/doc/integration/jira/dvcs/_index.md
@@ -5,11 +5,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Jira DVCS connector
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Jira DVCS connector for Jira Cloud was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/362168)
in GitLab 15.1 and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118126) in 16.0.
Use the [GitLab for Jira Cloud app](../connect-app.md) instead.
@@ -17,6 +21,8 @@ The Jira DVCS connector was also deprecated and removed for Jira 8.13 and earlie
You can only use the Jira DVCS connector with Jira Data Center or Jira Server in Jira 8.14 and later.
Upgrade your Jira instance to Jira 8.14 or later and reconfigure the Jira issues integration on your GitLab instance.
+{{< /alert >}}
+
Use the Jira DVCS (distributed version control system) connector if you self-host your Jira instance
with Jira Data Center or Jira Server and want to use the [Jira development panel](../development_panel.md).
The Jira DVCS connector is developed and maintained by Atlassian.
@@ -34,12 +40,12 @@ To refresh the data manually in Jira:
1. Sign in to your Jira instance as the user you configured the integration with.
1. On the top bar, in the upper-right corner,
- select **Administration** (**{settings}**) > **Applications**.
+ select **Administration** ({{< icon name="settings" >}}) > **Applications**.
1. On the left sidebar, select **DVCS accounts**.
1. To refresh one or more repositories in a DVCS account:
- **For all repositories**, next to the account,
- select the ellipsis (**{ellipsis_h}**) > **Refresh repositories**.
+ select the ellipsis ({{< icon name="ellipsis_h" >}}) > **Refresh repositories**.
- **For a single repository**:
1. Select the account.
1. Hover over the repository you want to refresh, and in the **Last activity** column,
- select **Click to sync repository** (**{retry}**).
+ select **Click to sync repository** ({{< icon name="retry" >}}).
diff --git a/doc/integration/jira/dvcs/troubleshooting.md b/doc/integration/jira/dvcs/troubleshooting.md
index 5858ec53be69be77fb9fad665a636fddaa29d36b..50891e371eeafe501d1a450481088a832c4c6478 100644
--- a/doc/integration/jira/dvcs/troubleshooting.md
+++ b/doc/integration/jira/dvcs/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Jira DVCS connector
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with the [Jira DVCS connector](_index.md), you might encounter the following issues.
@@ -102,7 +105,7 @@ resynchronize the information:
1. In Jira, select **Jira Administration > Applications > DVCS accounts**.
1. For the account (group or subgroup), select
- **Refresh repositories** from the **{ellipsis_h}** (ellipsis) menu.
+ **Refresh repositories** from the {{< icon name="ellipsis_h" >}} (ellipsis) menu.
1. For each project, next to the **Last activity** date:
- To perform a *soft resync*, select the sync icon.
- To complete a *full sync*, press `Shift` and select the sync icon.
diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md
index 83806d605dfed003f3b96c0ae036c4999bc6deb7..f494eaba75f322099d3ad9df8162ad68c3d6a5bd 100644
--- a/doc/integration/jira/issues.md
+++ b/doc/integration/jira/issues.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Jira issue management
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can [manage Jira issues directly in GitLab](configure.md).
You can then refer to Jira issues by ID in GitLab commits and merge requests.
@@ -52,9 +55,12 @@ You can [disable comments](#disable-comments-on-jira-issues) on issues.
### Require associated Jira issue for merge requests to be merged
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With this integration, you can prevent merge requests from being merged if they do not refer to a Jira issue.
To enable this feature:
@@ -70,7 +76,11 @@ Jira issue can't be merged. The merge request displays the message
## Customize Jira issue matching in GitLab
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112826) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112826) in GitLab 15.10.
+
+{{< /history >}}
You can configure custom rules for how GitLab matches Jira issue keys by defining:
diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md
index 28e020688da14eee0cda7fa27192f2fa16983f7f..f66783a09e011681e2d355157d0a70b9f94bf909 100644
--- a/doc/integration/jira/jira_server_configuration.md
+++ b/doc/integration/jira/jira_server_configuration.md
@@ -22,7 +22,7 @@ Prerequisites:
To create a Jira user:
-1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **User management**.
+1. On the top bar, in the upper-right corner, select **Administration** ({{< icon name="settings" >}}) > **User management**.
1. [Create a new user account](https://confluence.atlassian.com/adminjiraserver/create-edit-or-remove-a-user-938847025.html#Create,edit,orremoveauser-CreateusersmanuallyinJira) with write access to your Jira projects.
Alternatively, you can use an existing user account, provided the user belongs to a Jira group that has been granted
@@ -39,7 +39,7 @@ Now that you've created a user named `gitlab`, it's time to create a group for t
To create a Jira group for the user:
-1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **User management**.
+1. On the top bar, in the upper-right corner, select **Administration** ({{< icon name="settings" >}}) > **User management**.
1. On the left sidebar, select **Groups**.
1. In the **Add group** section, enter a name for the group (for example,
`gitlab-developers`), then select **Add group**.
@@ -58,7 +58,7 @@ it's time to create a permission scheme for the group.
To create a permission scheme for the group:
-1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **Issues**.
+1. On the top bar, in the upper-right corner, select **Administration** ({{< icon name="settings" >}}) > **Issues**.
1. On the left sidebar, select **Permission schemes**.
1. Select **Add permission scheme**.
1. On the **Add permission scheme** dialog:
diff --git a/doc/integration/jira/troubleshooting.md b/doc/integration/jira/troubleshooting.md
index 8d1f15faa615479992b3d0041d29537e5998e425..cc9e4679b38c89fffc6324f4b3cb43cc2d9daf1d 100644
--- a/doc/integration/jira/troubleshooting.md
+++ b/doc/integration/jira/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Jira issues integration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with the [Jira issues integration](configure.md), you might encounter the following issues.
@@ -69,9 +72,12 @@ If the user can access the issue, Jira responds with a `200 OK` and the returned
### Verify GitLab can post a comment to a Jira issue
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
To help troubleshoot your Jira issues integration, you can check whether
GitLab can post a comment to a Jira issue using the project's Jira
integration settings.
@@ -157,9 +163,12 @@ To resolve this issue, see
## Change all Jira projects to instance-level or group-level values
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
### Change all projects on an instance
To change all Jira projects to use instance-level integration settings:
@@ -234,9 +243,12 @@ To change all Jira projects in a group (and its subgroups) to use group-level in
## Update the integration password for all projects
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
To reset the Jira user's password for all projects with active Jira issues integrations,
run the following in a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session):
diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md
index ba1a1a3fd4558ba46252a809932fe353d669c013..b5c9860d7774b7b078bc20d82f6445a2fbbdbd6a 100644
--- a/doc/integration/kerberos.md
+++ b/doc/integration/kerberos.md
@@ -1,13 +1,16 @@
---
stage: Software Supply Chain Security
group: Authentication
-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"
+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
title: Integrate GitLab with Kerberos
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authentication mechanism.
@@ -16,10 +19,13 @@ GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authen
Kerberos is only available on instances that use GitLab Enterprise Edition (EE). If you're running GitLab Community Edition (CE), you can [convert from GitLab CE to GitLab EE](../update/package/convert_to_ee.md).
-WARNING:
+{{< alert type="warning" >}}
+
GitLab CI/CD doesn't work with a Kerberos-enabled GitLab instance unless the integration is
[set to use a dedicated port](#http-git-access-with-kerberos-token-passwordless-authentication).
+{{< /alert >}}
+
## Configuration
For GitLab to offer Kerberos token-based authentication, perform the
@@ -48,10 +54,13 @@ sudo chmod 0600 /etc/http.keytab
#### Self-compiled installations
-NOTE:
+{{< alert type="note" >}}
+
For self-compiled installations, make sure the `kerberos` gem group
[has been installed](../install/installation.md#install-gems).
+{{< /alert >}}
+
1. Edit the `kerberos` section of [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) to enable Kerberos ticket-based
authentication. In most cases, you only need to enable Kerberos and specify
the location of the keytab:
@@ -106,7 +115,11 @@ set up GitLab to create a new account when a Kerberos user tries to sign in.
### Link a Kerberos account to an existing GitLab account
-> - Kerberos SPNEGO [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96335) to Kerberos in GitLab 15.4.
+{{< history >}}
+
+- Kerberos SPNEGO [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96335) to Kerberos in GitLab 15.4.
+
+{{< /history >}}
If you're an administrator, you can link a Kerberos account to an
existing GitLab account. To do so:
@@ -158,11 +171,14 @@ With that information at hand:
1. If `block_auto_created_users` is false, the Kerberos user is
authenticated and is signed in to GitLab.
-WARNING:
+{{< alert type="warning" >}}
+
We recommend that you retain the default for `block_auto_created_users`.
Kerberos users who create accounts on GitLab without administrator
knowledge can be a security risk.
+{{< /alert >}}
+
## Link Kerberos and LDAP accounts together
If your users sign in with Kerberos, but you also have [LDAP integration](../administration/auth/ldap/_index.md)
@@ -188,9 +204,9 @@ match the domain from the user's LDAP DN. The configuration value must specify
all domains that users may be expected to have. Any other domains are
ignored and an LDAP identity is not linked.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -201,7 +217,9 @@ ignored and an LDAP identity is not linked.
1. Save the file and [reconfigure](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation)
GitLab for the changes to take effect.
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `config/gitlab.yml`:
@@ -213,7 +231,9 @@ ignored and an LDAP identity is not linked.
1. Save the file and [restart](../administration/restart_gitlab.md#self-compiled-installations)
GitLab for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## HTTP Git access
@@ -224,13 +244,16 @@ GitLab users with a linked Kerberos account can also `git pull` and `git push`
using Kerberos tokens. That is, without having to send their password with each
operation.
-WARNING:
+{{< alert type="warning" >}}
+
There is a [known issue](https://github.com/curl/curl/issues/1261) with `libcurl`
older than version 7.64.1 wherein it doesn't reuse connections when negotiating.
This leads to authorization issues when push is larger than `http.postBuffer`
configuration. Ensure that Git is using at least `libcurl` 7.64.1 to avoid this. To
know the `libcurl` version installed, run `curl-config --version`.
+{{< /alert >}}
+
### HTTP Git access with Kerberos token (passwordless authentication)
Because of [a bug in current Git versions](https://lore.kernel.org/git/YKNVop80H8xSTCjz@coredump.intra.peff.net/T/#mab47fd7dcb61fee651f7cc8710b8edc6f62983d5),
@@ -245,14 +268,17 @@ with current Git versions, it is possible to offer Kerberos ticket-based
authentication on a different port (for example, `8443`) while the standard port
offers only `basic` authentication.
-NOTE:
+{{< alert type="note" >}}
+
[Git 2.4 and later](https://github.com/git/git/blob/master/Documentation/RelNotes/2.4.0.txt#L225-L228) supports falling back to `basic` authentication if the
username and password is passed interactively or through a credentials manager. It fails to fall back when the username and password is passed as part of the URL instead. For example,
this can happen in GitLab CI/CD jobs that [authenticate with the CI/CD job token](../ci/jobs/ci_job_token.md).
-::Tabs
+{{< /alert >}}
+
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -264,7 +290,9 @@ this can happen in GitLab CI/CD jobs that [authenticate with the CI/CD job token
1. [Reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-:::TabTitle Self-compiled (source) with HTTPS
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source) with HTTPS" >}}
1. Edit the NGINX configuration file for GitLab
(for example, `/etc/nginx/sites-available/gitlab-ssl`) and configure NGINX to
@@ -293,7 +321,9 @@ this can happen in GitLab CI/CD jobs that [authenticate with the CI/CD job token
1. [Restart GitLab](../administration/restart_gitlab.md#self-compiled-installations) and NGINX for the changes to take effect.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
After this change, Git remote URLs have to be updated to
`https://gitlab.example.com:8443/mygroup/myproject.git` to use
diff --git a/doc/integration/kerberos_troubleshooting.md b/doc/integration/kerberos_troubleshooting.md
index df6ca14a4e60228de3171e312544336b2f3cb097..22934280fa67ad8783b73f46943e758e4c72045f 100644
--- a/doc/integration/kerberos_troubleshooting.md
+++ b/doc/integration/kerberos_troubleshooting.md
@@ -1,13 +1,16 @@
---
stage: Software Supply Chain Security
group: Authentication
-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"
+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
title: Troubleshooting GitLab with Kerberos integration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When working with GitLab with Kerberos integration, you might encounter the following issues.
diff --git a/doc/integration/mattermost/_index.md b/doc/integration/mattermost/_index.md
index 96abf32bf3691c974f1084dfb22732082ebfff0e..25d2390df349627db33aba6c94addf9027c3012e 100644
--- a/doc/integration/mattermost/_index.md
+++ b/doc/integration/mattermost/_index.md
@@ -5,8 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Mattermost
---
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can run a [GitLab Mattermost](https://gitlab.com/gitlab-org/gitlab-mattermost)
service on your GitLab server. Mattermost is not part of the single application that GitLab is. There is a good integration between [Mattermost and GitLab](https://mattermost.com/solutions/mattermost-gitlab/), and our Linux package allows you to install it. **However, Mattermost is a separate application from a separate company.** GitLab Support cannot help you with Mattermost-specific questions beyond the integration with GitLab. If you need help with Mattermost itself, see the [community support resources](#community-support-resources).
@@ -331,11 +334,14 @@ This setting can also be configured in `/var/opt/gitlab/mattermost/config.json`.
## Upgrading GitLab Mattermost
-NOTE:
+{{< alert type="note" >}}
+
When upgrading the Mattermost version, it is essential to check the
[Important Upgrade Notes](https://docs.mattermost.com/administration/important-upgrade-notes.html)
for Mattermost to address any changes or migrations that need to be performed.
+{{< /alert >}}
+
GitLab Mattermost can be upgraded through the regular Linux package update process. When upgrading previous versions of
GitLab, the update process can only be used if Mattermost configuration settings have not been changed outside of GitLab. That is, no changes to the Mattermost `config.json`
file have been made - either directly or via the Mattermost **System Console**, which saves changes to `config.json`.
@@ -390,9 +396,12 @@ Below is a list of Mattermost version changes for GitLab 15.0 and later:
| 15.1 | 6.7 | |
| 15.0 | 6.6 | |
-NOTE:
+{{< alert type="note" >}}
+
The Mattermost upgrade notes refer to different impacts when used with a PostgreSQL versus a MySQL database. The GitLab Mattermost included with the Linux package uses a PostgreSQL database.
+{{< /alert >}}
+
The Linux package bundles the [Mattermost Team Edition](https://docs.mattermost.com/about/editions-and-offerings.html#mattermost-team-edition), which is a free and open source edition and does not include its commercial features.
To upgrade to the [Mattermost Enterprise Edition](https://docs.mattermost.com/about/editions-and-offerings.html#mattermost-enterprise-edition) see the Mattermost [documentation on upgrading](https://docs.mattermost.com/install/enterprise-install-upgrade.html#upgrading-to-enterprise-edition-in-gitlab-omnibus).
diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md
index b9b0fbeeb1f87de1b0b0916187b7b11fd0a674d2..b3700d9b82963bbdc39f8b746aede3ba7e2be2f7 100644
--- a/doc/integration/oauth2_generic.md
+++ b/doc/integration/oauth2_generic.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Generic OAuth2 gem as an OAuth 2.0 authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
If your provider supports the OpenID specification, you should use [`omniauth-openid-connect`](../administration/auth/oidc.md) as your authentication provider.
+{{< /alert >}}
+
The [`omniauth-oauth2-generic` gem](https://gitlab.com/satorix/omniauth-oauth2-generic) allows single sign-on (SSO) between GitLab
and your OAuth 2.0 provider, or any OAuth 2.0 provider compatible with this gem.
@@ -57,9 +63,9 @@ To configure the provider:
1. On your GitLab server, complete the following steps.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
1. Configure the [common settings](omniauth.md#configure-common-settings)
to add `oauth2_generic` as a single sign-on provider. This enables Just-In-Time
@@ -103,7 +109,9 @@ To configure the provider:
sudo gitlab-ctl reconfigure
```
- :::TabTitle Helm chart (Kubernetes)
+ {{< /tab >}}
+
+ {{< tab title="Helm chart (Kubernetes)" >}}
1. Configure the [common settings](omniauth.md#configure-common-settings)
to add `oauth2_generic` as a single sign-on provider. This enables Just-In-Time
@@ -161,7 +169,9 @@ To configure the provider:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
1. Configure the [common settings](omniauth.md#configure-common-settings)
to add `oauth2_generic` as a single sign-on provider. This enables Just-In-Time
@@ -209,7 +219,9 @@ To configure the provider:
sudo service gitlab restart
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
On the sign-in page there should now be a new icon below the regular sign-in
form. Select that icon to begin your provider's authentication process. This
diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md
index b2772aa39f4d8814896c313895cfaeee00942908..e1542ad571f8e32d7f45b1b2f34a0d761eb947cf 100644
--- a/doc/integration/oauth_provider.md
+++ b/doc/integration/oauth_provider.md
@@ -64,9 +64,12 @@ To create a new application for a group:
## Create an instance-wide application
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To create an application for your GitLab instance:
@@ -79,8 +82,12 @@ The user authorization step is automatically skipped for this application.
## View all authorized applications
-> - `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default.
-> - Feature flag `k8s_proxy_pat` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131518) in GitLab 16.5.
+{{< history >}}
+
+- `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default.
+- Feature flag `k8s_proxy_pat` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131518) in GitLab 16.5.
+
+{{< /history >}}
To see all the application you've authorized with your GitLab credentials:
@@ -112,13 +119,20 @@ At any time you can revoke any access by selecting **Revoke**.
## Access token expiration
-> - Database validation on `expires_in` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112765) in GitLab 15.10. If your GitLab instance has any remaining OAuth access tokens without `expires_in` set when you are upgrading to 15.10 or later, the database migration will raise an error. For workaround instructions, see the [GitLab 15.10.0 upgrade documentation](../update/versions/gitlab_15_changes.md#15100).
+{{< history >}}
+
+- Database validation on `expires_in` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112765) in GitLab 15.10. If your GitLab instance has any remaining OAuth access tokens without `expires_in` set when you are upgrading to 15.10 or later, the database migration will raise an error. For workaround instructions, see the [GitLab 15.10.0 upgrade documentation](../update/versions/gitlab_15_changes.md#15100).
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
The ability to opt out of expiring access tokens was
[removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340848) in GitLab 15.0. All
existing integrations must be updated to support access token refresh.
+{{< /alert >}}
+
Access tokens expire after two hours. Integrations that use access tokens must
generate new ones using the `refresh_token` attribute. Refresh tokens may be
used even after the `access_token` itself expires.
@@ -136,10 +150,14 @@ application are also deleted.
## Hashed OAuth application secrets
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `hash_oauth_secrets`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.8.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113892) in GitLab 15.10. Feature flag `hash_oauth_secrets` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `hash_oauth_secrets`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.8.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113892) in GitLab 15.10. Feature flag `hash_oauth_secrets` removed.
+
+{{< /history >}}
By default, GitLab stores OAuth application secrets in the database in hashed format. These secrets are only available to users immediately after creating OAuth applications. In
earlier versions of GitLab, application secrets are stored as plain text in the database.
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md
index e35f8cbc82929189edc8ed3fad9178e156898dce..19855eefdaf0e27301ccfa54b3ee55aef0568f8a 100644
--- a/doc/integration/omniauth.md
+++ b/doc/integration/omniauth.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: OmniAuth
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Users can sign in to GitLab by using their credentials from Google, GitHub, and other popular services.
[OmniAuth](https://rubygems.org/gems/omniauth/) is the Rack framework that GitLab uses to provide this authentication.
@@ -61,9 +64,9 @@ configure the settings that are common for all providers.
To change the OmniAuth settings:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -83,7 +86,9 @@ To change the OmniAuth settings:
sudo gitlab-ctl reconfigure
```
- :::TabTitle Helm chart (Kubernetes)
+ {{< /tab >}}
+
+ {{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -112,7 +117,9 @@ To change the OmniAuth settings:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -133,7 +140,9 @@ To change the OmniAuth settings:
docker compose up -d
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -166,14 +175,20 @@ To change the OmniAuth settings:
sudo service gitlab restart
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
After configuring these settings, you can configure
your chosen [provider](#supported-providers).
### Per-provider configuration
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89379) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89379) in GitLab 15.3.
+
+{{< /history >}}
If `allow_single_sign_on` is set, GitLab uses one of the following fields returned in the OmniAuth `auth_hash` to establish a username in GitLab for the user signing in,
choosing the first that exists:
@@ -185,9 +200,9 @@ choosing the first that exists:
You can create GitLab configuration on a per-provider basis, which is supplied to the [provider](#supported-providers) using `args`. If you set the `gitlab_username_claim`
variable in `args` for a provider, you can select another claim to use for the GitLab username. The chosen claim must be unique to avoid collisions.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```ruby
gitlab_rails['omniauth_providers'] = [
@@ -215,7 +230,9 @@ gitlab_rails['omniauth_providers'] = [
]
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```yaml
- { name: 'PROVIDER_NAME',
@@ -232,7 +249,9 @@ gitlab_rails['omniauth_providers'] = [
}
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Passwords for users created via OmniAuth
@@ -260,9 +279,12 @@ You can now use your chosen OmniAuth provider to sign in to GitLab.
Administrators can enable or disable sign-in for some OmniAuth providers.
-NOTE:
+{{< alert type="note" >}}
+
By default, sign-in is enabled for all the OAuth providers configured in `config/gitlab.yml`.
+{{< /alert >}}
+
To enable or disable an OmniAuth provider:
1. On the left sidebar, at the bottom, select **Admin**.
@@ -278,22 +300,26 @@ if providers are configured and [enabled](#enable-or-disable-sign-in-with-an-omn
If OmniAuth providers are causing problems even when individually disabled, you
can disable the entire OmniAuth subsystem by modifying the configuration file.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```ruby
gitlab_rails['omniauth_enabled'] = false
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```yaml
omniauth:
enabled: false
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Link existing users to OmniAuth users
@@ -302,22 +328,26 @@ You can automatically link OmniAuth users with existing GitLab users if their em
The following example enables automatic linking
for the OpenID Connect provider and the Google OAuth provider.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```ruby
gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "google_oauth2"]
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```yaml
omniauth:
auto_link_user: ["openid_connect", "google_oauth2"]
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
This method of enabling automatic linking works for all providers
[except SAML](https://gitlab.com/gitlab-org/gitlab/-/issues/338293).
@@ -332,35 +362,49 @@ To define the external providers list, use the full name of the provider,
for example, `google_oauth2` for Google. For provider names, see the
**OmniAuth provider name** column in the [supported providers table](#supported-providers).
-NOTE:
+{{< alert type="note" >}}
+
If you remove an OmniAuth provider from the external providers list,
you must manually update the users that use this sign-in method so their
accounts are upgraded to full internal accounts.
-::Tabs
+{{< /alert >}}
+
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```ruby
gitlab_rails['omniauth_external_providers'] = ['saml', 'google_oauth2']
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```yaml
omniauth:
external_providers: ['saml', 'google_oauth2']
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Keep OmniAuth user profiles up to date
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/505575) `job_title` and `organization` attributes in GitLab 17.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/505575) `job_title` and `organization` attributes in GitLab 17.8.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
Some providers require additional configuration to synchronize these attributes. For example, SAML providers require [mapping profile attributes](saml.md#map-profile-attributes).
+{{< /alert >}}
+
You can enable profile syncing from selected OmniAuth providers.
You can sync any combination of the following user attributes:
@@ -372,9 +416,9 @@ You can sync any combination of the following user attributes:
When authenticating using LDAP, the user's name and email are always synced.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -389,7 +433,9 @@ When authenticating using LDAP, the user's name and email are always synced.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -413,7 +459,9 @@ When authenticating using LDAP, the user's name and email are always synced.
helm upgrade -f values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -433,7 +481,9 @@ When authenticating using LDAP, the user's name and email are always synced.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -454,7 +504,9 @@ When authenticating using LDAP, the user's name and email are always synced.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Bypass two-factor authentication
@@ -473,22 +525,26 @@ This option should be configured only for providers that already have 2FA. The d
This configuration doesn't apply to SAML.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```ruby
gitlab_rails['omniauth_allow_bypass_two_factor'] = ['saml', 'google_oauth2']
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```yaml
omniauth:
allow_bypass_two_factor: ['saml', 'google_oauth2']
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Sign in with a provider automatically
@@ -499,22 +555,26 @@ authentication. This removes the need to select the provider before signing in.
For example, to enable automatic sign-in for the
[Azure v2 integration](azure.md):
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```ruby
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2'
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```yaml
omniauth:
auto_sign_in_with_provider: azure_activedirectory_v2
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
Keep in mind that every sign-in attempt is redirected to the OmniAuth
provider, so you can't sign in using local credentials. Ensure at least
diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md
index 3df65179889799bbfa1af8db4215e3aad92cd669..2f50357a08fcc159ee7a9d3c6eb706a9800fcf5c 100644
--- a/doc/integration/openid_connect_provider.md
+++ b/doc/integration/openid_connect_provider.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab as OpenID Connect identity provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
You can use GitLab as an [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC)
identity provider to access other services.
@@ -44,21 +47,21 @@ The following user information is shared with clients:
| Claim | Type | Description | Included in ID Token | Included in `userinfo` endpoint |
|:---------------------|:----------|:------------|:---------------------|:------------------------------|
-| `sub` | `string` | The ID of the user | **{check-circle}** Yes | **{check-circle}** Yes |
-| `auth_time` | `integer` | The timestamp for the user's last authentication | **{check-circle}** Yes | **{dotted-circle}** No |
-| `name` | `string` | The user's full name | **{check-circle}** Yes | **{check-circle}** Yes |
-| `nickname` | `string` | The user's GitLab username | **{check-circle}** Yes| **{check-circle}** Yes |
-| `preferred_username` | `string` | The user's GitLab username | **{check-circle}** Yes | **{check-circle}** Yes |
-| `email` | `string` | The user's primary email address | **{check-circle}** Yes | **{check-circle}** Yes |
-| `email_verified` | `boolean` | Whether the user's email address is verified | **{check-circle}** Yes | **{check-circle}** Yes |
-| `website` | `string` | URL for the user's website | **{check-circle}** Yes | **{check-circle}** Yes |
-| `profile` | `string` | URL for the user's GitLab profile | **{check-circle}** Yes | **{check-circle}** Yes|
-| `picture` | `string` | URL for the user's GitLab avatar | **{check-circle}** Yes| **{check-circle}** Yes |
-| `groups` | `array` | Paths for the groups the user is a member of, either directly or through an ancestor group. | **{dotted-circle}** No | **{check-circle}** Yes |
-| `groups_direct` | `array` | Paths for the groups the user is a direct member of. | **{check-circle}** Yes | **{dotted-circle}** No |
-| `https://gitlab.org/claims/groups/owner` | `array` | Names of the groups the user is a direct member of with the Owner role | **{dotted-circle}** No | **{check-circle}** Yes |
-| `https://gitlab.org/claims/groups/maintainer` | `array` | Names of the groups the user is a direct member of with the Maintainer role | **{dotted-circle}** No | **{check-circle}** Yes |
-| `https://gitlab.org/claims/groups/developer` | `array` | Names of the groups the user is a direct member of with the Developer role | **{dotted-circle}** No | **{check-circle}** Yes |
+| `sub` | `string` | The ID of the user | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| `auth_time` | `integer` | The timestamp for the user's last authentication | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| `name` | `string` | The user's full name | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| `nickname` | `string` | The user's GitLab username | {{< icon name="check-circle" >}} Yes| {{< icon name="check-circle" >}} Yes |
+| `preferred_username` | `string` | The user's GitLab username | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| `email` | `string` | The user's primary email address | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| `email_verified` | `boolean` | Whether the user's email address is verified | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| `website` | `string` | URL for the user's website | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| `profile` | `string` | URL for the user's GitLab profile | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes|
+| `picture` | `string` | URL for the user's GitLab avatar | {{< icon name="check-circle" >}} Yes| {{< icon name="check-circle" >}} Yes |
+| `groups` | `array` | Paths for the groups the user is a member of, either directly or through an ancestor group. | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| `groups_direct` | `array` | Paths for the groups the user is a direct member of. | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| `https://gitlab.org/claims/groups/owner` | `array` | Names of the groups the user is a direct member of with the Owner role | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| `https://gitlab.org/claims/groups/maintainer` | `array` | Names of the groups the user is a direct member of with the Maintainer role | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| `https://gitlab.org/claims/groups/developer` | `array` | Names of the groups the user is a direct member of with the Developer role | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
The claims `email` and `email_verified` are included only if the application has access to the
`email` scope and the user's public email address. All other claims are available from the
diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md
index 4a28a6cfc2b6a75f9feb419a15ca5a368b8e8a2a..77195a3b57dbaf8258326bfd46fecc157ae9eb20 100644
--- a/doc/integration/recaptcha.md
+++ b/doc/integration/recaptcha.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: reCAPTCHA
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab leverages [reCAPTCHA](https://www.google.com/recaptcha/about/)
to protect against spam and abuse. GitLab displays the CAPTCHA form on the sign-up page
@@ -31,9 +34,12 @@ To use reCAPTCHA, first create a site and private key.
1. Open `app/services/spam/spam_verdict_service.rb`.
1. Change the first line of the `#execute` method to `return CONDITIONAL_ALLOW`.
-NOTE:
+{{< alert type="note" >}}
+
Make sure you are viewing an issuable in a project that is public. If you're working with an issue, the issue is public.
+{{< /alert >}}
+
## Enable reCAPTCHA for user logins using the HTTP header
You can enable reCAPTCHA for user logins via password [in the user interface](#configuration)
diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md
index 67958f7d9b62a019cb450489e38b94b4a44eef74..fbf997cf785761a1875407d87c2ef4e230b68e33 100644
--- a/doc/integration/salesforce.md
+++ b/doc/integration/salesforce.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Salesforce as an OAuth 2.0 authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can integrate your GitLab instance with [Salesforce](https://www.salesforce.com/) to enable users to sign in to your GitLab instance with their Salesforce account.
@@ -95,7 +98,10 @@ On the sign in page, there should now be a Salesforce icon below the regular sig
Select the icon to begin the authentication process. Salesforce asks the user to sign in and authorize the GitLab application.
If everything goes well, the user is returned to GitLab and is signed in.
-NOTE:
+{{< alert type="note" >}}
+
GitLab requires the email address of each new user. After the user is signed in
using Salesforce, GitLab redirects the user to the profile page where they must
provide the email and verify the email.
+
+{{< /alert >}}
diff --git a/doc/integration/saml.md b/doc/integration/saml.md
index 931245cf378a2883c0cd414a954b61ea74bc9d17..8df81e46a1d5b5024a1808671e0f5b1ad5944414 100644
--- a/doc/integration/saml.md
+++ b/doc/integration/saml.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: SAML SSO for GitLab Self-Managed
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page describes how to set up instance-wide SAML single sign on (SSO) for
GitLab Self-Managed.
@@ -25,9 +28,9 @@ For more information on:
## Configure SAML support in GitLab
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/).
1. Configure the [common settings](omniauth.md#configure-common-settings)
@@ -99,7 +102,9 @@ For more information on:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/charts/installation/tls.html).
1. Configure the [common settings](omniauth.md#configure-common-settings)
@@ -194,7 +199,9 @@ For more information on:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/).
1. Configure the [common settings](omniauth.md#configure-common-settings)
@@ -279,7 +286,9 @@ For more information on:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Make sure GitLab is [configured with HTTPS](../install/installation.md#using-https).
1. Configure the [common settings](omniauth.md#configure-common-settings)
@@ -358,7 +367,9 @@ For more information on:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Register GitLab in your SAML IdP
@@ -407,14 +418,17 @@ You can configure GitLab to use multiple SAML IdPs if:
- The `strategy_class` is explicitly set because it cannot be inferred from provider
name.
-NOTE:
+{{< alert type="note" >}}
+
When you configure multiple SAML IdPs, to ensure that SAML Group Links work, you must configure all SAML IdPs to contain group attributes in the SAML response. For more information, see [SAML Group Links](../user/group/saml_sso/group_sync.md).
+{{< /alert >}}
+
To set up multiple SAML IdPs:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -456,7 +470,9 @@ To set up multiple SAML IdPs:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers)
@@ -530,7 +546,9 @@ To set up multiple SAML IdPs:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -583,7 +601,9 @@ To set up multiple SAML IdPs:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -632,7 +652,9 @@ To set up multiple SAML IdPs:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Set up identity providers
@@ -742,14 +764,24 @@ your provider's support.
### Configure assertions
-DETAILS:
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab.com, GitLab Self-Managed
-> - Microsoft Azure/Entra ID attribute support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420766) in GitLab 16.7.
+{{< /details >}}
+
+{{< history >}}
+
+- Microsoft Azure/Entra ID attribute support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420766) in GitLab 16.7.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
These attributes are case-sensitive.
+{{< /alert >}}
+
| Field | Supported default keys |
|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Email (required)| `email`, `mail`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress` |
@@ -894,9 +926,9 @@ authentication can use the service.
If the attribute specified in `groups_attribute` is incorrect or missing then all users will be blocked.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -923,7 +955,9 @@ If the attribute specified in `groups_attribute` is incorrect or missing then al
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -969,7 +1003,9 @@ If the attribute specified in `groups_attribute` is incorrect or missing then al
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -1001,7 +1037,9 @@ If the attribute specified in `groups_attribute` is incorrect or missing then al
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1033,7 +1071,9 @@ If the attribute specified in `groups_attribute` is incorrect or missing then al
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### External groups
@@ -1053,9 +1093,9 @@ access as a standard user.
Example configuration:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1083,7 +1123,9 @@ Example configuration:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -1129,7 +1171,9 @@ Example configuration:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -1161,7 +1205,9 @@ Example configuration:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1193,7 +1239,9 @@ Example configuration:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Administrator groups
@@ -1210,9 +1258,9 @@ If the attribute specified in `groups_attribute` is incorrect or missing then us
Example configuration:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1239,7 +1287,9 @@ Example configuration:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -1285,7 +1335,9 @@ Example configuration:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -1317,7 +1369,9 @@ Example configuration:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1349,13 +1403,18 @@ Example configuration:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Auditor groups
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Your IdP passes group information to GitLab in the SAML response. To use this
response, configure GitLab to identify:
@@ -1370,9 +1429,9 @@ If the attribute specified in `groups_attribute` is incorrect or missing then us
Example configuration:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1399,7 +1458,9 @@ Example configuration:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -1445,7 +1506,9 @@ Example configuration:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -1477,7 +1540,9 @@ Example configuration:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1509,7 +1574,9 @@ Example configuration:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Automatically manage SAML Group Sync
@@ -1517,8 +1584,12 @@ For information on automatically managing GitLab group membership, see [SAML Gro
## Bypass two-factor authentication
-> - Bypass 2FA enforcement [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122109) in GitLab 16.1 [with a flag](../administration/feature_flags.md) named `by_pass_two_factor_current_session`.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/416535) in GitLab 17.8.
+{{< history >}}
+
+- Bypass 2FA enforcement [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122109) in GitLab 16.1 [with a flag](../administration/feature_flags.md) named `by_pass_two_factor_current_session`.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/416535) in GitLab 17.8.
+
+{{< /history >}}
To configure a SAML authentication method to count as two-factor authentication
(2FA) on a per session basis, register that method in the `upstream_two_factor_authn_contexts`
@@ -1537,9 +1608,9 @@ list.
1. Edit your installation configuration to register the SAML authentication method
in the `upstream_two_factor_authn_contexts` list. You must enter the `AuthnContext` from your SAML response.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1570,7 +1641,9 @@ list.
sudo gitlab-ctl reconfigure
```
- :::TabTitle Helm chart (Kubernetes)
+ {{< /tab >}}
+
+ {{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -1618,7 +1691,9 @@ list.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -1654,7 +1729,9 @@ list.
docker compose up -d
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1690,7 +1767,9 @@ list.
sudo service gitlab restart
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
## Validate response signatures
@@ -1704,9 +1783,9 @@ membership is required.
You configure the response signature validation using `idp_cert_fingerprint`.
An example configuration:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1731,7 +1810,9 @@ An example configuration:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -1775,7 +1856,9 @@ An example configuration:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -1805,7 +1888,9 @@ An example configuration:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1835,7 +1920,9 @@ An example configuration:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Using `idp_cert`
@@ -1843,9 +1930,9 @@ If your IdP does not support configuring this using `idp_cert_fingerprint`, you
can instead configure GitLab directly using `idp_cert`.
An example configuration:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -1872,7 +1959,9 @@ An example configuration:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -1919,7 +2008,9 @@ An example configuration:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -1951,7 +2042,9 @@ An example configuration:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1983,7 +2076,9 @@ An example configuration:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
If you have configured the response signature validation incorrectly, you might see
error messages such as:
@@ -2002,9 +2097,9 @@ You can add the `auto_sign_in_with_provider` setting to your GitLab configuratio
to automatically redirect you to your SAML server for authentication. This removes
the requirement to select an element before actually signing in.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -2018,7 +2113,9 @@ the requirement to select an element before actually signing in.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Export the Helm values:
@@ -2041,7 +2138,9 @@ the requirement to select an element before actually signing in.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -2060,7 +2159,9 @@ the requirement to select an element before actually signing in.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -2080,27 +2181,38 @@ the requirement to select an element before actually signing in.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
Every sign in attempt redirects to the SAML server, so you cannot sign in using
local credentials. Make sure at least one of the SAML users has administrator access.
-NOTE:
+{{< alert type="note" >}}
+
To bypass the auto sign-in setting, append `?auto_sign_in=false` in the sign in
URL, for example: `https://gitlab.example.com/users/sign_in?auto_sign_in=false`.
+{{< /alert >}}
+
### Map SAML response attribute names
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use `attribute_statements` to map attribute names in a SAML response to entries
in the OmniAuth [`info` hash](https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later).
-NOTE:
+{{< alert type="note" >}}
+
Only use this setting to map attributes that are part of the OmniAuth `info` hash schema.
+{{< /alert >}}
+
For example, if your `SAMLResponse` contains an Attribute called `EmailAddress`,
specify `{ email: ['EmailAddress'] }` to map the Attribute to the
corresponding key in the `info` hash. URI-named Attributes are also supported, for example,
@@ -2110,9 +2222,9 @@ Use this setting to tell GitLab where to look for certain attributes required
to create an account. For example, if your IdP sends the user's email address as `EmailAddress`
instead of `email`, let GitLab know by setting it on your configuration:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -2138,7 +2250,9 @@ instead of `email`, let GitLab know by setting it on your configuration:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -2184,7 +2298,9 @@ instead of `email`, let GitLab know by setting it on your configuration:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -2215,7 +2331,9 @@ instead of `email`, let GitLab know by setting it on your configuration:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -2246,7 +2364,9 @@ instead of `email`, let GitLab know by setting it on your configuration:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Set a username
@@ -2255,9 +2375,9 @@ generate the user's GitLab username.
Configure [`username` or `nickname`](omniauth.md#per-provider-configuration) in `attribute_statements` to specify one or more attributes that contain a user's desired username:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -2283,7 +2403,9 @@ Configure [`username` or `nickname`](omniauth.md#per-provider-configuration) in
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -2329,7 +2451,9 @@ Configure [`username` or `nickname`](omniauth.md#per-provider-configuration) in
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -2362,7 +2486,9 @@ Configure [`username` or `nickname`](omniauth.md#per-provider-configuration) in
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -2395,13 +2521,19 @@ Configure [`username` or `nickname`](omniauth.md#per-provider-configuration) in
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
This also sets the `username` attribute in your SAML Response to the username in GitLab.
#### Map profile attributes
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/505575) `job_title` and `organization` attributes in GitLab 17.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/505575) `job_title` and `organization` attributes in GitLab 17.8.
+
+{{< /history >}}
To sync profile information from your SAML provider, you must configure `attribute_statements` to map these attributes.
@@ -2412,9 +2544,9 @@ The supported profile attributes are:
These attributes have no default mappings and do not sync unless explicitly configured.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. [Configure OmniAuth to sync the desired attributes](omniauth.md#keep-omniauth-user-profiles-up-to-date).
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -2444,7 +2576,9 @@ These attributes have no default mappings and do not sync unless explicitly conf
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. [Configure OmniAuth to sync the desired attributes](omniauth.md#keep-omniauth-user-profiles-up-to-date).
1. Save the following YAML content in a file named `saml.yaml` to be used as a
@@ -2492,7 +2626,9 @@ These attributes have no default mappings and do not sync unless explicitly conf
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. [Configure OmniAuth to sync the desired attributes](omniauth.md#keep-omniauth-user-profiles-up-to-date).
1. Edit `docker-compose.yml`:
@@ -2527,7 +2663,9 @@ These attributes have no default mappings and do not sync unless explicitly conf
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. [Configure OmniAuth to sync the desired attributes](omniauth.md#keep-omniauth-user-profiles-up-to-date).
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -2562,7 +2700,9 @@ These attributes have no default mappings and do not sync unless explicitly conf
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Allow for clock drift
@@ -2571,9 +2711,9 @@ To allow for a small amount of clock drift, use `allowed_clock_drift` in
your settings. You must enter the parameter's value in a number and fraction of seconds.
The value given is added to the current time at which the response is validated.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -2601,7 +2741,9 @@ The value given is added to the current time at which the response is validated.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -2648,7 +2790,9 @@ The value given is added to the current time at which the response is validated.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -2681,7 +2825,9 @@ The value given is added to the current time at which the response is validated.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -2714,7 +2860,9 @@ The value given is added to the current time at which the response is validated.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Designate a unique attribute for the `uid` (optional)
@@ -2732,9 +2880,9 @@ See your SAML IdP documentation for information on how to make these attributes
unchangeable.
In the following example, the value of `uid` attribute in the SAML response is set as the `uid_attribute`.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -2760,7 +2908,9 @@ In the following example, the value of `uid` attribute in the SAML response is s
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -2807,7 +2957,9 @@ In the following example, the value of `uid` attribute in the SAML response is s
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -2840,7 +2992,9 @@ In the following example, the value of `uid` attribute in the SAML response is s
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -2873,7 +3027,9 @@ In the following example, the value of `uid` attribute in the SAML response is s
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Assertion encryption (optional)
@@ -2888,10 +3044,13 @@ Most organizations should not need additional encryption at this layer.
Your IdP encrypts the assertion with the public certificate of GitLab.
GitLab decrypts the `EncryptedAssertion` with its private key.
-NOTE:
+{{< alert type="note" >}}
+
This integration uses the `certificate` and `private_key` settings for both
assertion encryption and request signing.
+{{< /alert >}}
+
The SAML integration supports `EncryptedAssertion`. To encrypt your assertions,
define the private key and the public certificate of your GitLab instance in the
SAML settings.
@@ -2899,9 +3058,9 @@ SAML settings.
When you define the key and certificate, replace all line feeds in the key file with `\n`.
This makes the key file one long string with no line feeds.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -2930,7 +3089,9 @@ This makes the key file one long string with no line feeds.
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -2978,7 +3139,9 @@ This makes the key file one long string with no line feeds.
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -3012,7 +3175,9 @@ This makes the key file one long string with no line feeds.
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -3046,7 +3211,9 @@ This makes the key file one long string with no line feeds.
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Sign SAML authentication requests (optional)
@@ -3060,9 +3227,9 @@ To implement signing:
1. Configure the signing settings in the `security` section of the configuration.
For example:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux package (Omnibus)
+ {{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -3097,7 +3264,9 @@ To implement signing:
sudo gitlab-ctl reconfigure
```
- :::TabTitle Helm chart (Kubernetes)
+ {{< /tab >}}
+
+ {{< tab title="Helm chart (Kubernetes)" >}}
1. Put the following content in a file named `saml.yaml` to be used as a
[Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers):
@@ -3150,7 +3319,9 @@ To implement signing:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
- :::TabTitle Docker
+ {{< /tab >}}
+
+ {{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -3190,7 +3361,9 @@ To implement signing:
docker compose up -d
```
- :::TabTitle Self-compiled (source)
+ {{< /tab >}}
+
+ {{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -3230,7 +3403,9 @@ To implement signing:
sudo service gitlab restart
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
GitLab then:
@@ -3245,10 +3420,13 @@ The Ruby SAML gem is used by the
[OmniAuth SAML gem](https://github.com/omniauth/omniauth-saml) to implement the
client side of the SAML authentication.
-NOTE:
+{{< alert type="note" >}}
+
The SAML redirect binding is different to the SAML POST binding. In the POST binding,
signing is required to prevent intermediaries from tampering with the requests.
+{{< /alert >}}
+
## Password generation for users created through SAML
GitLab [generates and sets passwords for users created through SAML](../security/passwords_for_integrated_authentication_methods.md).
@@ -3269,18 +3447,21 @@ see [Enable OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-ex
## Configure group SAML SSO on GitLab Self-Managed
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use group SAML SSO if you have to allow access through multiple SAML IdPs on your
GitLab Self-Managed instance.
To configure group SAML SSO:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/).
1. Edit `/etc/gitlab/gitlab.rb` to enable OmniAuth and the `group_saml` provider:
@@ -3296,7 +3477,9 @@ To configure group SAML SSO:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/charts/installation/tls.html).
1. Put the following content in a file named `group_saml.yaml` to be used as a
@@ -3335,7 +3518,9 @@ To configure group SAML SSO:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/).
1. Edit `docker-compose.yml` to enable OmniAuth and the `group_saml` provider:
@@ -3356,7 +3541,9 @@ To configure group SAML SSO:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Make sure GitLab is [configured with HTTPS](../install/installation.md#using-https).
1. Edit `/home/git/gitlab/config/gitlab.yml` to enable OmniAuth and the `group_saml` provider:
@@ -3379,7 +3566,9 @@ To configure group SAML SSO:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
As a multi-tenant solution, group SAML on GitLab Self-Managed is limited compared
to the recommended [instance-wide SAML](saml.md). Use
diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md
index 511d79ee21fa416b1a7dd95b9be431f0955c2607..f5e2a207fded3d1a30a23f48f2cb0a45b8fe2399 100644
--- a/doc/integration/shibboleth.md
+++ b/doc/integration/shibboleth.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Shibboleth as an authentication provider
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
Use the [GitLab SAML integration](saml.md) to integrate specific Shibboleth identity providers (IdPs). For Shibboleth federation support (Discovery Service), use this document.
+{{< /alert >}}
+
To enable Shibboleth support in GitLab, use Apache instead of NGINX. Apache uses the `mod_shib2` module for Shibboleth authentication, and can pass attributes as headers to the OmniAuth Shibboleth provider.
You can use the bundled NGINX provided in the Linux package to run a Shibboleth service provider on a different instance using a reverse proxy setup. However if you are not doing this, the bundled NGINX is difficult to configure.
diff --git a/doc/integration/snowflake.md b/doc/integration/snowflake.md
index 7e7b43d0d9c9d8779c373183965586c628de8120..7da453f2964fc301a188961f6d0020c235d06f1c 100644
--- a/doc/integration/snowflake.md
+++ b/doc/integration/snowflake.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Snowflake
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451328) for audit events in GitLab 17.1.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451328) for audit events in GitLab 17.1.
+
+{{< /history >}}
The Snowflake [GitLab Data Connector](https://app.snowflake.com/marketplace/listing/GZTYZXESENG/gitlab-gitlab-data-connector) pulls data into [Snowflake](https://www.snowflake.com/en/).
diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md
index d8f7d66a4dbf67112805393b917141857f97bd9a..3f4711365ea040002bcf0ded4ed2a2e8a91c9478 100644
--- a/doc/integration/sourcegraph.md
+++ b/doc/integration/sourcegraph.md
@@ -1,17 +1,23 @@
---
stage: Create
group: Source Code
-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"
+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
title: Sourcegraph
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
On GitLab.com, this feature is available for public projects only.
+{{< /alert >}}
+
[Sourcegraph](https://sourcegraph.com) provides code intelligence features in the GitLab UI.
When enabled, participating projects display a code intelligence popover in
these code views:
@@ -34,9 +40,12 @@ For more information, see [epic 2201](https://gitlab.com/groups/gitlab-org/-/epi
## Set up for GitLab Self-Managed
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md
index 00aa7f28e167b80f3031a107256cb2066718c34d..77acbb78f7e72d346fb3e81011f4721bcd5fff50 100644
--- a/doc/integration/trello_power_up.md
+++ b/doc/integration/trello_power_up.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Trello Power-Ups
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use Trello Power-Ups for GitLab to attach
GitLab merge requests to Trello cards.
diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md
index e5ade60379603174cdc8e6c488b5f39c3f905c78..bc1fab903ce127549cb7c6ad6db01c019207a4ac 100644
--- a/doc/integration/twitter.md
+++ b/doc/integration/twitter.md
@@ -1,15 +1,18 @@
---
+redirect_to: omniauth.md#supported-providers
+remove_date: "2025-01-29"
stage: Software Supply Chain Security
group: Authentication
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
-remove_date: '2025-01-29'
-redirect_to: 'omniauth.md#supported-providers'
title: Twitter OAuth 1.0a OmniAuth Provider (removed)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This feature was [deprecated](https://gitlab.com/gitlab-com/Product/-/issues/11417) in GitLab 16.3
and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/420978) in 17.0.
diff --git a/doc/integration/vault.md b/doc/integration/vault.md
index 602b9cd935c22fbfc85b595f91c0c9dce19177fc..46b3d0c4bd32d926c6f03edfbb71423f5c5efd9e 100644
--- a/doc/integration/vault.md
+++ b/doc/integration/vault.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Vault authentication with GitLab OpenID Connect
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Vault](https://www.vaultproject.io/) is a secrets management application offered by HashiCorp.
It allows you to store and manage sensitive information such as secret environment
@@ -112,11 +115,14 @@ The `oidc_scopes` field must include `openid`.
This configuration is saved under the name of the role you are creating. In this
example, we are creating a `demo` role.
-WARNING:
+{{< alert type="warning" >}}
+
If you're using a public GitLab instance, such as GitLab.com, you must specify
the `bound_claims` to allow access only to members of your group or project.
Otherwise, anyone with a public account can access your Vault instance.
+{{< /alert >}}
+
## Sign in to Vault
1. Go to your Vault UI. For example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc).
diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md
index 5855dde4201a32b93ad677875ea1d175103e36b2..1bd8babe64d383a2e43e037c434c7b80eaccc6f0 100644
--- a/doc/legal/corporate_contributor_license_agreement.md
+++ b/doc/legal/corporate_contributor_license_agreement.md
@@ -2,10 +2,10 @@
stage: none
group: unassigned
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
+title: Corporate contributor license agreement
---
-<!-- vale off -->
-# Corporate contributor license agreement
+<!-- vale off -->
You accept and agree to the following terms and conditions for Your present and
future Contributions submitted to GitLab Inc. Except for the license granted
diff --git a/doc/legal/developer_certificate_of_origin.md b/doc/legal/developer_certificate_of_origin.md
index 3d649437ea97c5708c6c14bb43ab56157cd34ff4..71f141553f74fde20aabcafce2c6366459e112f6 100644
--- a/doc/legal/developer_certificate_of_origin.md
+++ b/doc/legal/developer_certificate_of_origin.md
@@ -2,10 +2,10 @@
stage: none
group: unassigned
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
+title: Developer Certificate of Origin Version 1.1
---
-<!-- vale off -->
-# Developer Certificate of Origin Version 1.1
+<!-- vale off -->
Copyright (C) 2004, 2006 The Linux Foundation and its contributors, 1 Letterman Drive, Suite D4700, San Francisco, CA 94129, USA
diff --git a/doc/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md
index 2b6fb6d85f18091a459b3c891857c7808219646e..41fa9a0ca47dc03ec89456b2951ac7dfb0efc118 100644
--- a/doc/legal/individual_contributor_license_agreement.md
+++ b/doc/legal/individual_contributor_license_agreement.md
@@ -2,10 +2,10 @@
stage: none
group: unassigned
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
+title: Individual contributor license agreement
---
-<!-- vale off -->
-# Individual contributor license agreement
+<!-- vale off -->
You accept and agree to the following terms and conditions for Your present and
future Contributions submitted to GitLab Inc. Except for the license granted
diff --git a/doc/operations/_index.md b/doc/operations/_index.md
index 51bb821ef157f8d9e0c5d97bbda4c7d1341e998e..9f4a9af037c7c3b5b822e6dd46c6888dc6da587f 100644
--- a/doc/operations/_index.md
+++ b/doc/operations/_index.md
@@ -1,8 +1,8 @@
---
stage: Monitor
group: Platform Insights
-description: Track errors, application performance issues, customer behavior patterns and manage incident response.
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
+description: Track errors, application performance issues, customer behavior patterns and manage incident response.
title: Monitor your application
---
diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md
index 462bbec2a7f5b12d44e4b6d2b21c79a4d2a43366..38d1dedf02dc07adabf7099e4daea558970b944f 100644
--- a/doc/operations/feature_flags.md
+++ b/doc/operations/feature_flags.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Feature flags
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With feature flags, you can deploy your application's new features to production in smaller batches.
You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery.
@@ -21,10 +24,13 @@ For an example of feature flags in action, see [Eliminating risk with feature fl
For a click-through demo, see [Feature Flags](https://tech-marketing.gitlab.io/static-demos/feature-flags/feature-flags-html.html).
<!-- Demo published on 2023-07-13 -->
-NOTE:
+{{< alert type="note" >}}
+
To contribute to the development of the GitLab product, view
[this feature flag content](../development/feature_flags/_index.md) instead.
+{{< /alert >}}
+
## How it works
GitLab offers an [Unleash](https://github.com/Unleash/unleash)-compatible API for feature flags.
@@ -51,7 +57,7 @@ To create and enable a feature flag:
and **Environments** (defaults to all environments).
1. Select **Create feature flag**.
-To change these settings, select **Edit** (**{pencil}**)
+To change these settings, select **Edit** ({{< icon name="pencil" >}})
next to any feature flag in the list.
## Maximum number of feature flags
@@ -81,7 +87,7 @@ flag controls. GitLab feature flags can have multiple strategies, and the suppor
Strategies can be added to feature flags when [creating a feature flag](#create-a-feature-flag),
or by editing an existing feature flag after creation by navigating to **Deploy > Feature flags**
-and selecting **Edit** (**{pencil}**).
+and selecting **Edit** ({{< icon name="pencil" >}}).
### All users
@@ -113,9 +119,12 @@ The rollout percentage can be from 0% to 100%.
Selecting a consistency based on User IDs functions the same as the [percent of Users](#percent-of-users) rollout.
-WARNING:
+{{< alert type="warning" >}}
+
Selecting **Random** provides inconsistent application behavior for individual users.
+{{< /alert >}}
+
### Percent of Users
Enables the feature for a percentage of authenticated users. It uses the Unleash activation strategy
@@ -131,10 +140,13 @@ but not anonymous users.
[Percent rollout](#percent-rollout) with a consistency based on **User IDs** has the same
behavior. We recommend using percent rollout because it's more flexible than percent of users
-WARNING:
+{{< alert type="warning" >}}
+
If the percent of users strategy is selected, then the Unleash client **must** be given a user
ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below.
+{{< /alert >}}
+
### User IDs
Enables the feature for a list of target users. It is implemented
@@ -144,10 +156,13 @@ Enter user IDs as a comma-separated list of values (for example,
`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on).
User IDs are identifiers for your application users. They do not need to be GitLab users.
-WARNING:
+{{< alert type="warning" >}}
+
The Unleash client **must** be given a user ID for the feature to be enabled for
target users. See the [Ruby example](#ruby-application-example) below.
+{{< /alert >}}
+
### User List
Enables the feature for lists of users created [in the feature flags UI](#create-a-user-list), or with the [feature flag user list API](../api/feature_flag_user_lists.md).
@@ -171,8 +186,8 @@ To create a user list:
1. Enter a name for the list.
1. Select **Create**.
-You can view a list's User IDs by selecting **Edit** (**{pencil}**) next to it.
-When viewing a list, you can rename it by selecting **Edit** (**{pencil}**).
+You can view a list's User IDs by selecting **Edit** ({{< icon name="pencil" >}}) next to it.
+When viewing a list, you can rename it by selecting **Edit** ({{< icon name="pencil" >}}).
#### Add users to a user list
@@ -180,7 +195,7 @@ To add users to a user list:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Feature flags**.
-1. Select **Edit** (**{pencil}**) next to the list you want to add users to.
+1. Select **Edit** ({{< icon name="pencil" >}}) next to the list you want to add users to.
1. Select **Add Users**.
1. Enter the user IDs as a comma-separated list of values. For example,
`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on.
@@ -192,14 +207,17 @@ To remove users from a user list:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Feature flags**.
-1. Select **Edit** (**{pencil}**) next to the list you want to change.
-1. Select **Remove** (**{remove}**) next to the ID you want to remove.
+1. Select **Edit** ({{< icon name="pencil" >}}) next to the list you want to change.
+1. Select **Remove** ({{< icon name="remove" >}}) next to the ID you want to remove.
## Search for Code References
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To remove the feature flag from the code during cleanup, find any project references to it.
@@ -208,7 +226,7 @@ To search for code references of a feature flag:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Feature flags**.
1. Edit the feature flag you want to remove.
-1. Select **More actions** (**{ellipsis_v}**).
+1. Select **More actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Search code references**.
## Disable a feature flag for a specific environment
@@ -217,7 +235,7 @@ To disable a feature flag for a specific environment:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Feature flags**.
-1. For the feature flag you want to disable, select **Edit** (**{pencil}**).
+1. For the feature flag you want to disable, select **Edit** ({{< icon name="pencil" >}}).
1. To disable the flag:
- For each strategy it applies to, under **Environments**, delete the environment.
1. Select **Save changes**.
@@ -379,9 +397,12 @@ this to GitLab on behalf of the client, which means the client can't override it
## Feature flag related issues
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can link related issues to a feature flag. In the feature flag **Linked issues** section,
select the `+` button and input the issue reference number or the full URL of the issue.
diff --git a/doc/operations/incident_management/_index.md b/doc/operations/incident_management/_index.md
index fddec9cb0887d4e3d0057ec792222bc7422c25f1..01f68ec6440d0288a9a2e4384685d6f96111cdaf 100644
--- a/doc/operations/incident_management/_index.md
+++ b/doc/operations/incident_management/_index.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Incident management
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is not under active development, but [community contributions](https://about.gitlab.com/community/contribute/) are welcome.
For more information, see [issue 468607](https://gitlab.com/gitlab-org/gitlab/-/issues/468607#note_1967939452).
To determine if the feature meets your needs, see the [open bug issues](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=updated_desc&state=opened&label_name%5B%5D=Category%3AIncident%20Management&label_name%5B%5D=type%3A%3Abug&first_page_size=20).
+{{< /alert >}}
+
Incident Management enables developers to easily triage and view the alerts and incidents
generated by their application. By surfacing alerts and incidents where the code is
being developed, efficiency and awareness can be increased. Check out the following sections for more information:
diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md
index f7d11efc42e2b577094764fcdb8b3470828341b7..d6ed1271d2eb66fdd5449c4b40ff66af8f106e75 100644
--- a/doc/operations/incident_management/alerts.md
+++ b/doc/operations/incident_management/alerts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Alerts
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Alerts are a critical entity in your incident management workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened.
@@ -48,12 +51,12 @@ Alerts contain one of the following icons:
| Severity | Icon | Color (hexadecimal) |
|----------|-------------------------|---------------------|
-| Critical | **{severity-critical}** | `#8b2615` |
-| High | **{severity-high}** | `#c0341d` |
-| Medium | **{severity-medium}** | `#fca429` |
-| Low | **{severity-low}** | `#fdbc60` |
-| Info | **{severity-info}** | `#418cd8` |
-| Unknown | **{severity-unknown}** | `#bababa` |
+| Critical | {{< icon name="severity-critical" >}} | `#8b2615` |
+| High | {{< icon name="severity-high" >}} | `#c0341d` |
+| Medium | {{< icon name="severity-medium" >}} | `#fca429` |
+| Low | {{< icon name="severity-low" >}} | `#fdbc60` |
+| Info | {{< icon name="severity-info" >}} | `#418cd8` |
+| Unknown | {{< icon name="severity-unknown" >}} | `#bababa` |
<!-- vale gitlab_base.SubstitutionWarning = YES -->
@@ -137,9 +140,12 @@ When you [close an incident](manage_incidents.md#close-an-incident) that is link
#### As an on-call responder
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
On-call responders can respond to [alert pages](paging.md#escalating-an-alert) by changing the alert status.
@@ -167,7 +173,7 @@ To assign an alert:
1. If the right sidebar is not expanded, select
- **Expand sidebar** (**{chevron-double-lg-right}**) to expand it.
+ **Expand sidebar** ({{< icon name="chevron-double-lg-right" >}}) to expand it.
1. On the right sidebar, locate the **Assignee**, and then select **Edit**.
From the list, select each user you want to assign to the alert.
@@ -183,9 +189,12 @@ To add a to-do item, on the right sidebar, select **Add a to-do item**.
### Trigger actions from alerts
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Turn on creating [incidents](incidents.md) automatically whenever an alert is triggered.
diff --git a/doc/operations/incident_management/escalation_policies.md b/doc/operations/incident_management/escalation_policies.md
index 92254ddf885aacbb2447556a8923f2feb3ec5083..7677dd61635f92ad19a1741bb28c048855ce4b9b 100644
--- a/doc/operations/incident_management/escalation_policies.md
+++ b/doc/operations/incident_management/escalation_policies.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Escalation policies
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Escalation policies protect your company from missed critical alerts. Escalation policies contain
time-boxed steps that automatically page the next responder in the escalation step if the responder
@@ -51,7 +54,7 @@ To update an escalation policy:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Monitor > Escalation Policies**.
-1. Select **Edit escalation policy** (**{pencil}**).
+1. Select **Edit escalation policy** ({{< icon name="pencil" >}}).
1. Edit the information.
1. Select **Save changes**.
@@ -61,5 +64,5 @@ To delete an escalation policy:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Monitor > Escalation Policies**.
-1. Select **Delete escalation policy** (**{remove}**).
+1. Select **Delete escalation policy** ({{< icon name="remove" >}}).
1. On the confirmation dialog, select **Delete escalation policy**.
diff --git a/doc/operations/incident_management/incident_timeline_events.md b/doc/operations/incident_management/incident_timeline_events.md
index c2b20f00340c3ca2b383c91c24851c103b35a3f4..afe7b68444306f4afc6413784c2180dfe4349943 100644
--- a/doc/operations/incident_management/incident_timeline_events.md
+++ b/doc/operations/incident_management/incident_timeline_events.md
@@ -5,9 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Timeline events
---
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344059) in GitLab 15.2 [with a flag](../../administration/feature_flags.md) named `incident_timeline`. Enabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353426) in GitLab 15.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/353426) in GitLab 15.5. [Feature flag `incident_timeline`](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344059) in GitLab 15.2 [with a flag](../../administration/feature_flags.md) named `incident_timeline`. Enabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353426) in GitLab 15.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/353426) in GitLab 15.5. [Feature flag `incident_timeline`](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) removed.
+
+{{< /history >}}
Incident timelines are an important part of record keeping for incidents.
Timelines can show executives and external viewers what happened during an incident,
@@ -51,13 +55,21 @@ To create a timeline event:
### Using a quick action
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4.
+
+{{< /history >}}
You can create a timeline event using the `/timeline` [quick action](../../user/project/quick_actions.md).
### From a comment on the incident
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344058) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344058) in GitLab 15.4.
+
+{{< /history >}}
Prerequisites:
@@ -69,13 +81,17 @@ To create a timeline event from a comment on the incident:
1. Select **Monitor > Incidents**.
1. Select an incident.
1. Create a comment or choose an existing comment.
-1. On the comment you want to add, select **Add comment to incident timeline** (**{clock}**).
+1. On the comment you want to add, select **Add comment to incident timeline** ({{< icon name="clock" >}}).
The comment is shown on the incident timeline as a timeline event.
### When incident severity changes
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375280) in GitLab 15.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375280) in GitLab 15.6.
+
+{{< /history >}}
A new timeline event is created when someone [changes the severity](manage_incidents.md#change-severity)
of an incident.
@@ -84,21 +100,35 @@ of an incident.
### When labels change
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365489) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `incident_timeline_events_from_labels`. Disabled by default.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365489) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `incident_timeline_events_from_labels`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
A new timeline event is created when someone adds or removes [labels](../../user/project/labels.md) on an incident.
## Delete an event
-> - Ability to delete an event when editing it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372265) in GitLab 15.7.
+{{< history >}}
+
+- Ability to delete an event when editing it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372265) in GitLab 15.7.
+
+{{< /history >}}
You can also delete timeline events.
@@ -112,21 +142,25 @@ To delete a timeline event:
1. Select **Monitor > Incidents**.
1. Select an incident.
1. Select the **Timeline** tab.
-1. On the right of a timeline event, select **More actions** (**{ellipsis_v}**) and then select **Delete**.
+1. On the right of a timeline event, select **More actions** ({{< icon name="ellipsis_v" >}}) and then select **Delete**.
1. To confirm, select **Delete Event**.
Alternatively:
-1. On the right of a timeline event, select **More actions** (**{ellipsis_v}**) and then select **Edit**.
+1. On the right of a timeline event, select **More actions** ({{< icon name="ellipsis_v" >}}) and then select **Edit**.
1. Select **Delete**.
1. To confirm, select **Delete event**.
## Incident tags
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8741) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `incident_event_tags`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/387647) in GitLab 15.9.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/387647) in GitLab 15.10.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/387647) in GitLab 15.11. Feature flag `incident_event_tags` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8741) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `incident_event_tags`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/387647) in GitLab 15.9.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/387647) in GitLab 15.10.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/387647) in GitLab 15.11. Feature flag `incident_event_tags` removed.
+
+{{< /history >}}
[When creating an event using the form](#using-the-form) or editing it,
you can specify incident tags to capture relevant incident timestamps.
diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md
index 7ae557c4aff0233318ddf0894ad0a4dfe673c73c..513292c8ae1548f759866356fe81a454953f105d 100644
--- a/doc/operations/incident_management/incidents.md
+++ b/doc/operations/incident_management/incidents.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Incidents
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
An incident is a service disruption or outage that needs to be restored urgently.
Incidents are critical in incident management workflows.
@@ -23,11 +26,11 @@ When you [view the incidents list](manage_incidents.md#view-a-list-of-incidents)
- **Severity**: Severity of a particular incident, which can be one of the following
values:
- - **{severity-critical}** Critical - S1
- - **{severity-high}** High - S2
- - **{severity-medium}** Medium - S3
- - **{severity-low}** Low - S4
- - **{severity-unknown}** Unknown
+ - {{< icon name="severity-critical" >}} Critical - S1
+ - {{< icon name="severity-high" >}} High - S2
+ - {{< icon name="severity-medium" >}} Medium - S3
+ - {{< icon name="severity-low" >}} Low - S4
+ - {{< icon name="severity-unknown" >}} Unknown
- **Incident**: The title of the incident, which attempts to capture the
most meaningful information.
@@ -100,9 +103,12 @@ displays them below the summary.
### Metrics
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In many cases, incidents are associated to metrics. You can upload screenshots of metric
charts in the **Metrics** tab:
@@ -133,19 +139,25 @@ Read more about [timeline events](incident_timeline_events.md) and how to enable
### Recent updates view
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To see the latest updates on an incident, select
-**Turn recent updates view on** (**{history}**) on the comment bar. Comments display
+**Turn recent updates view on** ({{< icon name="history" >}}) on the comment bar. Comments display
un-threaded and chronologically, newest to oldest.
### Service Level Agreement countdown timer
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can enable the Service Level Agreement Countdown timer on incidents to track
the Service Level Agreements (SLA) you hold with your customers. The timer is
diff --git a/doc/operations/incident_management/integrations.md b/doc/operations/incident_management/integrations.md
index a6b338faf1a4cc6a40b57d015796d0c357e0804a..080771276f0ea1667b3c03562edf1c50520f7b15 100644
--- a/doc/operations/incident_management/integrations.md
+++ b/doc/operations/incident_management/integrations.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Integrations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab can accept alerts from any source via a webhook receiver. [Alert notifications](alerts.md)
can [trigger paging](paging.md#paging) for on-call rotations or be used to [create incidents](manage_incidents.md#from-an-alert).
@@ -42,9 +45,12 @@ receive alert payloads in JSON format. You can always
### HTTP Endpoints
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In [GitLab Premium](https://about.gitlab.com/pricing/), you can create multiple
unique HTTP endpoints to receive alerts from any external source in JSON format,
@@ -72,7 +78,7 @@ and you can [customize the payload](#customize-the-alert-payload-outside-of-gitl
from your integration's **Send test alert** tab after the integration is created.
The new HTTP Endpoint displays in the [integrations list](#integrations-list).
-You can edit the integration by selecting the **{settings}** settings icon on the right
+You can edit the integration by selecting the {{< icon name="settings" >}} settings icon on the right
side of the integrations list.
#### Map fields in custom alerts
@@ -110,10 +116,13 @@ can be a nested JSON object. For example:
{ "foo": { "bar": { "baz": 42 } } }
```
-NOTE:
+{{< alert type="note" >}}
+
Ensure your requests are smaller than the
[payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads).
+{{< /alert >}}
+
### Example request body
Example payload:
@@ -228,10 +237,13 @@ can be a nested JSON object. For example:
}
```
-NOTE:
+{{< alert type="note" >}}
+
Ensure your requests are smaller than the
[payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads).
+{{< /alert >}}
+
#### Prometheus severity options
Alerts from Prometheus can provide any of the case-insensitive follow values for [alert severity](../incident_management/alerts.md#alert-severity):
@@ -348,10 +360,13 @@ curl --request POST \
<username:password@url>
```
-WARNING:
+{{< alert type="warning" >}}
+
Using your authorization key in the URL is insecure, as it's visible in server logs. We recommend
using one of the above header options if your tooling supports it.
+{{< /alert >}}
+
## Response body
The JSON response body contains a list of any alerts created within the request:
@@ -380,7 +395,7 @@ alert to confirm your integration works properly.
1. Sign in as a user with at least the Developer role.
1. Go to **Settings > Monitor** in your project.
1. Select **Alerts** to expand the section.
-1. Select the **{settings}** settings icon on the right side of the integration in [the list](#integrations-list).
+1. Select the {{< icon name="settings" >}} settings icon on the right side of the integration in [the list](#integrations-list).
1. Select the **Send test alert** tab to open it.
1. Enter a test payload in the payload field (valid JSON is required).
1. Select **Send**.
@@ -389,9 +404,12 @@ GitLab displays an error or success message, depending on the outcome of your te
## Automatic grouping of identical alerts
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab groups alerts based on their payload. When an incoming alert contains the same payload as another alert
(excluding the `start_time` and `hosts` attributes), GitLab groups these alerts
@@ -418,17 +436,27 @@ You can also configure the associated [incident to be closed automatically](../i
## Link to your Opsgenie Alerts
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.2.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
We are building deeper integration with Opsgenie and other alerting tools through
[HTTP endpoint integrations](#single-http-endpoint) so you can see alerts in
the GitLab interface.
+{{< /alert >}}
+
You can monitor alerts using a GitLab integration with [Opsgenie](https://www.atlassian.com/software/opsgenie).
If you enable the Opsgenie integration, you can't have other GitLab alert
diff --git a/doc/operations/incident_management/linked_resources.md b/doc/operations/incident_management/linked_resources.md
index 0becb34ec53706ccdce6be31cbe6822af2c2f03c..d62070ec83ddaaf47a45c061f4ac2d2c02d5c043 100644
--- a/doc/operations/incident_management/linked_resources.md
+++ b/doc/operations/incident_management/linked_resources.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Linked resources in incidents
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230852) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `incident_resource_links_widget`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364755) in GitLab 15.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/364755) in GitLab 15.5. Feature flag `incident_resource_links_widget` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230852) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `incident_resource_links_widget`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364755) in GitLab 15.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/364755) in GitLab 15.5. Feature flag `incident_resource_links_widget` removed.
+
+{{< /history >}}
To help your team members find the important links without having to search through many comments,
you can add linked resources to an incident issue.
@@ -47,13 +54,17 @@ To add a linked resource:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Monitor > Incidents**.
1. Select an incident.
-1. In the **Linked resources** section, select the plus icon (**{plus-square}**).
+1. In the **Linked resources** section, select the plus icon ({{< icon name="plus-square" >}}).
1. Complete the required fields.
1. Select **Add**.
### Using a quick action
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5.
+
+{{< /history >}}
To add multiple links to an incident, use the `/link`
[quick action](../../user/project/quick_actions.md):
@@ -71,7 +82,11 @@ The description shows instead of the URL in the **Linked resources** section of
### Link Zoom meetings from an incident
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) in GitLab 15.4.
+
+{{< /history >}}
Use the `/zoom` [quick action](../../user/project/quick_actions.md) to add multiple Zoom links to an incident:
@@ -98,4 +113,4 @@ To remove a linked resource:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Monitor > Incidents**.
1. Select an incident.
-1. In the **Linked resources** section, select **Remove** (**{close}**).
+1. In the **Linked resources** section, select **Remove** ({{< icon name="close" >}}).
diff --git a/doc/operations/incident_management/manage_incidents.md b/doc/operations/incident_management/manage_incidents.md
index b9dba640fd9e800d92a8ce5ddc401fa57ed46848..934f904506364a8aba9a441d01247c4e97e5716b 100644
--- a/doc/operations/incident_management/manage_incidents.md
+++ b/doc/operations/incident_management/manage_incidents.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Manage incidents
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Ability to add an [incident](_index.md) to an iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347153) in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Ability to add an [incident](_index.md) to an iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347153) in GitLab 17.0.
+
+{{< /history >}}
This page collects instructions for all the things you can do with [incidents](incidents.md) or in relation to them.
@@ -19,9 +26,12 @@ You can create an incident manually or automatically.
## Add an incident to an iteration
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To add an incident to an [iteration](../../user/group/iterations/_index.md):
@@ -83,16 +93,23 @@ You are then credited with the alert's status change.
### Automatically, when an alert is triggered
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In the project settings, you can turn on [creating an incident automatically](alerts.md#trigger-actions-from-alerts)
whenever an alert is triggered.
### Using the PagerDuty webhook
-> - [PagerDuty V3 Webhook](https://support.pagerduty.com/docs/webhooks) support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383029) in GitLab 15.7.
+{{< history >}}
+
+- [PagerDuty V3 Webhook](https://support.pagerduty.com/docs/webhooks) support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383029) in GitLab 15.7.
+
+{{< /history >}}
You can set up a webhook with PagerDuty to automatically create a GitLab incident
for each PagerDuty incident. This configuration requires you to make changes
@@ -127,7 +144,11 @@ To view an incident's [details page](incidents.md#incident-details), select it f
### Who can view an incident
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Whether you can view an incident depends on the [project visibility level](../../user/public_access.md) and
the incident's confidentiality status:
@@ -167,9 +188,13 @@ You can also change the severity using the `/severity` [quick action](../../user
## Change status
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5716) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `incident_escalations`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/345769) in GitLab 14.10.
-> - [Feature flag `incident_escalations`](https://gitlab.com/gitlab-org/gitlab/-/issues/345769) removed in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5716) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `incident_escalations`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/345769) in GitLab 14.10.
+- [Feature flag `incident_escalations`](https://gitlab.com/gitlab-org/gitlab/-/issues/345769) removed in GitLab 15.1.
+
+{{< /history >}}
Prerequisites:
@@ -184,9 +209,12 @@ To change the status of an incident:
### As an on-call responder
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
On-call responders can respond to [incident pages](paging.md#escalating-an-incident)
by changing the status.
@@ -203,9 +231,12 @@ the alert status is independent and does not change when the incident status cha
## Change escalation policy
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
@@ -231,7 +262,7 @@ Prerequisites:
- You must have at least the Reporter role for the project.
-To close an incident, in the upper-right corner, select **Incident actions** (**{ellipsis_v}**) and then **Close incident**.
+To close an incident, in the upper-right corner, select **Incident actions** ({{< icon name="ellipsis_v" >}}) and then **Close incident**.
When you close an incident that is linked to an [alert](alerts.md),
the linked alert's status changes to **Resolved**.
@@ -266,12 +297,12 @@ Prerequisites:
To delete an incident:
-1. In an incident, select **Incident actions** (**{ellipsis_v}**).
+1. In an incident, select **Incident actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Delete incident**.
Alternatively:
-1. In an incident, select **Edit title and description** (**{pencil}**).
+1. In an incident, select **Edit title and description** ({{< icon name="pencil" >}}).
1. Select **Delete incident**.
## Other actions
diff --git a/doc/operations/incident_management/oncall_schedules.md b/doc/operations/incident_management/oncall_schedules.md
index dfe5e1b4f2bb9baee5802ebb34466da2357fea23..de3d696044496540d296851de53f9555bc50064e 100644
--- a/doc/operations/incident_management/oncall_schedules.md
+++ b/doc/operations/incident_management/oncall_schedules.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: On-call Schedule Management
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use on-call schedule management to create schedules for responders to rotate on-call
responsibilities. Maintain the availability of your software services by putting your teams on-call.
@@ -46,7 +49,7 @@ To update a schedule:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Monitor > On-call Schedules**.
-1. Select **Edit schedule** (**{pencil}**).
+1. Select **Edit schedule** ({{< icon name="pencil" >}}).
1. Edit the information.
1. Select **Save changes**.
@@ -59,7 +62,7 @@ To delete a schedule:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Monitor > On-call Schedules**.
-1. Select **Delete escalation policy** (**{remove}**).
+1. Select **Delete escalation policy** ({{< icon name="remove" >}}).
1. On the confirmation dialog, select **Delete schedule**.
## Rotations
@@ -88,7 +91,7 @@ To edit a rotation:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Monitor > On-call Schedules**.
-1. In the **Rotations** section, select **Edit rotation** (**{pencil}**).
+1. In the **Rotations** section, select **Edit rotation** ({{< icon name="pencil" >}}).
1. Edit the information.
1. Select **Save changes**.
@@ -98,7 +101,7 @@ To delete a rotation:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Monitor > On-call Schedules**.
-1. In the **Rotations** section, select **Delete rotation** (**{remove}**).
+1. In the **Rotations** section, select **Delete rotation** ({{< icon name="remove" >}}).
1. On the confirmation dialog, select **Delete rotation**.
## View schedule rotations
diff --git a/doc/operations/incident_management/paging.md b/doc/operations/incident_management/paging.md
index 93341d1554ab67717a8a0f9d6bcf833a1056acf4..a46fb07b54b97b0520854063bd097e465fa0d20e 100644
--- a/doc/operations/incident_management/paging.md
+++ b/doc/operations/incident_management/paging.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Paging and notifications
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When there is a new alert or incident, it is important for a responder to be notified
immediately so they can triage and respond to the problem. Responders can receive
@@ -38,9 +41,12 @@ a single email notification for new alerts.
## Paging
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In projects that have an [escalation policy](escalation_policies.md) configured, on-call responders
can be automatically paged about critical problems through email.
@@ -54,9 +60,13 @@ or stop alert escalations by [updating the alert's status](alerts.md#change-an-a
### Escalating an incident
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5716) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `incident_escalations`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/345769) in GitLab 14.10.
-> - [Feature flag `incident_escalations`](https://gitlab.com/gitlab-org/gitlab/-/issues/345769) removed in GitLab 15.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5716) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `incident_escalations`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/345769) in GitLab 14.10.
+- [Feature flag `incident_escalations`](https://gitlab.com/gitlab-org/gitlab/-/issues/345769) removed in GitLab 15.1.
+
+{{< /history >}}
For incidents, paging on-call responders is optional for each individual incident.
diff --git a/doc/operations/incident_management/slack.md b/doc/operations/incident_management/slack.md
index 9e384b504c90dc92404346d880b18364c69b093f..efa4cb971f2206fc93b788d6dc922433cae67398 100644
--- a/doc/operations/incident_management/slack.md
+++ b/doc/operations/incident_management/slack.md
@@ -5,19 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Incident management for Slack
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344856) in GitLab 15.7 [with a flag](../../administration/feature_flags.md) named `incident_declare_slash_command`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/378072) in GitLab 15.10 in [beta](../../policy/development_stages_support.md#beta).
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344856) in GitLab 15.7 [with a flag](../../administration/feature_flags.md) named `incident_declare_slash_command`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/378072) in GitLab 15.10 in [beta](../../policy/development_stages_support.md#beta).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Many teams receive alerts and collaborate in real time during incidents in Slack.
Use the GitLab for Slack app to:
diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md
index fdc348f0c9fb6b8b02ac55c5aeaabc009de9f364..b26940a4a28f2887b9ede020303c68db6ea3598a 100644
--- a/doc/operations/incident_management/status_page.md
+++ b/doc/operations/incident_management/status_page.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Status Page
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With a GitLab Status Page, you can create and deploy a static website to communicate
efficiently to users during an incident. The Status Page landing page displays an
@@ -88,10 +91,13 @@ the necessary CI/CD variables to deploy the Status Page to AWS S3:
1. On the left sidebar, select **Build > Pipelines**.
1. To deploy the Status Page to S3, select **New pipeline**.
-WARNING:
+{{< alert type="warning" >}}
+
Consider limiting who can access issues in this project, as any user who can view
the issue can potentially [publish comments to your GitLab Status Page](#publish-comments-on-incidents).
+{{< /alert >}}
+
### Sync incidents to the Status Page
After creating the CI/CD variables, configure the Project you want to use for
@@ -153,10 +159,13 @@ After publication, you can access the incident's details page by selecting the
To publish an update to the Incident, update the incident issue's description.
-WARNING:
+{{< alert type="warning" >}}
+
When referenced issues are changed (such as title or confidentiality) the incident
they were referenced in is not updated.
+{{< /alert >}}
+
### Publish comments on incidents
To publish comments to the Status Page Incident:
@@ -167,10 +176,13 @@ To publish comments to the Status Page Incident:
reaction (`:microphone:` 🎤) to the comment.
- Any files attached to the comment (up to 5000 per issue) are also published.
-WARNING:
+{{< alert type="warning" >}}
+
Anyone with access to view the Issue can add an emoji reaction to a comment, so
consider limiting access to issues to team members only.
+{{< /alert >}}
+
### Update the incident status
To change the incident status from `open` to `closed`, close the incident issue
diff --git a/doc/operations/integrated_error_tracking.md b/doc/operations/integrated_error_tracking.md
index aad9d40db1057a2213cd850d047e32cf3805f2a9..a16f586f5df850dea434b6117695e4398393f074 100644
--- a/doc/operations/integrated_error_tracking.md
+++ b/doc/operations/integrated_error_tracking.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Integrated error tracking
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
This guide provides basic information on how to set up integrated error tracking for
your project, using examples from different languages.
@@ -72,7 +75,7 @@ those errors are available in the GitLab UI. To view them:
- Total number of occurrences.
- Total users affected.
- - First seen: the date and commit (**{commit}**).
+ - First seen: the date and commit ({{< icon name="commit" >}}).
- Last seen date, shown as a relative date. To view the timestamp, hover over the date.
- A bar graph of error frequency per hour. To view the total number of errors in a specific hour, hover over a bar.
- A stack trace.
@@ -128,9 +131,12 @@ For more information, see the [Sentry SDK documentation](https://docs.sentry.io/
## Rotate generated DSN
-WARNING:
+{{< alert type="warning" >}}
+
According to Sentry [it is safe to keep a DSN public](https://docs.sentry.io/concepts/key-terms/dsn-explainer/#dsn-utilization), but this opens up the possibility of junk events being sent to Sentry by malicious users. Therefore if possible you should keep the DSN secret. This doesn't apply to client-side applications where the DSN will be loaded and therefore stored on the user's device.
+{{< /alert >}}
+
Prerequisites:
- You need the numeric [project ID](../user/project/working_with_projects.md#access-a-project-by-using-the-project-id)
diff --git a/doc/operations/logs.md b/doc/operations/logs.md
index a0b906c911de2f17d43ff9b0600ad8400b223738..1e76df3c65a54d7bd4afe774b03497ca69b03bf3 100644
--- a/doc/operations/logs.md
+++ b/doc/operations/logs.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../development/logs.md'
-remove_date: '2025-03-10'
+redirect_to: ../development/logs.md
+remove_date: "2025-03-10"
---
<!-- markdownlint-disable -->
diff --git a/doc/operations/metrics.md b/doc/operations/metrics.md
index 5d0f6a0c4a4be1ce273b6476b8e6ddb692448798..edef8048571e997d552c10f7058ed6dfca6a0b0b 100644
--- a/doc/operations/metrics.md
+++ b/doc/operations/metrics.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../development/metrics.md'
-remove_date: '2025-03-10'
+redirect_to: ../development/metrics.md
+remove_date: "2025-03-10"
---
<!-- markdownlint-disable -->
diff --git a/doc/operations/product_analytics/_index.md b/doc/operations/product_analytics/_index.md
index c4c5d3ce2cd25f606cd1974950d390484059b88b..5c105896b88a93c6282590dc7be19ce9317e0e3b 100644
--- a/doc/operations/product_analytics/_index.md
+++ b/doc/operations/product_analytics/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../../development/internal_analytics/product_analytics.md'
-remove_date: '2025-03-20'
+redirect_to: ../../development/internal_analytics/product_analytics.md
+remove_date: "2025-03-20"
---
<!-- markdownlint-disable -->
diff --git a/doc/operations/product_analytics/instrumentation/_index.md b/doc/operations/product_analytics/instrumentation/_index.md
index 7c45fa874048e5aa09c7ed65cd3617e5c12570c3..f2478aee08143161c2f6e6a79e0faad06488d033 100644
--- a/doc/operations/product_analytics/instrumentation/_index.md
+++ b/doc/operations/product_analytics/instrumentation/_index.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../../../development/internal_analytics/_index.md'
-remove_date: '2025-04-17'
+redirect_to: ../../../development/internal_analytics/_index.md
+remove_date: "2025-04-17"
---
<!-- markdownlint-disable -->
diff --git a/doc/operations/product_analytics/instrumentation/browser_sdk.md b/doc/operations/product_analytics/instrumentation/browser_sdk.md
index bef34bb448f9e1535908f5f125fc153a668ccaab..c694539aaaaa24d3368a43d96113372eab7970c2 100644
--- a/doc/operations/product_analytics/instrumentation/browser_sdk.md
+++ b/doc/operations/product_analytics/instrumentation/browser_sdk.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../../../development/internal_analytics/browser_sdk.md'
-remove_date: '2025-04-17'
+redirect_to: ../../../development/internal_analytics/browser_sdk.md
+remove_date: "2025-04-17"
---
<!-- markdownlint-disable -->
diff --git a/doc/operations/sentry_error_tracking.md b/doc/operations/sentry_error_tracking.md
index 1bcdff2f19c06461b8bf58abde92bdba50280316..0a657f76d8331a5387a8c887b917b0ea6bd7f7a8 100644
--- a/doc/operations/sentry_error_tracking.md
+++ b/doc/operations/sentry_error_tracking.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sentry error tracking
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Sentry](https://sentry.io/) is an open source error tracking system. GitLab enables
administrators to connect Sentry to GitLab, so users can view a list of Sentry errors in GitLab.
diff --git a/doc/operations/tracing.md b/doc/operations/tracing.md
index 43b6e423525bef51de4a45035c74d62822bcb362..d359a1ff334dbde1911514f1de3532dd075bd996 100644
--- a/doc/operations/tracing.md
+++ b/doc/operations/tracing.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../development/tracing.md'
-remove_date: '2025-03-10'
+redirect_to: ../development/tracing.md
+remove_date: "2025-03-10"
---
<!-- markdownlint-disable -->
diff --git a/doc/policy/development_stages_support.md b/doc/policy/development_stages_support.md
index a254abddc8fabaa1867ffd88685cc5abdcc7086c..0da9db6275bc85ac2edac4458e6b881f117ef2fe 100644
--- a/doc/policy/development_stages_support.md
+++ b/doc/policy/development_stages_support.md
@@ -1,8 +1,8 @@
---
stage: Systems
group: Distribution
-description: Support details.
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
+description: Support details.
title: Support for features in different stages of development
---
diff --git a/doc/policy/early_access_program/_index.md b/doc/policy/early_access_program/_index.md
index 1a576352987762f35eaf4b73ce42ec8a99650a43..ca8bed28ed6aff814c2a132ef77be508e3f04c01 100644
--- a/doc/policy/early_access_program/_index.md
+++ b/doc/policy/early_access_program/_index.md
@@ -2,13 +2,15 @@
stage: none
group: Contributor Success
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
-ignore_in_report: true
title: GitLab Early Access Program
---
-NOTE:
+{{< alert type="note" >}}
+
Last status update 2024-10-02.
+{{< /alert >}}
+
These features may not be ready for production use and follow the [Experimental or Beta policy](../development_stages_support.md) of GitLab.
## Features included in the GitLab Early Access Program
diff --git a/doc/policy/experiment-beta-support.md b/doc/policy/experiment-beta-support.md
index 4224897e5c801e9954c67de0c3d6d717f1302594..63c18749c80343d7cc6c95e120fdf49e1d1a01d1 100644
--- a/doc/policy/experiment-beta-support.md
+++ b/doc/policy/experiment-beta-support.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'development_stages_support.md'
-remove_date: '2025-02-27'
+redirect_to: development_stages_support.md
+remove_date: "2025-02-27"
---
<!-- markdownlint-disable -->
diff --git a/doc/raketasks/_index.md b/doc/raketasks/_index.md
index 8055d122641482ff789ff5dd2846ccdc1cb46b3c..d95a3c4fd6b7fbfc9c5c3026978b5dac4aaa1075 100644
--- a/doc/raketasks/_index.md
+++ b/doc/raketasks/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides [Rake](https://ruby.github.io/rake/) tasks to assist you with common administration and operational
processes.
diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md
index bf9bf803b57127d3da51aa5c800681a8bc61ca3b..2aa48f69f291e11317cf08a593c2526590d45737 100644
--- a/doc/raketasks/cleanup.md
+++ b/doc/raketasks/cleanup.md
@@ -5,18 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Clean up Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides Rake tasks for cleaning up GitLab instances.
## Remove unreferenced LFS files
-WARNING:
+{{< alert type="warning" >}}
+
Do not run this within 12 hours of a GitLab upgrade. This is to ensure that all background migrations
have finished, which otherwise may lead to data loss.
+{{< /alert >}}
+
When you remove LFS files from a repository's history, they become orphaned and continue to consume
disk space. With this Rake task, you can remove invalid references from the database, which
allows garbage collection of LFS files.
@@ -143,10 +149,13 @@ I, [2018-08-02T10:26:47.764356 #45087] INFO -- : Moved to lost and found: @hash
## Remove orphan artifact files
-NOTE:
+{{< alert type="note" >}}
+
These commands don't work for artifacts stored on
[object storage](../administration/object_storage.md).
+{{< /alert >}}
+
When you notice there are more job artifacts files and/or directories on disk than there
should be, you can run:
diff --git a/doc/raketasks/spdx.md b/doc/raketasks/spdx.md
index 755fcf0f16debccbaadc62879b5f2a27bba54fa7..b027b97355123543999ce2b0c0dc7a4b22a1e344 100644
--- a/doc/raketasks/spdx.md
+++ b/doc/raketasks/spdx.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: SPDX license list import Rake task
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides a Rake task for uploading a fresh copy of the [SPDX license list](https://spdx.org/licenses/)
to a GitLab instance. This list is needed for matching the names of [License approval policies](../user/compliance/license_approval_policies.md).
diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md
index 3db4be5e788690780ab0055b2154376b829e2b0b..e97f535869d509c88601009096d24472febed861 100644
--- a/doc/raketasks/user_management.md
+++ b/doc/raketasks/user_management.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User management Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides Rake tasks for managing users. Administrators can also use the **Admin** area to
[manage users](../administration/admin_area.md#administering-users).
@@ -183,11 +186,18 @@ sudo /etc/init.d/gitlab start
## Bulk assign users to GitLab Duo Pro
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142189) in GitLab 16.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142189) in GitLab 16.9.
+{{< /history >}}
The Rake task for bulk user assignment is available in GitLab 16.9 and later. For GitLab 16.8, use the script [`bulk_user_assignment.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/duo_pro/bulk_user_assignment.rb) instead.
diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md
index b854c8b01f4af0df561aad2d2914fde6baaa0335..369dbda90d608161d528e2ab7bae3c6ac2be8df8 100644
--- a/doc/raketasks/web_hooks.md
+++ b/doc/raketasks/web_hooks.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Webhook administration Rake tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
GitLab provides Rake tasks for webhooks management.
diff --git a/doc/raketasks/x509_signatures.md b/doc/raketasks/x509_signatures.md
index 021a5ff797a3dafcb6d15d127ea8663766498e6c..88fba390d5b72aaceb847a6fd5ca00a137aa35d5 100644
--- a/doc/raketasks/x509_signatures.md
+++ b/doc/raketasks/x509_signatures.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: X.509 signatures Rake task
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When [signing commits with X.509](../user/project/repository/signed_commits/x509.md),
the trust anchor might change and the signatures stored in the database must be updated.
@@ -23,18 +26,22 @@ This task:
To update all X.509 signatures, run:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake gitlab:x509:update_signatures
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
sudo -u git -H bundle exec rake gitlab:x509:update_signatures RAILS_ENV=production
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/security/_index.md b/doc/security/_index.md
index df8b0f3fa8a8d5d26cd602df1c7802b77642ffd1..b86b93c9c27064f903735c080292f660a160dfe2 100644
--- a/doc/security/_index.md
+++ b/doc/security/_index.md
@@ -1,14 +1,17 @@
---
stage: Software Supply Chain Security
group: Authentication
-description: SSH key limits, 2FA, tokens, hardening.
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
+description: SSH key limits, 2FA, tokens, hardening.
title: Secure GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## General information
diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md
index d41265e99f96ef8c04c3561df7cb75901f16c966..af255fd6ecbc517c505ffb4d43a7de0efa5b53cf 100644
--- a/doc/security/asset_proxy.md
+++ b/doc/security/asset_proxy.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Proxying assets
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A possible security concern when managing a public-facing GitLab instance is
the ability to steal a user's IP address by referencing images in issues and comments.
diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md
index d44904f7ec2dec88fc1b142cd9c689bd32754c2f..5bdc0f3edaed059220fdd66064aa96ea5eda94bc 100644
--- a/doc/security/crime_vulnerability.md
+++ b/doc/security/crime_vulnerability.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: How we manage the TLS protocol CRIME vulnerability
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
[CRIME](https://en.wikipedia.org/w/index.php?title=CRIME&oldid=692423806) is a security exploit against
secret web cookies over connections using the HTTPS and SPDY protocols that also
diff --git a/doc/security/email_verification.md b/doc/security/email_verification.md
index 79ad284883a4dd54b0606610b3c2f24d1daf5738..63784470fd959e2f327aa5c25bc9c2c97a1dc182 100644
--- a/doc/security/email_verification.md
+++ b/doc/security/email_verification.md
@@ -5,15 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Account email verification
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86352) in GitLab 15.2 [with a flag](../administration/feature_flags.md) named `require_email_verification`. Disabled by default.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86352) in GitLab 15.2 [with a flag](../administration/feature_flags.md) named `require_email_verification`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `require_email_verification`. On GitLab.com and GitLab Dedicated, this feature is not available.
+{{< /alert >}}
+
Account email verification provides an additional layer of GitLab account security.
When certain conditions are met, an account is locked. If your account is locked,
you must verify your identity or reset your password to sign in to GitLab.
diff --git a/doc/security/hardening.md b/doc/security/hardening.md
index 988dc2731bb7b4f1971a2aaec174a371a1d120c9..74e97a6bcd35d7a8b4585446495c77a0325dd867 100644
--- a/doc/security/hardening.md
+++ b/doc/security/hardening.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Hardening Recommendations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This documentation is for GitLab instances where the overall system can be "hardened"
against common and even not-so-common attacks. It is not designed to completely
diff --git a/doc/security/hardening_nist_800_53.md b/doc/security/hardening_nist_800_53.md
index fe34c5b180a24881fb4cc14b21258465187bdc6a..dc188ca1dc36de0d026d7b9dd51c99f2625b4d61 100644
--- a/doc/security/hardening_nist_800_53.md
+++ b/doc/security/hardening_nist_800_53.md
@@ -5,9 +5,12 @@ info: All material changes to this page must be approved by the [FedRAMP Complia
title: NIST 800-53 compliance
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page provides a reference for GitLab administrators
who want to configure GitLab Self-Managed instances to meet applicable
diff --git a/doc/security/identity_verification.md b/doc/security/identity_verification.md
index 76740102874bac4df2239d7fbc16f87069716dce..5caeb984f50efcbc57bc8dca1b2461559255165c 100644
--- a/doc/security/identity_verification.md
+++ b/doc/security/identity_verification.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Identity verification
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95722) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `identity_verification`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371389) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371389) in GitLab 16.11. Feature flag `identity_verification` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95722) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `identity_verification`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371389) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371389) in GitLab 16.11. Feature flag `identity_verification` removed.
+
+{{< /history >}}
Identity verification provides multiple layers of GitLab account security.
Depending on your [risk score](../integration/arkose.md), you might be required to perform up to
diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md
index 9444f741c9e800f6213e881641955f7e6d0bb61d..b16a6e7e6eb17d40aaeaf31f7ad1b22c50a1b8cd 100644
--- a/doc/security/information_exclusivity.md
+++ b/doc/security/information_exclusivity.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Information exclusivity
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Git is a distributed version control system (DVCS). This means that everyone
who works with the source code has a local copy of the complete repository.
diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md
index 3718541e10fea06153bf280886772d3836020b60..91fd9591e08b7316aa606e919d8525bf082cac26 100644
--- a/doc/security/password_length_limits.md
+++ b/doc/security/password_length_limits.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Custom password length limits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
By default, GitLab supports passwords with the following lengths:
diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md
index c5a474f51ca0b739abd14be4ef2d5a78080db767..1b86e39029c1e139e37452eeaa76c214de703a93 100644
--- a/doc/security/password_storage.md
+++ b/doc/security/password_storage.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Password and OAuth token storage
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab administrators can configure how passwords and OAuth tokens are stored.
## Password storage
-> - PBKDF2+SHA512 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360658) in GitLab 15.2 [with flags](../administration/feature_flags.md) named `pbkdf2_password_encryption` and `pbkdf2_password_encryption_write`. Disabled by default.
-> - Feature flags [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101691) in GitLab 15.6 and PBKDF2+SHA512 was made available to all GitLab instances running in [FIPS mode](../development/fips_gitlab.md).
+{{< history >}}
+
+- PBKDF2+SHA512 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360658) in GitLab 15.2 [with flags](../administration/feature_flags.md) named `pbkdf2_password_encryption` and `pbkdf2_password_encryption_write`. Disabled by default.
+- Feature flags [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101691) in GitLab 15.6 and PBKDF2+SHA512 was made available to all GitLab instances running in [FIPS mode](../development/fips_gitlab.md).
+
+{{< /history >}}
GitLab stores user passwords in a hashed format to prevent passwords from being
stored as plain text.
@@ -39,8 +46,12 @@ library to hash user passwords. Created password hashes have these attributes:
## OAuth access token storage
-> - PBKDF2+SHA512 introduced in GitLab 15.3 [with flag](../administration/feature_flags.md) named `hash_oauth_tokens`.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/367570) in GitLab 15.5.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/367570) in GitLab 15.6.
+{{< history >}}
+
+- PBKDF2+SHA512 introduced in GitLab 15.3 [with flag](../administration/feature_flags.md) named `hash_oauth_tokens`.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/367570) in GitLab 15.5.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/367570) in GitLab 15.6.
+
+{{< /history >}}
OAuth access tokens are stored in the database in PBKDF2+SHA512 format. As with PBKDF2+SHA512 password storage, access token values are [stretched](https://en.wikipedia.org/wiki/Key_stretching) 20,000 times to harden against brute-force attacks.
diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md
index 751c0dac653198803c5c0cb66592b5bd6af647fb..d2268538119d71eeb7a03863dc1ace1499fe9204 100644
--- a/doc/security/passwords_for_integrated_authentication_methods.md
+++ b/doc/security/passwords_for_integrated_authentication_methods.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Generated passwords for users created through integrated authentication
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab allows users to set up accounts through integration with external [authentication and authorization providers](../administration/auth/_index.md).
diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md
index 25f144ce3f5b626cdec7ba2d2d736c2feaaf6b91..3d8415e565fafaafbf757e722c583738e01a1f7a 100644
--- a/doc/security/rate_limits.md
+++ b/doc/security/rate_limits.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rate limits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
For GitLab.com, see
[GitLab.com-specific rate limits](../user/gitlab_com/_index.md#gitlabcom-specific-rate-limits).
+{{< /alert >}}
+
Rate limiting is a common technique used to improve the security and durability
of a web application.
@@ -29,9 +35,12 @@ Most cases can be mitigated by limiting the rate of requests from a single IP ad
Most [brute-force attacks](https://en.wikipedia.org/wiki/Brute-force_attack) are
similarly mitigated by a rate limit.
-NOTE:
+{{< alert type="note" >}}
+
The rate limits for API requests do not affect requests made by the frontend, because these requests are always counted as web traffic.
+{{< /alert >}}
+
## Configurable limits
You can set these rate limits in the **Admin** area of your instance:
@@ -87,13 +96,20 @@ For configuration information, see
## Non-configurable limits
-> - Rate limit on the `:user_id/status`, `:id/following`, `:id/followers`, `:user_id/keys`, `id/keys/:key_id`, `:id/gpg_keys`, and `:id/gpg_keys/:key_id` endpoints [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/452349) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `rate_limiting_user_endpoints`. Disabled by default.
+{{< history >}}
+
+- Rate limit on the `:user_id/status`, `:id/following`, `:id/followers`, `:user_id/keys`, `id/keys/:key_id`, `:id/gpg_keys`, and `:id/gpg_keys/:key_id` endpoints [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/452349) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `rate_limiting_user_endpoints`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of multiple endpoints in this feature is controlled by a feature flag.
For more information, see the history.
These endpoints are available for testing, but not ready for production use.
+{{< /alert >}}
+
### Repository archives
A rate limit for [downloading repository archives](../api/repositories.md#get-file-archive) is
@@ -173,8 +189,12 @@ The **rate limit** is 20 calls per minute per IP address.
### Project Jobs API endpoint
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382985) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `ci_enforce_rate_limits_jobs_api`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384186) in GitLab 16.0. Feature flag `ci_enforce_rate_limits_jobs_api` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382985) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `ci_enforce_rate_limits_jobs_api`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384186) in GitLab 16.0. Feature flag `ci_enforce_rate_limits_jobs_api` removed.
+
+{{< /history >}}
There is a rate limit for the endpoint `project/:id/jobs`, which is enforced to reduce timeouts when retrieving jobs.
@@ -182,7 +202,11 @@ The **rate limit** defaults to 600 calls per authenticated user. You can [config
### AI action
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118010) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118010) in GitLab 16.0.
+
+{{< /history >}}
There is a rate limit for the GraphQL `aiAction` mutation, which is enforced to prevent from abusing this endpoint.
@@ -190,7 +214,11 @@ The **rate limit** is 160 calls per 8 hours per authenticated user.
### Delete a member using the API
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118296) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118296) in GitLab 16.0.
+
+{{< /history >}}
There is a rate limit for [removing project or group members using the API endpoints](../api/members.md#remove-a-member-from-a-group-or-project) `/groups/:id/members` or `/project/:id/members`.
@@ -198,8 +226,12 @@ The **rate limit** is 60 deletions per minute.
### Notification emails
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439101) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `rate_limit_notification_emails`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/439101) in GitLab 17.2. Feature flag `rate_limit_notification_emails` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439101) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `rate_limit_notification_emails`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/439101) in GitLab 17.2. Feature flag `rate_limit_notification_emails` removed.
+
+{{< /history >}}
There is a rate limit for notification emails related to a project or group.
@@ -207,7 +239,11 @@ The **rate limit** is 1,000 notifications per 24 hours per project or group per
### FogBugz import
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439101) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439101) in GitLab 17.6.
+
+{{< /history >}}
There is a rate limit for triggering project imports from FogBugz.
diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md
index 715b183d7d91176ec71cd7adc5720f59a1341066..dd9b3efba690303850d070e6098e6dba994cbc34 100644
--- a/doc/security/reset_user_password.md
+++ b/doc/security/reset_user_password.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Reset user passwords
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can reset user passwords by using the UI, a Rake task, a Rails console, or the
[Users API](../api/users.md#modify-a-user).
@@ -33,42 +36,50 @@ A confirmation is displayed.
To reset a user password with a Rake task:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake "gitlab:password:reset"
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
bundle exec rake "gitlab:password:reset"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
GitLab requests a username, a password, and confirmation of the password. When complete, the user password is updated.
The Rake task can accept a username as an argument. For example, to reset the password for the user with username
`sidneyjones`:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake "gitlab:password:reset[sidneyjones]"
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
bundle exec rake "gitlab:password:reset[sidneyjones]"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Use a Rails console
diff --git a/doc/security/responding_to_security_incidents.md b/doc/security/responding_to_security_incidents.md
index d874965c642ce5ed84d17db1f115403a00cc1406..6d3e4dd6ab6453ea1ba0f3da0dca46797062b177 100644
--- a/doc/security/responding_to_security_incidents.md
+++ b/doc/security/responding_to_security_incidents.md
@@ -13,9 +13,12 @@ When a security incident occurs, you should primarily follow the processes defin
Using this guide, you should feel confident in handling security incidents related to GitLab. Where necessary, the guide links to other parts of GitLab documentation.
-WARNING:
+{{< alert type="warning" >}}
+
Use the suggestions/recommendations mentioned in this guide at your own risk.
+{{< /alert >}}
+
## Common security incident scenarios
### Credential exposure to public internet
diff --git a/doc/security/rotate_integrations_secrets.md b/doc/security/rotate_integrations_secrets.md
index ce34843204083daaea7d2961dce2b736182c1156..63f6445707a50de517d1fb6d590f11a8353e88d4 100644
--- a/doc/security/rotate_integrations_secrets.md
+++ b/doc/security/rotate_integrations_secrets.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rotate secrets of third-party integrations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Rotating secrets of third-party integrations is an important security practice
that helps mitigate the risks associated with leaked secrets, such as
diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md
index 5fdb4da60370846e9b34eef9c5872cfde0303c3b..b78ecc3e3688787ef01ea8fd3a009513b05e4c5a 100644
--- a/doc/security/ssh_keys_restrictions.md
+++ b/doc/security/ssh_keys_restrictions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Restrict allowed SSH key technologies and minimum length
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
`ssh-keygen` allows users to create RSA keys with as few as 768 bits, which
falls well below recommendations from certain standards groups (such as the US
@@ -37,7 +40,7 @@ If a restriction is imposed on any key type, users cannot upload new SSH keys th
requirement. Any existing keys that don't meet it are disabled but not removed and users cannot
pull or push code using them.
-If you have a restricted key, a warning icon (**{warning}**) is visible to you in the **SSH keys** section of your profile.
+If you have a restricted key, a warning icon ({{< icon name="warning" >}}) is visible to you in the **SSH keys** section of your profile.
To learn why that key is restricted, hover over the icon.
## Default settings
@@ -54,12 +57,19 @@ By default, the GitLab.com and self-managed settings for the
## Block banned or compromised keys
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24614) in GitLab 15.1 [with a flag](../administration/feature_flags.md) named `ssh_banned_key`. Enabled by default.
+- Generally available in GitLab 15.2. [Feature flag `ssh_banned_key`](https://gitlab.com/gitlab-org/gitlab/-/issues/363410) removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24614) in GitLab 15.1 [with a flag](../administration/feature_flags.md) named `ssh_banned_key`. Enabled by default.
-> - Generally available in GitLab 15.2. [Feature flag `ssh_banned_key`](https://gitlab.com/gitlab-org/gitlab/-/issues/363410) removed.
+{{< /history >}}
When users attempt to [add a new SSH key](../user/ssh.md#add-an-ssh-key-to-your-gitlab-account)
to GitLab accounts, the key is checked against a list of SSH keys which are known
diff --git a/doc/security/tls_support.md b/doc/security/tls_support.md
index 532d94ed069508821612083f1819c212203b0353..4b8cf992ba24779739e746b3bac531974c774e71 100644
--- a/doc/security/tls_support.md
+++ b/doc/security/tls_support.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: TLS support
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab prioritizes the security of data transmission between users and our
platforms by employing Transport Layer Security (TLS) to safeguard information
diff --git a/doc/security/tokens/_index.md b/doc/security/tokens/_index.md
index bf1fa05220a48219085ac77aa95bbc851cf152b2..e67f0cfe149440413d0a82bd50155eee758ad323 100644
--- a/doc/security/tokens/_index.md
+++ b/doc/security/tokens/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab token overview
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This document lists tokens used in GitLab, their purpose and, where
applicable, security guidance.
@@ -192,13 +195,16 @@ You can use the runners API to [rotate or revoke a runner authentication token](
## Runner registration tokens (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
The ability to pass a runner registration token has been [deprecated](../../ci/runners/new_creation_workflow.md) and is
planned for removal in GitLab 18.0, along with support for certain configuration arguments. This change is a breaking change. GitLab has implemented a new
[GitLab Runner token architecture](../../ci/runners/new_creation_workflow.md), which introduces
a new method for registering runners and eliminates the
runner registration token.
+{{< /alert >}}
+
Runner registration tokens are used to
[register](https://docs.gitlab.com/runner/register/) a
[runner](https://docs.gitlab.com/runner/) with GitLab. Group or
@@ -307,16 +313,16 @@ This table shows default scopes per token. For some tokens, you can limit scopes
| Token name | API access | Registry access | Repository access |
|-----------------------------|------------------------------------|------------------------------------|-------------------|
-| Personal access token | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| OAuth 2.0 token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Impersonation token | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Project access token | **{check-circle}** Yes<sup>1</sup> | **{check-circle}** Yes<sup>1</sup> | **{check-circle}** Yes<sup>1</sup> |
-| Group access token | **{check-circle}** Yes<sup>2</sup> | **{check-circle}** Yes<sup>2</sup> | **{check-circle}** Yes<sup>2</sup> |
-| Deploy token | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes |
-| Deploy key | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| Runner registration token | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle-dashed}** Limited<sup>3</sup> |
-| Runner authentication token | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle-dashed}** Limited<sup>3</sup> |
-| Job token | **{check-circle-dashed}** Limited<sup>4</sup> | **{dotted-circle}** No | **{check-circle}** Yes |
+| Personal access token | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| OAuth 2.0 token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Impersonation token | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Project access token | {{< icon name="check-circle" >}} Yes<sup>1</sup> | {{< icon name="check-circle" >}} Yes<sup>1</sup> | {{< icon name="check-circle" >}} Yes<sup>1</sup> |
+| Group access token | {{< icon name="check-circle" >}} Yes<sup>2</sup> | {{< icon name="check-circle" >}} Yes<sup>2</sup> | {{< icon name="check-circle" >}} Yes<sup>2</sup> |
+| Deploy token | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Deploy key | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Runner registration token | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle-dashed" >}} Limited<sup>3</sup> |
+| Runner authentication token | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle-dashed" >}} Limited<sup>3</sup> |
+| Job token | {{< icon name="check-circle-dashed" >}} Limited<sup>4</sup> | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
**Footnotes:**
diff --git a/doc/security/tokens/token_troubleshooting.md b/doc/security/tokens/token_troubleshooting.md
index f4543019f2da1de24a7cd6295d10270696699f59..abec3c6a01456f9fe571ff35106577743fb21b8d 100644
--- a/doc/security/tokens/token_troubleshooting.md
+++ b/doc/security/tokens/token_troubleshooting.md
@@ -23,7 +23,11 @@ For more information on authentication request limits, see [Git and container re
### Identify expired access tokens from logs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464652) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464652) in GitLab 17.2.
+
+{{< /history >}}
Prerequisites:
@@ -110,16 +114,18 @@ For group and project access tokens, this script only extends the lifetime of th
To use the script:
-::Tabs
+{{< tabs >}}
-:::TabTitle Rails console session
+{{< tab title="Rails console session" >}}
1. In your terminal window, start a Rails console session with `sudo gitlab-rails console`.
1. Paste in the entire `extend_expiring_tokens.rb` script below.
If desired, change the `expiring_date` to a different date.
1. Press <kbd>Enter</kbd>.
-:::TabTitle Rails Runner
+{{< /tab >}}
+
+{{< tab title="Rails Runner" >}}
1. In your terminal window, connect to your instance.
1. Copy this entire `extend_expiring_tokens.rb` script below, and save it as a file on your instance:
@@ -135,7 +141,9 @@ To use the script:
For more information, see the [Rails Runner troubleshooting section](../../administration/operations/rails_console.md#troubleshooting).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
##### `extend_expiring_tokens.rb`
@@ -216,9 +224,9 @@ Prerequisites:
To use it:
-::Tabs
+{{< tabs >}}
-:::TabTitle Rails console session
+{{< tab title="Rails console session" >}}
1. In your terminal window, connect to your instance.
1. Start a Rails console session with `sudo gitlab-rails console`.
@@ -227,7 +235,9 @@ To use it:
Change the `expires_at_date` to the date one year after your instance was upgraded to GitLab 16.0.
1. Press <kbd>Enter</kbd>.
-:::TabTitle Rails Runner
+{{< /tab >}}
+
+{{< tab title="Rails Runner" >}}
1. In your terminal window, connect to your instance.
1. Depending on your needs, copy either the entire `expired_tokens.rb`
@@ -244,7 +254,9 @@ To use it:
For more information, see the [Rails Runner troubleshooting section](../../administration/operations/rails_console.md#troubleshooting).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### `expired_tokens.rb`
@@ -276,26 +288,31 @@ PersonalAccessToken.project_access_token.where(expires_at: expires_at_date).find
end
```
-NOTE:
+{{< alert type="note" >}}
+
To not only hide, but also remove, tokens belonging to blocked users, add `token.destroy!` directly below
`if token.user.blocked?`. However, this action does not leave an audit event,
unlike the [API method](../../api/personal_access_tokens.md#revoke-a-personal-access-token).
+{{< /alert >}}
+
### Find tokens expiring in a given month
This script finds tokens that expire in a particular month. You don't need to know
the exact date your instance was upgraded to GitLab 16.0. To use it:
-::Tabs
+{{< tabs >}}
-:::TabTitle Rails console session
+{{< tab title="Rails console session" >}}
1. In your terminal window, start a Rails console session with `sudo gitlab-rails console`.
1. Paste in the entire `tokens_with_no_expiry.rb` script below.
If desired, change the `date_range` to a different range.
1. Press <kbd>Enter</kbd>.
-:::TabTitle Rails Runner
+{{< /tab >}}
+
+{{< tab title="Rails Runner" >}}
1. In your terminal window, connect to your instance.
1. Copy this entire `tokens_with_no_expiry.rb` script below, and save it as a file on your instance:
@@ -311,7 +328,9 @@ the exact date your instance was upgraded to GitLab 16.0. To use it:
For more information, see the [Rails Runner troubleshooting section](../../administration/operations/rails_console.md#troubleshooting).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### `expired_tokens_date_range.rb`
@@ -351,15 +370,17 @@ The script returns results in this format:
To use it:
-::Tabs
+{{< tabs >}}
-:::TabTitle Rails console session
+{{< tab title="Rails console session" >}}
1. In your terminal window, start a Rails console session with `sudo gitlab-rails console`.
1. Paste in the entire `dates_when_most_of_tokens_expire.rb` script.
1. Press <kbd>Enter</kbd>.
-:::TabTitle Rails Runner
+{{< /tab >}}
+
+{{< tab title="Rails Runner" >}}
1. In your terminal window, connect to your instance.
1. Copy this entire `dates_when_most_of_tokens_expire.rb`
@@ -375,7 +396,9 @@ To use it:
For more information, see the [Rails Runner troubleshooting section](../../administration/operations/rails_console.md#troubleshooting).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### `dates_when_most_of_tokens_expire.rb`
@@ -400,16 +423,18 @@ value is `NULL`, and can be used to identify tokens to add an expiration date to
You can use this script in either the [Rails console](../../administration/operations/rails_console.md)
or the [Rails Runner](../../administration/operations/rails_console.md#using-the-rails-runner):
-::Tabs
+{{< tabs >}}
-:::TabTitle Rails console session
+{{< tab title="Rails console session" >}}
1. In your terminal window, connect to your instance.
1. Start a Rails console session with `sudo gitlab-rails console`.
1. Paste in the entire `tokens_with_no_expiry.rb` script below.
1. Press <kbd>Enter</kbd>.
-:::TabTitle Rails Runner
+{{< /tab >}}
+
+{{< tab title="Rails Runner" >}}
1. In your terminal window, connect to your instance.
1. Copy this entire `tokens_with_no_expiry.rb` script below, and save it as a file on your instance:
@@ -423,7 +448,9 @@ or the [Rails Runner](../../administration/operations/rails_console.md#using-the
For more information, see the [Rails Runner troubleshooting section](../../administration/operations/rails_console.md#troubleshooting).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### `tokens_with_no_expiry.rb`
diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md
index ad31ff4c79bd83e709935b0c6e2fb9c66e20f57f..e3719a33921be824b9015db72e350f2d34892c2d 100644
--- a/doc/security/two_factor_authentication.md
+++ b/doc/security/two_factor_authentication.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Enforce two-factor authentication
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Two-factor authentication (2FA)](../user/profile/account/two_factor_authentication.md)
is an authentication method that requires the user to provide two different factors
@@ -19,14 +22,20 @@ to prove their identity:
2FA makes it harder for an unauthorized person to access an account because
they would need both factors.
-NOTE:
+{{< alert type="note" >}}
+
If you are [using and enforcing SSO](../user/group/saml_sso/_index.md#sso-enforcement), you might already be enforcing 2FA on the identity provider (IdP) side. Enforcing 2FA on GitLab as well might be unnecessary.
+{{< /alert >}}
+
## Enforce 2FA for all users
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Administrators can enforce 2FA for all users in two different ways:
@@ -58,11 +67,18 @@ For more information, see the [list of settings that can be accessed through API
## Enforce 2FA for Administrator users
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427549) in GitLab 16.8.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427549) in GitLab 16.8.
+
+{{< /history >}}
Administrators can enforce 2FA for administrator users in a self-managed instance.
@@ -74,20 +90,29 @@ Administrators can enforce 2FA for administrator users in a self-managed instanc
enforce 2FA on the next sign-in attempt, enter `0`.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
If you are using an external provider to sign in into GitLab, this setting will **not** enforce 2FA for users. 2FA should be enabled on that external provider.
+{{< /alert >}}
+
## Enforce 2FA for all users in a group
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can enforce 2FA for all users in a group or subgroup.
-NOTE:
+{{< alert type="note" >}}
+
2FA enforcement applies to both [direct and inherited members](../user/project/members/_index.md#membership-types) group members. If 2FA is enforced on a subgroup, members of the parent group must also enroll an authentication factor.
+{{< /alert >}}
+
Prerequisites:
- You must have the Maintainer or Owner role for the group.
@@ -132,26 +157,35 @@ without using 2FA. For example:
To ensure this does not occur, [prevent sharing of projects](../user/project/members/sharing_projects_groups.md#prevent-a-project-from-being-shared-with-groups)
for the 2FA group.
-WARNING:
+{{< alert type="warning" >}}
+
If you add members to a project in a group or subgroup that has 2FA
enabled, 2FA is **not** required for those individually added members.
+{{< /alert >}}
+
## Disable 2FA
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can disable 2FA for a single user or all users.
This action is permanent and irreversible. Users must reactivate 2FA to use it again.
-WARNING:
+{{< alert type="warning" >}}
+
Disabling 2FA for users does not disable the [enforce 2FA for all users](#enforce-2fa-for-all-users)
or [enforce 2FA for all users in a group](#enforce-2fa-for-all-users-in-a-group)
settings. You must also disable any enforced 2FA settings so users aren't asked to set up 2FA again
when they next sign in to GitLab.
+{{< /alert >}}
+
### For a single user
#### Administrators
@@ -196,16 +230,26 @@ To disable 2FA for all users even when forced 2FA is disabled, use the following
## 2FA for Git over SSH operations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
-> - It's deployed behind a feature flag, disabled by default.
-> - Push notification support [introduced](https://gitlab.com/gitlab-org/gitlab-shell/-/issues/506) in GitLab 15.3.
+- It's deployed behind a feature flag, disabled by default.
+- Push notification support [introduced](https://gitlab.com/gitlab-org/gitlab-shell/-/issues/506) in GitLab 15.3.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `two_factor_for_cli`. On GitLab.com and GitLab Dedicated, this feature is not available. This feature is not ready for production use. This feature flag also affects [session duration for Git Operations when 2FA is enabled](../administration/settings/account_and_limit_settings.md#customize-session-duration-for-git-operations-when-2fa-is-enabled).
+{{< /alert >}}
+
You can enforce 2FA for [Git over SSH operations](../development/gitlab_shell/features.md#git-operations). However, you should use
[ED25519_SK](../user/ssh.md#ed25519_sk-ssh-keys) or [ECDSA_SK](../user/ssh.md#ecdsa_sk-ssh-keys) SSH keys instead. 2FA is enforced for Git operations only, and internal commands such as [`personal_access_token`](../development/gitlab_shell/features.md#personal-access-token) are excluded.
diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md
index a5024845cbf6d791289f7c87d00fd1f1f31a710f..21164a4f8aa41e012efb4d82b7c4a9cfd5bafcc5 100644
--- a/doc/security/unlock_user.md
+++ b/doc/security/unlock_user.md
@@ -9,9 +9,12 @@ GitLab locks a user account after the user unsuccessfully attempts to sign in se
## GitLab.com users
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
If two-factor authentication (2FA) is enabled, accounts are locked after three failed sign-in attempts. Accounts are unlocked automatically after 30 minutes.
@@ -22,11 +25,18 @@ If 2FA is not enabled user accounts are locked after three failed sign-in attemp
## GitLab Self-Managed and GitLab Dedicated users
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Configurable locked user policy [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27048) in GitLab 16.5.
-> - Configurable locked user policy [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27048) in GitLab 16.5.
+{{< /history >}}
By default, user accounts are locked after 10 failed sign-in attempts. Accounts are unlocked automatically after 10 minutes.
diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md
index 03d016a77be2ab15b49a37cb2c75f39dd97bd8b6..548abf0475471110a51777e92d50c4741728e86f 100644
--- a/doc/security/user_email_confirmation.md
+++ b/doc/security/user_email_confirmation.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Make new users confirm email
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab can be configured to require confirmation of a user's email address when
the user signs up. When this setting is enabled, the user is unable to sign in until
@@ -24,9 +27,12 @@ After 24 hours, the confirmation token becomes invalid.
## Automatically delete unconfirmed users
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When email confirmation is turned on, administrators can enable the setting to
[automatically delete unconfirmed users](../administration/moderate_users.md#automatically-delete-unconfirmed-users).
diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md
index 4d82adc3df3a618ae719fa7a877339458a6d2e33..afcf825b2ecf734a246517d25b240087d0d2705b 100644
--- a/doc/security/user_file_uploads.md
+++ b/doc/security/user_file_uploads.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User file uploads
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Users can upload files to:
@@ -18,13 +21,20 @@ GitLab generates direct URLs for these uploaded files with a random 32-character
Files uploaded by users to GitLab issues, merge requests, and epics contain `/uploads/<32-character-id>` in the URL path.
-WARNING:
+{{< alert type="warning" >}}
+
Exercise caution in downloading files uploaded by unknown or untrusted sources, especially if the file is an executable or script.
+{{< /alert >}}
+
## Access control for uploaded files
-> - Enforced authorization checks became [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352291) in GitLab 15.3. Feature flag `enforce_auth_checks_on_uploads` removed.
-> - Project settings in the user interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88567) in GitLab 15.3.
+{{< history >}}
+
+- Enforced authorization checks became [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352291) in GitLab 15.3. Feature flag `enforce_auth_checks_on_uploads` removed.
+- Project settings in the user interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88567) in GitLab 15.3.
+
+{{< /history >}}
Access to non-image files uploaded to:
@@ -58,13 +68,20 @@ To configure authentication settings for all media files:
1. Expand **Visibility, project features, permissions**.
1. Scroll to **Project visibility** and select **Require authentication to view media files**.
-NOTE:
+{{< alert type="note" >}}
+
You cannot select this option for public projects.
+{{< /alert >}}
+
## Delete uploaded files
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92791) in GitLab 15.3.
-> - REST API [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) support in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92791) in GitLab 15.3.
+- REST API [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157066) support in GitLab 17.2.
+
+{{< /history >}}
You should delete an uploaded file when that file contains sensitive or confidential information. When you have deleted that file, users cannot access the file and the direct URL returns a 404 error.
diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md
index 211c82c4b5876908b21afdd8ff333e0cf17aac3a..492ff49bdc8a4a95e1d1b832061760d0128f6c74 100644
--- a/doc/security/webhooks.md
+++ b/doc/security/webhooks.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Filtering outbound requests
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To protect against the risk of data loss and exposure, GitLab administrators can now use outbound request filtering controls to restrict certain outbound requests made by the GitLab instance.
@@ -85,7 +88,11 @@ Prerequisites:
## Filter requests
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377371) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377371) in GitLab 15.10.
+
+{{< /history >}}
Prerequisites:
diff --git a/doc/solutions/cloud/aws/gitaly_sre_for_aws.md b/doc/solutions/cloud/aws/gitaly_sre_for_aws.md
index 3b248e45f5f66312c480b9c07aa30deb3f701ac4..05fc15c4bbbf27389328e7b2c6cbe1f6b65de3d6 100644
--- a/doc/solutions/cloud/aws/gitaly_sre_for_aws.md
+++ b/doc/solutions/cloud/aws/gitaly_sre_for_aws.md
@@ -6,9 +6,12 @@ description: Doing SRE for Gitaly instances on AWS.
title: SRE Considerations for Gitaly on AWS
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
## Gitaly SRE considerations
@@ -35,9 +38,12 @@ Complete performance metrics should be collected for Gitaly instances for identi
Gitaly functions as the primary Git Repository Storage in GitLab. However, it's not a streaming file server. It also does a lot of demanding computing work, such as preparing and caching Git packfiles which informs some of the performance recommendations below.
-NOTE:
+{{< alert type="note" >}}
+
All recommendations are for production configurations, including performance testing. For test configurations, like training or functional testing, you can use less expensive options. However, you should adjust or rebuild if performance is an issue.
+{{< /alert >}}
+
#### Overall recommendations
- Production-grade Gitaly must be implemented on instance compute due to all of the above and below characteristics.
diff --git a/doc/solutions/cloud/aws/gitlab_aws_integration.md b/doc/solutions/cloud/aws/gitlab_aws_integration.md
index 77b970bc55a30da896e63c3f5a17a0c7626fdeff..373d8cff91a98eaf350d07d43285df3a8dd9b816 100644
--- a/doc/solutions/cloud/aws/gitlab_aws_integration.md
+++ b/doc/solutions/cloud/aws/gitlab_aws_integration.md
@@ -2,7 +2,7 @@
stage: Solutions Architecture
group: Solutions Architecture
info: This page is owned by the Solutions Architecture team.
-description: "Integrations Solutions Index for GitLab and AWS."
+description: Integrations Solutions Index for GitLab and AWS.
title: Integrate with AWS
---
diff --git a/doc/solutions/cloud/aws/gitlab_single_box_on_aws.md b/doc/solutions/cloud/aws/gitlab_single_box_on_aws.md
index 5e2f80236ad66d54045afd02912da939c224df56..99c1aa32b8495ab6cf0987bee0c6534cb29baad8 100644
--- a/doc/solutions/cloud/aws/gitlab_single_box_on_aws.md
+++ b/doc/solutions/cloud/aws/gitlab_single_box_on_aws.md
@@ -5,9 +5,12 @@ info: This page is owned by the Solutions Architecture team.
title: Provision GitLab on a single EC2 instance in AWS
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
If you want to provision a single GitLab instance on AWS, you have two options:
@@ -28,14 +31,20 @@ Initial licensing can either be the Free Enterprise License (EE) or the open sou
Currently the Amazon AMI uses the Amazon prepared Ubuntu AMI (x86 and ARM are available) as its starting point.
-NOTE:
+{{< alert type="note" >}}
+
When deploying a GitLab instance using the official AMI, the root password to the instance is the EC2 **Instance** ID (not the AMI ID). This way of setting the root account password is specific to official GitLab published AMIs ONLY.
+{{< /alert >}}
+
Instances running on Community Edition (CE) require a migration to Enterprise Edition (EE) to subscribe to the GitLab Premium or Ultimate plan. If you want to pursue a subscription, using the Free-forever plan of Enterprise Edition is the least disruptive method.
-NOTE:
+{{< alert type="note" >}}
+
Because any given GitLab upgrade might involve data disk updates or database schema upgrades, swapping out the AMI is not sufficient for taking upgrades.
+{{< /alert >}}
+
1. Sign in to the AWS Web Console, so that selecting the links in the following step take you directly to the AMI list.
1. Pick the edition you want:
diff --git a/doc/solutions/cloud/aws/tutorials/aws_ecr_pull_through_cache.md b/doc/solutions/cloud/aws/tutorials/aws_ecr_pull_through_cache.md
index 45b879ac8e14494bd85f79d06ff76a6d1550e2f9..1181c862b795766fa549d3d9936079ccbe8433f7 100644
--- a/doc/solutions/cloud/aws/tutorials/aws_ecr_pull_through_cache.md
+++ b/doc/solutions/cloud/aws/tutorials/aws_ecr_pull_through_cache.md
@@ -2,7 +2,7 @@
stage: Solutions Architecture
group: Solutions Architecture
info: This page is owned by the Solutions Architecture team.
-description: "Integrations Solutions Index for GitLab and AWS."
+description: Integrations Solutions Index for GitLab and AWS.
title: 'Tutorial: Configuring AWS ECR Pull Through Cache Rules for Authenticated Access to GitLab.com Projects'
---
@@ -20,9 +20,12 @@ On Step 2: Configure authentication page, for Upstream credentials, you must sto
To use an existing secret, choose Use an existing AWS secret. For Secret name use the drop down to select your existing secret, and then choose Next. For more information on creating a Secrets Manager secret using the Secrets Manager console, see Storing your upstream repository credentials in an AWS Secrets Manager secret.
-NOTE:
+{{< alert type="note" >}}
+
The AWS Management Console only displays Secrets Manager secrets with names using the ecr-pullthroughcache/ prefix. The secret must also be in the same account and Region that the pull through cache rule is created in.
+{{< /alert >}}
+
To create a new secret, choose Create an AWS secret, do the following, then choose Next.
For Secret name, specify a descriptive name for the secret. Secret names must contain 1-512 Unicode characters.
diff --git a/doc/solutions/components/ai_gatewaysolution.md b/doc/solutions/components/ai_gatewaysolution.md
index d08d585c16437becf7727ee1373f42c24b7cb61e..62c645844f03cf21b6b13e516e06baf266e79fcc 100644
--- a/doc/solutions/components/ai_gatewaysolution.md
+++ b/doc/solutions/components/ai_gatewaysolution.md
@@ -5,8 +5,11 @@ info: This page is owned by the Solutions Architecture team.
title: AI Gateway Solution
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Pro or Enterprise
-**Offering:** GitLab Self-Managed
+{{< details >}}
-The document describes the installation package and integration scripts of GitLab and GitLab Duo with a self-hosted Large Language Model (LLM) running a selected models on Ollama.
+- Tier: Ultimate with GitLab Duo Pro or Enterprise
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+The document describes the installation package and integration scripts of GitLab and GitLab Duo with a self-hosted Large Language Model (LLM) running a selected models on Ollama.
diff --git a/doc/solutions/components/integrated_servicenow.md b/doc/solutions/components/integrated_servicenow.md
index a8e23bc911cb08ecf83369599928139e188a4e53..87b37a3512ad14c04e51be730ebad5ea48072a86 100644
--- a/doc/solutions/components/integrated_servicenow.md
+++ b/doc/solutions/components/integrated_servicenow.md
@@ -5,8 +5,11 @@ info: This page is owned by the Solutions Architecture team.
title: Integrated Change Management - ServiceNow
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This document provides the instruction and functional detail for GitLab to orcestrate the change management with integrated ServiceNow solution.
diff --git a/doc/solutions/components/regulatedindustry_sdlc.md b/doc/solutions/components/regulatedindustry_sdlc.md
index 7b59ad44dcfefb79dddd8bf66c86a179c24ba682..3798611719f43bd23d258195f5e5e28ffdb28aa4 100644
--- a/doc/solutions/components/regulatedindustry_sdlc.md
+++ b/doc/solutions/components/regulatedindustry_sdlc.md
@@ -5,8 +5,11 @@ info: This page is owned by the Solutions Architecture team.
title: Sectors - Regulated Industry Solution
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This document provides the instruction and functional detail for GitLab Regulated Industry SDLC Compliance Solution.
diff --git a/doc/solutions/components/securitykpi.md b/doc/solutions/components/securitykpi.md
index ae8bde1d50d438c3435dd3cd2b5e276a157f9893..40d578c787904ff76963befa643bd7e4d5ed3266 100644
--- a/doc/solutions/components/securitykpi.md
+++ b/doc/solutions/components/securitykpi.md
@@ -5,9 +5,12 @@ info: This page is owned by the Solutions Architecture team.
title: Security Metrics and KPIs
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The document describes the installation, configuration and user guide of GitLab Security Metrics and KPIs Solution Component. This security solution component provides metrics and KPIs that can be viewed by business units, time range, vulnerability severity and security types. It can provide snapshot of the seucrity posture on the monthly and quarterly basis with pdf documents. The dashboard and visualization of data are displayed as Dashboard in Splunk.
diff --git a/doc/solutions/components/workflow_mobileapps.md b/doc/solutions/components/workflow_mobileapps.md
index 4579046ef11a392320099e579714fda3a37ca4aa..116e133090bb97037c243614603a20af5e3ad96a 100644
--- a/doc/solutions/components/workflow_mobileapps.md
+++ b/doc/solutions/components/workflow_mobileapps.md
@@ -5,8 +5,11 @@ info: This page is owned by the Solutions Architecture team.
title: DevSecOps Workflow - Mobile Apps
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This document provides the instruction and functional detail for GitLab DevSecOps Workflow solution for building and delivering mobile apps.
diff --git a/doc/solutions/integrations/aws_googlecloud_ollama.md b/doc/solutions/integrations/aws_googlecloud_ollama.md
index 3af5c1075a08f461c994948eabe2e391cd997298..24de666d473343d9204c232d6291330e62de98f7 100644
--- a/doc/solutions/integrations/aws_googlecloud_ollama.md
+++ b/doc/solutions/integrations/aws_googlecloud_ollama.md
@@ -5,9 +5,12 @@ info: This page is owned by the Solutions Architecture team.
title: 'GitLab Duo Self-Hosted: Complete AWS/Google Cloud Deployment Guide with Ollama Integration'
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Pro or Enterprise
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Pro or Enterprise
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
The document describes the installation and integration of GitLab and GitLab Duo with a self-hosted Large Language Model (LLM) running a Mistral model on Ollama. The guide describes the setup using 3 different
virtual machines and can be easily followed along on AWS or GCP. Of course, the process is applicable to different deployment platforms, too.
@@ -60,9 +63,12 @@ flowchart LR
These components work together to realize the Self-Hosted AI functionality. This guide provides detailed instructions for building a complete self-hosted AI environment using Ollama as the LLM server.
-NOTE:
+{{< alert type="note" >}}
+
While for a full production environment, the [official documentation](../../administration/gitlab_duo_self_hosted/supported_models_and_hardware_requirements.md) recommends more powerful GPU instances such as 1x NVIDIA A100 (40 GB), the g4dn.xlarge instance type should be sufficient for evaluation purposes with a small team of users.
+{{< /alert >}}
+
#### Networking
To enable access to GitLab, a static public IP address (such as an Elastic IP in AWS or an External IP in Google Cloud) is required. All other components can and should use static internal IP addresses for internal communication. We assume all VMs are on the same network and can communicate directly.
@@ -205,8 +211,11 @@ During the initial setup and testing phase, you can set AIGW_AUTH__BYPASS_EXTERN
Environment="OLLAMA_HOST=172.31.11.27"
```
- NOTE:
- Replace the IP address with your actual server's internal IP address.
+ {{< alert type="note" >}}
+
+Replace the IP address with your actual server's internal IP address.
+
+ {{< /alert >}}
1. Reload and restart the service:
@@ -264,9 +273,12 @@ During the initial setup and testing phase, you can set AIGW_AUTH__BYPASS_EXTERN
-NOTE:
+{{< alert type="note" >}}
+
Enabling Duo for just the root user is sufficient for initial setup and testing. Additional users can be granted Duo access later if needed, within your seat license limitations.
+{{< /alert >}}
+
### Configure GitLab Duo Self-Hosted in GitLab
1. Access GitLab Duo Self-Hosted Configuration
diff --git a/doc/solutions/integrations/servicenow.md b/doc/solutions/integrations/servicenow.md
index b1ba6bd48d2b3a850c11699805041b572e456dd3..bd72c4ae2be459e36be8c51b263c8916ce76e821 100644
--- a/doc/solutions/integrations/servicenow.md
+++ b/doc/solutions/integrations/servicenow.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: ServiceNow
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
ServiceNow offers several integrations to help centralize and automate your
management of GitLab workflows.
diff --git a/doc/subscriptions/choosing_subscription.md b/doc/subscriptions/choosing_subscription.md
index e003f99b0331cb1e9f95b26259eba29018c7e396..c320b0298e7b902174f020868e754b3922a829fd 100644
--- a/doc/subscriptions/choosing_subscription.md
+++ b/doc/subscriptions/choosing_subscription.md
@@ -1,8 +1,8 @@
---
stage: Fulfillment
group: Subscription Management
-description: Options for accessing GitLab.
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
+description: Options for accessing GitLab.
title: GitLab plans
---
@@ -24,10 +24,13 @@ features for all users.
On GitLab.com, you can apply a subscription to a top-level group
namespace. You cannot apply a subscription to a personal namespace.
-NOTE:
+{{< alert type="note" >}}
+
Subscriptions cannot be transferred between GitLab.com and GitLab Self-Managed.
A new subscription must be purchased and applied as needed.
+{{< /alert >}}
+
## Choose a subscription tier
Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose
diff --git a/doc/subscriptions/community_programs.md b/doc/subscriptions/community_programs.md
index 83af3300094a078a08eecc0a3dcbda8a97c196a6..c6f93f8c8f3616a379eced1dfbad8754814a3de8 100644
--- a/doc/subscriptions/community_programs.md
+++ b/doc/subscriptions/community_programs.md
@@ -1,8 +1,8 @@
---
stage: none
group: unassigned
-description: Education, Open Source, Startups.
info: For help with this Community Programs page, see https://handbook.gitlab.com/handbook/marketing/developer-relations/community-programs/
+description: Education, Open Source, Startups.
title: Community programs
---
@@ -29,9 +29,12 @@ To add a license to a project:
Applicants must add the correct license to each project in their respective groups or namespaces. When you're sure you're using OSI-approved licenses for your projects, you can take your screenshots.
-NOTE:
+{{< alert type="note" >}}
+
GitLab for Open Source Program benefits apply to an entire GitLab namespace. To qualify for the GitLab for Open Source Program, all projects in an applicant's namespace must meet program requirements. Applicants submit materials related to one project in the applying namespace, and the open source program team uses that project to verify eligibility of the entire namespace.
+{{< /alert >}}
+
### Verification for Open Source Program
Next, take screenshots of your project to confirm that project's eligibility. You must upload three screenshots:
@@ -40,9 +43,12 @@ Next, take screenshots of your project to confirm that project's eligibility. Yo
- [OSI-approved license contents](#screenshot-2-license-contents)
- [Publicly visible settings](#screenshot-3-publicly-visible-settings)
-NOTE:
+{{< alert type="note" >}}
+
Benefits of the GitLab Open Source Program apply to all projects in a GitLab namespace. All projects in an eligible namespace must meet program requirements.
+{{< /alert >}}
+
#### Screenshot 1: License overview
1. On the left sidebar, select **Search or go to** and find your project.
@@ -72,9 +78,12 @@ To be eligible for the GitLab Open Source Program, projects must be publicly vis
-NOTE:
+{{< alert type="note" >}}
+
Exceptions to this public visibility requirement apply in select circumstances (for example, in cases where a project in an applicant's namespace may hold sensitive data). Email `opensource@gitlab.com` with details of your use case to request written permission for exceptions.
+{{< /alert >}}
+
## GitLab for Startups
For qualifying startups, the [GitLab for Startups](https://about.gitlab.com/solutions/startups/) program provides GitLab Ultimate, plus 50,000 compute minutes per month for 12 months. For more information—including instructions for applying to the program and renewing program membership—see the [GitLab for Startups Program page](https://about.gitlab.com/solutions/startups/) and the [GitLab handbook](https://handbook.gitlab.com/handbook/marketing/developer-relations/community-programs/startups-program/).
diff --git a/doc/subscriptions/customers_portal.md b/doc/subscriptions/customers_portal.md
index f14ce68d3089e6c25684a89b75e708f6db5cace1..fc29aa09ca3f75a4701afa19cfbbe4d6c2d637a0 100644
--- a/doc/subscriptions/customers_portal.md
+++ b/doc/subscriptions/customers_portal.md
@@ -1,8 +1,8 @@
---
stage: Fulfillment
group: Subscription Management
-description: Payment and company details.
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
+description: Payment and company details.
title: The Customers Portal
---
@@ -18,9 +18,12 @@ For more information, see [Customers that purchased through a reseller](#custome
You can sign in to Customers Portal either with your GitLab.com account or a one-time sign-in link sent to your email (if you have not yet [linked your Customers Portal account to your GitLab.com account](#link-a-gitlabcom-account)).
-NOTE:
+{{< alert type="note" >}}
+
If you registered for Customers Portal with your GitLab.com account, sign in with this account.
+{{< /alert >}}
+
To sign in to Customers Portal using your GitLab.com account:
1. Go to [Customers Portal](https://customers.gitlab.com/customers/sign_in).
@@ -33,9 +36,12 @@ To sign in to Customers Portal with your email and to receive a one-time sign-in
1. Provide the **Email** for your Customers Portal profile. You will receive an email with a one-time sign-in link.
1. In the email you received, select **Sign in**.
-NOTE:
+{{< alert type="note" >}}
+
The one-time sign-in link expires in 24 hours and can only be used once.
+{{< /alert >}}
+
## Confirm Customers Portal email address
The first time you sign in to the Customers Portal with a one-time sign-in link,
diff --git a/doc/subscriptions/gitlab_com/_index.md b/doc/subscriptions/gitlab_com/_index.md
index ba13cf5255ebe505c2a9573097492bc8f30170eb..a72ca6299b43eebfca01924e9a47f1d8b1f1c44d 100644
--- a/doc/subscriptions/gitlab_com/_index.md
+++ b/doc/subscriptions/gitlab_com/_index.md
@@ -1,18 +1,24 @@
---
stage: Fulfillment
group: Subscription Management
-description: Seat usage, compute minutes, storage limits, renewal info.
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
+description: Seat usage, compute minutes, storage limits, renewal info.
title: GitLab.com subscription
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
The GitLab SaaS subscription is being renamed to GitLab.com. During this transition, you might see references to GitLab SaaS and GitLab.com in the UI and documentation.
+{{< /alert >}}
+
GitLab.com is the GitLab multi-tenant software-as-a-service (SaaS) offering.
You don't need to install anything to use GitLab.com, you only need to
[sign up](https://gitlab.com/users/sign_up). When you sign up, you choose:
@@ -178,9 +184,12 @@ In this case, the user sees only the features available to that subscription.
### Free Guest users
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In the **Ultimate** tier, users who are assigned the Guest role do not consume a seat.
The user must not be assigned any other role, anywhere in the instance or in the namespace for GitLab.com.
@@ -212,8 +221,12 @@ This setting restricts groups from adding new billable users when there are no s
### Seat usage alerts
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348481) in GitLab 15.2 [with a flag](../../administration/feature_flags.md) named `seat_flag_alerts`.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/362041) in GitLab 15.4. Feature flag `seat_flag_alerts` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348481) in GitLab 15.2 [with a flag](../../administration/feature_flags.md) named `seat_flag_alerts`.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/362041) in GitLab 15.4. Feature flag `seat_flag_alerts` removed.
+
+{{< /history >}}
If you have the Owner role for the top-level group, an alert notifies you
of your total seat usage.
@@ -352,7 +365,7 @@ To change the group linked to a GitLab.com subscription:
[linked](../customers_portal.md#link-a-gitlabcom-account) GitLab.com account.
1. Do one of the following:
- If the subscription is not linked to a group, select **Link subscription to a group**.
- - If the subscription is already linked to a group, select **Subscription actions** (**{ellipsis_v}**) > **Change linked group**.
+ - If the subscription is already linked to a group, select **Subscription actions** ({{< icon name="ellipsis_v" >}}) > **Change linked group**.
1. Select the desired group from the **New Namespace** dropdown list. For a group to appear here, you must have the Owner role for that group.
1. If the [total number of users](#view-seat-usage) in your group exceeds the number of seats in your subscription,
you are prompted to pay for the additional users. Subscription charges are calculated based on
@@ -409,10 +422,13 @@ Prerequisites:
- You must have the Owner role.
-NOTE:
+{{< alert type="note" >}}
+
Storage subscriptions **renew automatically each year**.
You can [disable automatic subscription renewal](../self_managed/_index.md#enable-or-disable-automatic-subscription-renewal).
+{{< /alert >}}
+
### For your personal namespace
1. Sign in to GitLab.com.
diff --git a/doc/subscriptions/gitlab_com/compute_minutes.md b/doc/subscriptions/gitlab_com/compute_minutes.md
index 252b3ff82e9dced2c34e38dc87578ef1ee492234..2bf3f1910f163cb14303550c0439434b6cb7b866 100644
--- a/doc/subscriptions/gitlab_com/compute_minutes.md
+++ b/doc/subscriptions/gitlab_com/compute_minutes.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Purchase additional compute minutes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
[Compute minutes](../../ci/pipelines/compute_minutes.md) is the resource consumed
when running [CI/CD pipelines](../../ci/_index.md) on GitLab instance runners. You can find
diff --git a/doc/subscriptions/gitlab_com/gitlab_subscription_troubleshooting.md b/doc/subscriptions/gitlab_com/gitlab_subscription_troubleshooting.md
index 5eb02e7c8f4f4b7d84ffdca260c5f1c474ac69a0..40fbf2075a4ccac0b7f35a18de907d0e37788e8c 100644
--- a/doc/subscriptions/gitlab_com/gitlab_subscription_troubleshooting.md
+++ b/doc/subscriptions/gitlab_com/gitlab_subscription_troubleshooting.md
@@ -1,14 +1,17 @@
---
stage: Fulfillment
group: Subscription Management
-description: Seat usage, compute minutes, storage limits, renewal info.
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
+description: Seat usage, compute minutes, storage limits, renewal info.
title: Troubleshooting GitLab subscription
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
When you purchase or use subscriptions for GitLab.com or GitLab Self-Managed, you might encounter the following issues.
diff --git a/doc/subscriptions/gitlab_dedicated/_index.md b/doc/subscriptions/gitlab_dedicated/_index.md
index 94c58e0c6414035e209cea5e7b84423780d83067..4e989cfd7c60a16f476c9489b9d881db70fb0ba7 100644
--- a/doc/subscriptions/gitlab_dedicated/_index.md
+++ b/doc/subscriptions/gitlab_dedicated/_index.md
@@ -1,8 +1,8 @@
---
stage: GitLab Dedicated
group: Switchboard
-description: Available features and benefits.
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
+description: Available features and benefits.
title: GitLab Dedicated
---
@@ -113,9 +113,12 @@ When you add a custom hostname:
To add a custom hostname after your instance is created, submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650).
-NOTE:
+{{< alert type="note" >}}
+
Custom hostnames for GitLab Pages are not supported. If you use GitLab Pages, the URL to access the Pages site for your GitLab Dedicated instance would be `tenant_name.gitlab-dedicated.site`.
+{{< /alert >}}
+
### Application
GitLab Dedicated comes with the self-managed [Ultimate feature set](https://about.gitlab.com/pricing/feature-comparison/) with a small number of exceptions. For more information, see [Unavailable features](#unavailable-features).
@@ -128,9 +131,12 @@ GitLab Dedicated uses the [advanced search functionality](../../integration/adva
You can use [GitLab Pages](../../user/project/pages/_index.md) on GitLab Dedicated to host your static website. The domain name is `tenant_name.gitlab-dedicated.site`, where `tenant_name` is the same as your instance URL.
-NOTE:
+{{< alert type="note" >}}
+
Custom domains for GitLab Pages are not supported. For example, if you added a custom domain named `gitlab.my-company.com`, the URL to access the Pages site for your GitLab Dedicated instance would still be `tenant_name.gitlab-dedicated.site`.
+{{< /alert >}}
+
You can control access to your Pages website with:
- [GitLab Pages access control](../../user/project/pages/pages_access_control.md).
@@ -215,9 +221,12 @@ The following features are not supported:
- [Mattermost](../../integration/mattermost/_index.md)
- [Server-side Git hooks](../../administration/server_hooks.md)
-NOTE:
+{{< alert type="note" >}}
+
Access to the underlying infrastructure is only available to GitLab team members. Due to the server-side configuration, there is a security concern with running arbitrary code on services, and the possible impact on the service SLA. As an alternative, use [push rules](../../user/project/repository/push_rules.md) or [webhooks](../../user/project/integrations/webhooks.md) instead.
+{{< /alert >}}
+
### Operational features
The following operational features are not available:
diff --git a/doc/subscriptions/gitlab_dedicated/data_residency_and_high_availability.md b/doc/subscriptions/gitlab_dedicated/data_residency_and_high_availability.md
index 257e0d2b739d12a0641ee25415c70e5c85f6a40a..14a2c27b1ecb8bb0f59a2dcfb65642ea198e0e4c 100644
--- a/doc/subscriptions/gitlab_dedicated/data_residency_and_high_availability.md
+++ b/doc/subscriptions/gitlab_dedicated/data_residency_and_high_availability.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Environment Automation
-description: Data residency, isolation, availability, and scalability.
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
+description: Data residency, isolation, availability, and scalability.
title: Data residency and high availability
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
GitLab Dedicated offers enterprise-grade infrastructure and performance in a secure and reliable deployment.
@@ -61,9 +64,12 @@ GitLab Dedicated uses modified versions of the [Cloud Native Hybrid reference ar
During [onboarding](../../administration/dedicated/create_instance.md#step-2-create-your-gitlab-dedicated-instance), GitLab matches you to the closest reference architecture size based on the number of users.
-NOTE:
+{{< alert type="note" >}}
+
While the reference architectures serve as a foundation for GitLab Dedicated environments, they are not exhaustive. Additional cloud provider services beyond the standard reference architectures are used to enhance security and stability. As a result, GitLab Dedicated costs differ from standard reference architecture costs.
+{{< /alert >}}
+
For more information, see the [Current Service Level Objective](https://handbook.gitlab.com/handbook/engineering/infrastructure/team/gitlab-dedicated/slas/#current-service-level-objective).
## Disaster recovery
diff --git a/doc/subscriptions/gitlab_dedicated/maintenance.md b/doc/subscriptions/gitlab_dedicated/maintenance.md
index 743611d178bf6d427386073e46d7c6908c3593c6..79dda0d9e45e156283aa6f73196ac3bfbf1727a3 100644
--- a/doc/subscriptions/gitlab_dedicated/maintenance.md
+++ b/doc/subscriptions/gitlab_dedicated/maintenance.md
@@ -1,14 +1,17 @@
---
stage: GitLab Dedicated
group: Environment Automation
-description: Maintenance procedures, including regular upgrades, zero-downtime deployments, and emergency maintenance protocols.
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
+description: Maintenance procedures, including regular upgrades, zero-downtime deployments, and emergency maintenance protocols.
title: Maintenance
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Dedicated
+
+{{< /details >}}
GitLab Dedicated instances receive regular maintenance to ensure security, reliability, and optimal performance.
@@ -56,9 +59,12 @@ The effects of an upgrade are usually unnoticeable. However, in rare cases, a ne
If this unlikely sequence occurs, refreshing the page resolves any visual inconsistencies.
-NOTE:
+{{< alert type="note" >}}
+
Implementing a caching proxy in your network further reduces this risk.
+{{< /alert >}}
+
## Emergency maintenance
[Emergency maintenance](../../administration/dedicated/maintenance.md#emergency-maintenance) addresses high-severity issues that affect your instance's security, availability, or reliability. When critical patch releases are available, GitLab Dedicated instances are upgraded as soon as possible using emergency maintenance procedures.
diff --git a/doc/subscriptions/gitlab_dedicated_for_government/_index.md b/doc/subscriptions/gitlab_dedicated_for_government/_index.md
index ec500e600f629ed55873dfbe405b9d927a782214..dcddbd1943ef537c45871075d69ef74713425737 100644
--- a/doc/subscriptions/gitlab_dedicated_for_government/_index.md
+++ b/doc/subscriptions/gitlab_dedicated_for_government/_index.md
@@ -1,8 +1,8 @@
---
stage: GitLab Dedicated
group: US Public Sector Services
-description: Available features and benefits.
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
+description: Available features and benefits.
title: GitLab Dedicated for Government
---
@@ -23,8 +23,11 @@ GitLab Dedicated for Government is available in AWS GovCloud and meets US data r
### Advanced search
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
GitLab Dedicated for Government uses [advanced search](../../user/search/advanced_search.md).
@@ -32,9 +35,12 @@ GitLab Dedicated for Government uses [advanced search](../../user/search/advance
GitLab Dedicated for Government leverages modified versions of the [cloud native hybrid reference architectures](../../administration/reference_architectures/_index.md#cloud-native-hybrid) with high availability enabled. When [onboarding](../../administration/dedicated/create_instance.md#step-2-create-your-gitlab-dedicated-instance), GitLab matches you to the closest reference architecture size based on your number of users.
-NOTE:
+{{< alert type="note" >}}
+
The published [reference architectures](../../administration/reference_architectures/_index.md) act as a starting point in defining the cloud resources deployed inside GitLab Dedicated for Government environments, but they are not comprehensive. GitLab Dedicated leverages additional Cloud Provider services beyond what's included in the standard reference architectures for enhanced security and stability of the environment. Therefore, GitLab Dedicated for Government costs differ from standard reference architecture costs.
+{{< /alert >}}
+
#### Disaster recovery
GitLab Dedicated regularly backs up all datastores, including databases and Git repositories. These backups are tested and stored securely. For added redundancy, you can store backup copies in a separate cloud region.
@@ -43,8 +49,11 @@ GitLab Dedicated regularly backs up all datastores, including databases and Git
#### Authentication and authorization
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
GitLab Dedicated for Government supports instance-level [SAML OmniAuth](../../integration/saml.md). Your GitLab Dedicated instance acts as the service provider, and you must provide the necessary [configuration](../../integration/saml.md#configure-saml-support-in-gitlab) for GitLab to communicate with your IdP.
@@ -56,8 +65,11 @@ Data is encrypted at rest and in transit using the latest encryption standards.
#### SMTP
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
Email sent from GitLab Dedicated uses [Amazon Simple Email Service (Amazon SES)](https://aws.amazon.com/ses/). The connection to Amazon SES is encrypted.
diff --git a/doc/subscriptions/quarterly_reconciliation.md b/doc/subscriptions/quarterly_reconciliation.md
index ee60cb7b0eb000f75dc5a57ad61dca0a7433e2bb..eaba64a113fd50fd45c53063e8efd71d1d9ea212 100644
--- a/doc/subscriptions/quarterly_reconciliation.md
+++ b/doc/subscriptions/quarterly_reconciliation.md
@@ -1,14 +1,17 @@
---
stage: Fulfillment
group: Subscription Management
-description: Billing examples.
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
+description: Billing examples.
title: Quarterly reconciliation and annual true-ups
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In accordance with [the GitLab Subscription Agreement](https://about.gitlab.com/terms/),
GitLab reviews your seat usage and sends you an invoice for any overages.
diff --git a/doc/subscriptions/self_managed/_index.md b/doc/subscriptions/self_managed/_index.md
index d6d586d558a79432a68c1797a340b39f4130669f..6258ea24d6178c5d60a9a510816d04f60faa2660 100644
--- a/doc/subscriptions/self_managed/_index.md
+++ b/doc/subscriptions/self_managed/_index.md
@@ -1,14 +1,17 @@
---
stage: Fulfillment
group: Subscription Management
-description: Billable users, renewal and upgrade info.
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
+description: Billable users, renewal and upgrade info.
title: GitLab Self-Managed subscription
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
After you subscribe to GitLab, you can manage the details of your self-managed subscription.
If you experience any issues, see the [troubleshooting page](../gitlab_com/gitlab_subscription_troubleshooting.md).
@@ -21,11 +24,14 @@ To subscribe to GitLab for a GitLab Self-Managed instance:
1. After purchase, an activation code is sent to the email address associated with the Customers Portal account.
You must [add this code to your GitLab instance](../../administration/license.md).
-NOTE:
+{{< alert type="note" >}}
+
If you're purchasing a subscription for an existing **Free** GitLab Self-Managed
instance, ensure you're purchasing enough seats to
[cover your users](../../administration/admin_area.md#administering-users).
+{{< /alert >}}
+
## How GitLab bills for users
A GitLab Self-Managed subscription uses a hybrid model. You pay for a subscription
@@ -102,9 +108,12 @@ To view the number of users over subscription, go to the **Admin** area.
### Free Guest users
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In the **Ultimate** tier, users who are assigned the Guest role do not consume a seat.
The user must not be assigned any other role, anywhere in the instance.
@@ -115,11 +124,14 @@ The user must not be assigned any other role, anywhere in the instance.
can access your project.
- A user's highest assigned role is updated asynchronously and may take some time to update.
-NOTE:
+{{< alert type="note" >}}
+
If a user creates a project, they are assigned the Maintainer or Owner role.
To prevent a user from creating projects, as an administrator, you can mark the user
as [external](../../administration/external_users.md).
+{{< /alert >}}
+
## View users
View the lists of users in your instance:
@@ -259,7 +271,7 @@ You can also manually synchronize subscription data at any time.
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Subscription**.
-1. In the **Subscription details** section, select **Sync** (**{retry}**).
+1. In the **Subscription details** section, select **Sync** ({{< icon name="retry" >}}).
A synchronization job is then queued. When the job finishes, the subscription
details are updated.
@@ -379,9 +391,12 @@ This file contains the information GitLab uses to manually process
or [renewals](#renew-your-subscription). If your instance is firewalled or an
offline environment, you must provide GitLab with this information.
-WARNING:
+{{< alert type="warning" >}}
+
Do not open the license usage file. If you open the file, failures might occur when [you submit your license usage data](../../administration/license_file.md#submit-license-usage-data).
+{{< /alert >}}
+
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Subscription**.
1. In the upper-right corner, select **Export license usage file**.
@@ -400,9 +415,12 @@ The license usage file includes the following information:
- Timestamp the count was recorded (UTC)
- [Billable user](#billable-users) count
-NOTE:
+{{< alert type="note" >}}
+
A custom format is used for [dates](https://gitlab.com/gitlab-org/gitlab/blob/3be39f19ac3412c089be28553e6f91b681e5d739/config/initializers/date_time_formats.rb#L7) and [times](https://gitlab.com/gitlab-org/gitlab/blob/3be39f19ac3412c089be28553e6f91b681e5d739/config/initializers/date_time_formats.rb#L13) in CSV files.
+{{< /alert >}}
+
## Renew your subscription
You can [renew your subscription automatically](#automatic-subscription-renewal)
@@ -461,7 +479,7 @@ You cannot manually renew your subscription more than 15 days before the subscri
expires. To check when you can renew:
1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in).
-1. Select **Subscription actions** (**{ellipsis_v}**), then select **Renew subscription**
+1. Select **Subscription actions** ({{< icon name="ellipsis_v" >}}), then select **Renew subscription**
to view the date you can renew.
To manually renew your subscription:
@@ -474,9 +492,13 @@ To manually renew your subscription:
1. If renewing Premium or Ultimate products, in the **Seats** text box, enter the
total number of user seats you'll need for the upcoming year.
- NOTE:
+ {{< alert type="note" >}}
+
Make sure this number is equal to, or greater than
the number of [billable users](#billable-users) in the system at the time of renewal.
+
+ {{< /alert >}}
+
1. Optional. If the maximum number of users in your instance exceeded the number
you were licensed for in the previous subscription term, the
[overage](../quarterly_reconciliation.md) is due when you renew.
@@ -531,10 +553,10 @@ You can use the Customers Portal to enable or disable automatic subscription ren
1. Check the subscription card:
- If the card displays **Expires on DATE**, your subscription is not
set to automatically renew. To enable automatic renewal, in
- **Subscription actions** (**{ellipsis_v}**), select **Turn on auto-renew**.
+ **Subscription actions** ({{< icon name="ellipsis_v" >}}), select **Turn on auto-renew**.
- If the card displays **Auto-renews on DATE**, your subscription is set to
automatically renew. To disable automatic renewal:
- 1. In **Subscription actions** (**{ellipsis_v}**), select **Cancel subscription**.
+ 1. In **Subscription actions** ({{< icon name="ellipsis_v" >}}), select **Cancel subscription**.
1. Select a reason for cancelling.
1. Optional: In **Would you like to add anything?**, enter any relevant information.
1. Select **Cancel subscription**.
diff --git a/doc/subscriptions/subscription-add-ons.md b/doc/subscriptions/subscription-add-ons.md
index b4c959d1d6ad221af8e3630b00a25e5d64f695a0..316db40e251c9fdd93e39493661d180d2671666f 100644
--- a/doc/subscriptions/subscription-add-ons.md
+++ b/doc/subscriptions/subscription-add-ons.md
@@ -1,14 +1,17 @@
---
stage: Fulfillment
group: Provision
-description: Seat assignment, GitLab Duo add-on
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
+description: Seat assignment, GitLab Duo add-on
title: GitLab Duo add-ons
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can purchase GitLab Duo seats to give users in your organization access to more GitLab features. GitLab Duo is only available for Premium and Ultimate customers.
Access to features provided by GitLab Duo is managed through seat assignment. GitLab Duo can be assigned to any user in your group namespace or instance.
@@ -18,7 +21,7 @@ Access to features provided by GitLab Duo is managed through seat assignment. Gi
To purchase GitLab Duo Pro seats, you can use the Customers Portal, or you can contact the [GitLab Sales team](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/). To purchase GitLab Duo Enterprise, contact the [GitLab Sales team](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/).
1. Sign in to the [GitLab Customers Portal](https://customers.gitlab.com/).
-1. On the subscription card, select the vertical ellipsis (**{ellipsis_v}**).
+1. On the subscription card, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. Select **Buy GitLab Duo Pro**.
1. Enter the number of seats for GitLab Duo.
1. Review the **Purchase summary** section.
@@ -101,7 +104,7 @@ Prerequisites:
after purchase:
1. On the left sidebar, select **Subscription**.
1. In **Subscription details**, to the right of **Last sync**, select
- synchronize subscription (**{retry}**).
+ synchronize subscription ({{< icon name="retry" >}}).
1. By **Seat utilization**, select **Assign seats**.
1. To the right of the user, turn on the toggle to assign a GitLab Duo seat.
@@ -197,16 +200,19 @@ Prerequisites:
after purchase:
1. On the left sidebar, select **Subscription**.
1. In **Subscription details**, to the right of **Last sync**, select
- synchronize subscription (**{retry}**).
+ synchronize subscription ({{< icon name="retry" >}}).
1. By **Seat utilization**, select **Assign seats**.
1. To filter by users assigned to a GitLab Duo seat, in the **Filter users** bar, select **Assigned seat**, then select **Yes**.
1. User list is filtered to only users assigned a GitLab Duo seat.
## Start GitLab Duo Pro trial
-DETAILS:
-**Tier:** Premium
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
### On GitLab.com
@@ -246,9 +252,12 @@ The trial automatically synchronizes to your instance within 24 hours. After the
## Start GitLab Duo Enterprise trial
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
### On GitLab.com
diff --git a/doc/topics/autodevops/_index.md b/doc/topics/autodevops/_index.md
index 08ca6f054f6341799ddc64dc2cc4238ad107fc87..b9de0a8b665bceea0de3a64a5d92142efa52c5ce 100644
--- a/doc/topics/autodevops/_index.md
+++ b/doc/topics/autodevops/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Auto DevOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab Auto DevOps is a collection of pre-configured features and integrations
that work together to support your software delivery process.
diff --git a/doc/topics/autodevops/cicd_variables.md b/doc/topics/autodevops/cicd_variables.md
index bdd70417d0b681567af3f16a901ccb1da09e55ff..4cb34ca0a979f6e95c0e5b937223bf253fd2a5fc 100644
--- a/doc/topics/autodevops/cicd_variables.md
+++ b/doc/topics/autodevops/cicd_variables.md
@@ -67,9 +67,12 @@ Use these variables to customize and deploy your build.
## Database variables
-WARNING:
+{{< alert type="warning" >}}
+
From [GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/343988), `POSTGRES_ENABLED` is no longer set by default.
+{{< /alert >}}
+
Use these variables to integrate CI/CD with PostgreSQL databases.
| **CI/CD variable** | **Description** |
@@ -199,10 +202,13 @@ Add replica variables when you want to scale your deployments:
1. Add a replica variable as a [project CI/CD variable](../../ci/variables/_index.md#for-a-project).
1. To scale your application, redeploy it.
- WARNING:
+ {{< alert type="warning" >}}
+
Do not scale your application using Kubernetes directly. Helm might not detect the change,
and subsequent deployments with Auto DevOps can undo your changes.
+ {{< /alert >}}
+
### Custom replica variables
You can create custom replica variables with the format `<TRACK>_<ENV>_REPLICAS`:
@@ -263,9 +269,12 @@ You can also enable manual deployment in your [project settings](requirements.md
## Deploy policy for canary environments
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use a [canary environment](../../user/project/canary_deployments.md) before
deploying any changes to production.
@@ -277,9 +286,12 @@ If you set `CANARY_ENABLED`, GitLab creates two [manual jobs](../../ci/pipelines
## Incremental rollout to production
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use an incremental rollout to continuously deploy your application,
starting with only a few pods. You can increase the number of pods
@@ -326,9 +338,12 @@ With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`:
## Timed incremental rollout to production
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use a timed incremental rollout to continuously deploy your application, starting with
only a few pods.
diff --git a/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md
index f34f9518f1759af036aa41a401cac7c6244130b6..6cca86b68faf726584d69ec64528835937771401 100644
--- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md
+++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md
@@ -44,10 +44,13 @@ If you prefer, you can also create a cluster manually using `eksctl`.
Use a GitLab project template to get started. As the name suggests,
those projects provide a bare-bones application built on some well-known frameworks.
-WARNING:
+{{< alert type="warning" >}}
+
Create the application project in the group hierarchy at the same level or below the project for cluster management. Otherwise, it fails to [authorize the agent](../../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent).
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+{{< /alert >}}
+
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. Select the **Ruby on Rails** template.
1. Give your project a name, optionally a description, and make it public so that
@@ -152,9 +155,9 @@ The commit should trigger a pipeline. In the next section, we explain what each
When your pipeline runs, what is it doing?
To view the jobs in the pipeline, select the pipeline's status badge. The
-**{status_running}** icon displays when pipeline jobs are running, and updates
-without refreshing the page to **{status_success}** (for success) or
-**{status_failed}** (for failure) when the jobs complete.
+{{< icon name="status_running" >}} icon displays when pipeline jobs are running, and updates
+without refreshing the page to {{< icon name="status_success" >}} (for success) or
+{{< icon name="status_failed" >}} (for failure) when the jobs complete.
The jobs are separated into stages:
@@ -202,16 +205,16 @@ you to common environment tasks:
-- **Open live environment** (**{external-link}**) - Opens the URL of the application deployed in production
-- **Monitoring** (**{chart}**) - Opens the metrics page where Prometheus collects data
+- **Open live environment** ({{< icon name="external-link" >}}) - Opens the URL of the application deployed in production
+- **Monitoring** ({{< icon name="chart" >}}) - Opens the metrics page where Prometheus collects data
about the Kubernetes cluster and how the application
affects it in terms of memory usage, CPU usage, and latency
-- **Deploy to** (**{play}** **{chevron-lg-down}**) - Displays a list of environments you can deploy to
-- **Terminal** (**{terminal}**) - Opens a [web terminal](../../../ci/environments/_index.md#web-terminals-deprecated)
+- **Deploy to** ({{< icon name="play" >}} {{< icon name="chevron-lg-down" >}}) - Displays a list of environments you can deploy to
+- **Terminal** ({{< icon name="terminal" >}}) - Opens a [web terminal](../../../ci/environments/_index.md#web-terminals-deprecated)
session inside the container where the application is running
-- **Re-deploy to environment** (**{repeat}**) - For more information, see
+- **Re-deploy to environment** ({{< icon name="repeat" >}}) - For more information, see
[Retrying and rolling back](../../../ci/environments/deployments.md#retry-or-roll-back-a-deployment)
-- **Stop environment** (**{stop}**) - For more information, see
+- **Stop environment** ({{< icon name="stop" >}}) - For more information, see
[Stopping an environment](../../../ci/environments/_index.md#stopping-an-environment)
GitLab displays the [deploy board](../../../user/project/deploy_boards.md) below the
@@ -267,13 +270,13 @@ To fix the broken test:
1. In the left-hand directory of files, find the `test/controllers/welcome_controller_test.rb`
file, and select it to open it.
1. Change line 7 to say `You're on Rails! Powered by GitLab Auto DevOps.`
-1. On the left sidebar, select **Source Control** (**{merge}**).
+1. On the left sidebar, select **Source Control** ({{< icon name="merge" >}}).
1. Write a commit message, and select **Commit**.
Return to the **Overview** page of your merge request, and you should not only
see the test passing, but also the application deployed as a
[review application](../stages.md#auto-review-apps). You can visit it by selecting
-the **View app** **{external-link}** button to see your changes deployed.
+the **View app** {{< icon name="external-link" >}} button to see your changes deployed.
After merging the merge request, GitLab runs the pipeline on the default branch,
and then deploys the application to production.
diff --git a/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md
index 754a076650461a8191ba640467308ba279af9a9f..e09ebd7debce17b1989cf41d12473c53b91967d3 100644
--- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md
+++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Auto DevOps to deploy an application to Google Kubernetes Engine
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In this tutorial, we'll help you to get started with [Auto DevOps](../_index.md)
through an example of how to deploy an application to Google Kubernetes Engine (GKE).
@@ -43,13 +46,16 @@ or Google Drive, or create a new one.
1. Ensure you've created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
with Google Cloud Platform.
-NOTE:
+{{< alert type="note" >}}
+
Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial),
and in partnership with Google, GitLab is able to offer an additional $200 for new
GCP accounts to get started with the GitLab integration with Google Kubernetes Engine.
[Follow this link](https://cloud.google.com/partners?pcn_code=0014M00001h35gDQAQ#contact-form)
and apply for credit.
+{{< /alert >}}
+
## Create a Kubernetes cluster
To create a new cluster on Google Kubernetes Engine (GKE), use Infrastructure as Code (IaC) approach
@@ -62,10 +68,13 @@ This project is where configuration for GitLab agent resides.
Use a GitLab project template to get started. As the name suggests,
those projects provide a bare-bones application built on some well-known frameworks.
-WARNING:
+{{< alert type="warning" >}}
+
Create the application project in the group hierarchy at the same level or below the project for cluster management. Otherwise, it fails to [authorize the agent](../../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent).
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+{{< /alert >}}
+
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. Select the **Ruby on Rails** template.
1. Give your project a name, optionally a description, and make it public so that
@@ -160,9 +169,9 @@ The commit should trigger a pipeline. In the next section, we explain what each
When your pipeline runs, what is it doing?
To view the jobs in the pipeline, select the pipeline's status badge. The
-**{status_running}** icon displays when pipeline jobs are running, and updates
-without refreshing the page to **{status_success}** (for success) or
-**{status_failed}** (for failure) when the jobs complete.
+{{< icon name="status_running" >}} icon displays when pipeline jobs are running, and updates
+without refreshing the page to {{< icon name="status_success" >}} (for success) or
+{{< icon name="status_failed" >}} (for failure) when the jobs complete.
The jobs are separated into stages:
@@ -210,16 +219,16 @@ you to common environment tasks:
-- **Open live environment** (**{external-link}**) - Opens the URL of the application deployed in production
-- **Monitoring** (**{chart}**) - Opens the metrics page where Prometheus collects data
+- **Open live environment** ({{< icon name="external-link" >}}) - Opens the URL of the application deployed in production
+- **Monitoring** ({{< icon name="chart" >}}) - Opens the metrics page where Prometheus collects data
about the Kubernetes cluster and how the application
affects it in terms of memory usage, CPU usage, and latency
-- **Deploy to** (**{play}** **{chevron-lg-down}**) - Displays a list of environments you can deploy to
-- **Terminal** (**{terminal}**) - Opens a [web terminal](../../../ci/environments/_index.md#web-terminals-deprecated)
+- **Deploy to** ({{< icon name="play" >}} {{< icon name="chevron-lg-down" >}}) - Displays a list of environments you can deploy to
+- **Terminal** ({{< icon name="terminal" >}}) - Opens a [web terminal](../../../ci/environments/_index.md#web-terminals-deprecated)
session inside the container where the application is running
-- **Re-deploy to environment** (**{repeat}**) - For more information, see
+- **Re-deploy to environment** ({{< icon name="repeat" >}}) - For more information, see
[Retrying and rolling back](../../../ci/environments/deployments.md#retry-or-roll-back-a-deployment)
-- **Stop environment** (**{stop}**) - For more information, see
+- **Stop environment** ({{< icon name="stop" >}}) - For more information, see
[Stopping an environment](../../../ci/environments/_index.md#stopping-an-environment)
GitLab displays the [deploy board](../../../user/project/deploy_boards.md) below the
@@ -228,11 +237,14 @@ Kubernetes cluster, color-coded to show their status. Hovering over a square on
the deploy board displays the state of the deployment, and selecting the square
takes you to the pod's logs page.
-NOTE:
+{{< alert type="note" >}}
+
The example shows only one pod hosting the application at the moment, but you can add
more pods by defining the [`REPLICAS` CI/CD variable](../cicd_variables.md)
in **Settings > CI/CD > Variables**.
+{{< /alert >}}
+
### Work with branches
Next, create a feature branch to add content to your application:
@@ -276,13 +288,13 @@ To fix the broken test:
1. In the left-hand directory of files, find the `test/controllers/welcome_controller_test.rb`
file, and select it to open it.
1. Change line 7 to say `You're on Rails! Powered by GitLab Auto DevOps.`
-1. On the left sidebar, select **Source Control** (**{merge}**).
+1. On the left sidebar, select **Source Control** ({{< icon name="merge" >}}).
1. Write a commit message, and select **Commit**.
Return to the **Overview** page of your merge request, and you should not only
see the test passing, but also the application deployed as a
[review application](../stages.md#auto-review-apps). You can visit it by selecting
-the **View app** **{external-link}** button to see your changes deployed.
+the **View app** {{< icon name="external-link" >}} button to see your changes deployed.
After merging the merge request, GitLab runs the pipeline on the default branch,
and then deploys the application to production.
diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md
index a5435f663a19bf20e7d974a530e363746fdeeaf6..0ac47a085ab5a15dc69e5d2ff64fc540c9be6ff7 100644
--- a/doc/topics/autodevops/customize.md
+++ b/doc/topics/autodevops/customize.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Customize Auto DevOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can customize components of Auto DevOps to fit your needs. For example, you can:
@@ -96,10 +99,13 @@ For example, to build a Docker image based on based on the
To pass complex values like spaces and newlines, use Base64 encoding.
Complex, unencoded values can cause issues with character escaping.
-WARNING:
+{{< alert type="warning" >}}
+
Do not pass secrets as Docker build arguments. Secrets might persist in your image. For more information, see
[this discussion of best practices with secrets](https://github.com/moby/moby/issues/13490).
+{{< /alert >}}
+
## Custom container image
By default, [Auto Deploy](stages.md#auto-deploy) deploys a container image built and pushed to the GitLab registry by [Auto Build](stages.md#auto-build).
@@ -301,11 +307,14 @@ You can configure many Auto DevOps jobs to run in an [offline environment](../..
## PostgreSQL database support
-WARNING:
+{{< alert type="warning" >}}
+
Provisioning a PostgreSQL database by default was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387766)
in GitLab 15.8 and will no longer be the default from 16.0. To enable database provisioning, set
the associated [CI/CD variable](cicd_variables.md#database-variables).
+{{< /alert >}}
+
To support applications that require a database,
[PostgreSQL](https://www.postgresql.org/) is provisioned by default.
The credentials to access the database are preconfigured.
diff --git a/doc/topics/autodevops/multiple_clusters_auto_devops.md b/doc/topics/autodevops/multiple_clusters_auto_devops.md
index 589981f3387e252f571b7679521834bc362b71e9..020460398807f933da8882397bc0c411aa5996a6 100644
--- a/doc/topics/autodevops/multiple_clusters_auto_devops.md
+++ b/doc/topics/autodevops/multiple_clusters_auto_devops.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Multiple Kubernetes clusters for Auto DevOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When using Auto DevOps, you can deploy different environments to different Kubernetes clusters.
@@ -39,9 +42,12 @@ For deprecated, [certificate-based clusters](../../user/infrastructure/clusters/
1. [Set the environment scope of each cluster](../../user/project/clusters/multiple_kubernetes_clusters.md#setting-the-environment-scope).
1. For each cluster, [add a domain based on its Ingress IP address](../../user/project/clusters/gitlab_managed_clusters.md#base-domain).
-NOTE:
+{{< alert type="note" >}}
+
[Cluster environment scope is not respected when checking for active Kubernetes clusters](https://gitlab.com/gitlab-org/gitlab/-/issues/20351). For a multi-cluster setup to work with Auto DevOps, you must create a fallback cluster with **Cluster environment scope** set to `*`. You can set any of the clusters you've already added as a fallback cluster.
+{{< /alert >}}
+
### Example configurations
| Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` value | `KUBE CONTEXT` value | Variable environment scope | Notes |
diff --git a/doc/topics/autodevops/prepare_deployment.md b/doc/topics/autodevops/prepare_deployment.md
index 47a6521778a1220f0c5547df60c55c323787bc1b..754f3b0486582e4422a91c3f052c184ceb5a864a 100644
--- a/doc/topics/autodevops/prepare_deployment.md
+++ b/doc/topics/autodevops/prepare_deployment.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Prepare Auto DevOps for deployment
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you enable Auto DevOps without setting the base domain and deployment
strategy, GitLab can't deploy your application directly. Therefore, we
@@ -31,10 +34,13 @@ You can choose the deployment method when enabling Auto DevOps or later:
1. Choose the deployment strategy.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique
to minimize downtime and risk.
+{{< /alert >}}
+
## Auto DevOps base domain
The Auto DevOps base domain is required to use
diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md
index b3137859de4197b9287aa0b6113b50ae048a4981..9951c53f4a4ebf386c3311bab776bb7578f542f1 100644
--- a/doc/topics/autodevops/requirements.md
+++ b/doc/topics/autodevops/requirements.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Requirements for Auto DevOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Before enabling [Auto DevOps](_index.md), we recommend you to prepare it for
deployment. If you don't, you can use it to build and test your apps, and
@@ -48,10 +51,13 @@ You can choose the deployment method when enabling Auto DevOps or later:
1. Choose the deployment strategy.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique
to minimize downtime and risk.
+{{< /alert >}}
+
## Auto DevOps base domain
The Auto DevOps base domain is required to use
@@ -113,10 +119,13 @@ To make full use of Auto DevOps with Kubernetes, you need:
the Ingress manifest to be scraped by Prometheus using
`prometheus.io/scrape: "true"` and `prometheus.io/port: "10254"`.
- NOTE:
+ {{< alert type="note" >}}
+
If your cluster is installed on bare metal, see
[Auto DevOps Requirements for bare metal](#auto-devops-requirements-for-bare-metal).
+ {{< /alert >}}
+
- **Base domain** (for [Auto Review Apps](stages.md#auto-review-apps) and
[Auto Deploy](stages.md#auto-deploy))
diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md
index 305e08d6cc3ff1562d5d0a10f06cfaa749976dc9..63da5b14e48bea3ed9a6c389c828528f00506bca 100644
--- a/doc/topics/autodevops/stages.md
+++ b/doc/topics/autodevops/stages.md
@@ -5,18 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Stages of Auto DevOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The following sections describe the stages of [Auto DevOps](_index.md).
Read them carefully to understand how each one works.
## Auto Build
-NOTE:
+{{< alert type="note" >}}
+
Auto Build is not supported if Docker in Docker is not available for your GitLab Runners, like in OpenShift clusters. The OpenShift support in GitLab is tracked [in a dedicated epic](https://gitlab.com/groups/gitlab-org/-/epics/2068).
+{{< /alert >}}
+
Auto Build creates a build of the application using an existing `Dockerfile` or
Heroku buildpacks. The resulting Docker image is pushed to the
[Container Registry](../../user/packages/container_registry/_index.md), and tagged
@@ -60,11 +66,14 @@ language:
For the requirements of other languages and frameworks, read the
[Heroku buildpacks documentation](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks).
-NOTE:
+{{< alert type="note" >}}
+
Auto Test still uses Herokuish, as test suite detection is not
yet part of the Cloud Native Buildpack specification. For more information, see
[issue 212689](https://gitlab.com/gitlab-org/gitlab/-/issues/212689).
+{{< /alert >}}
+
#### Mount volumes into the build container
The variable `BUILDPACK_VOLUMES` can be used to pass volume mount definitions to the
@@ -116,12 +125,15 @@ tests, it's up to you to add them.
<!-- vale gitlab_base.Spelling = NO -->
-NOTE:
+{{< alert type="note" >}}
+
Not all buildpacks supported by [Auto Build](#auto-build) are supported by Auto Test.
Auto Test uses [Herokuish](https://gitlab.com/gitlab-org/gitlab/-/issues/212689), *not*
Cloud Native Buildpacks, and only buildpacks that implement the
[Testpack API](https://devcenter.heroku.com/articles/testpack-api) are supported.
+{{< /alert >}}
+
<!-- vale gitlab_base.Spelling = YES -->
### Currently supported languages
@@ -154,7 +166,11 @@ might want to use a [custom buildpack](customize.md#custom-buildpacks).
## Auto Code Quality
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) from GitLab Starter to GitLab Free in 13.2.
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) from GitLab Starter to GitLab Free in 13.2.
+
+{{< /history >}}
Auto Code Quality uses the
[Code Quality image](https://gitlab.com/gitlab-org/ci-cd/codequality) to run
@@ -165,8 +181,12 @@ out. The merge request widget also displays any
## Auto SAST
-> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3.
-> - Select functionality made available in all tiers beginning in 13.1
+{{< history >}}
+
+- Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3.
+- Select functionality made available in all tiers beginning in 13.1
+
+{{< /history >}}
Static Application Security Testing (SAST) runs static
analysis on the current code, and checks for potential security issues. The
@@ -192,9 +212,12 @@ For more information, see [Secret Detection](../../user/application_security/sec
## Auto Dependency Scanning
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Dependency Scanning runs analysis on the project's dependencies and checks for potential security issues.
The Auto Dependency Scanning stage is skipped on licenses other than
@@ -248,18 +271,24 @@ for the environment.
used. Previous versions of GitLab had a Tiller installed in the project
namespace.
-WARNING:
+{{< alert type="warning" >}}
+
Your apps should *not* be manipulated outside of Helm (using Kubernetes directly).
This can cause confusion with Helm not detecting the change and subsequent
deploys with Auto DevOps can undo your changes. Also, if you change something
and want to undo it by deploying again, Helm may not detect that anything changed
in the first place, and thus not realize that it needs to re-apply the old configuration.
+{{< /alert >}}
+
## Auto DAST
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Dynamic Application Security Testing (DAST) uses the popular open source tool
[OWASP ZAProxy](https://github.com/zaproxy/zaproxy) to analyze the current code
@@ -283,13 +312,16 @@ For more information, see
To use a custom target instead of the auto-deployed review apps,
set a `DAST_WEBSITE` CI/CD variable to the URL for DAST to scan.
-WARNING:
+{{< alert type="warning" >}}
+
If [DAST Full Scan](../../user/application_security/dast/browser/_index.md) is
enabled, GitLab strongly advises **not**
to set `DAST_WEBSITE` to any staging or production environment. DAST Full Scan
actively attacks the target, which can take down your application and lead to
data loss or corruption.
+{{< /alert >}}
+
### Skipping Auto DAST
You can skip DAST jobs:
@@ -302,9 +334,12 @@ You can skip DAST jobs:
## Auto Browser Performance Testing
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Auto [Browser Performance Testing](../../ci/testing/browser_performance_testing.md)
measures the browser performance of a web page with the
@@ -325,9 +360,12 @@ Any browser performance differences between the source and target branches are a
## Auto Load Performance Testing
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Auto [Load Performance Testing](../../ci/testing/load_performance_testing.md)
measures the server performance of an application with the
@@ -371,13 +409,16 @@ for the environment.
used. Previous versions of GitLab had a Tiller installed in the project
namespace.
-WARNING:
+{{< alert type="warning" >}}
+
Your apps should *not* be manipulated outside of Helm (using Kubernetes directly).
This can cause confusion with Helm not detecting the change and subsequent
deploys with Auto DevOps can undo your changes. Also, if you change something
and want to undo it by deploying again, Helm may not detect that anything changed
in the first place, and thus not realize that it needs to re-apply the old configuration.
+{{< /alert >}}
+
### GitLab deploy tokens
[GitLab Deploy Tokens](../../user/project/deploy_tokens/_index.md#gitlab-deploy-token)
@@ -389,18 +430,24 @@ automatically created.
If the GitLab Deploy Token can't be found, `CI_REGISTRY_PASSWORD` is
used.
-NOTE:
+{{< alert type="note" >}}
+
`CI_REGISTRY_PASSWORD` is only valid during deployment. Kubernetes can
successfully pull the container image during deployment, but if the image must
be pulled again, such as after pod eviction, Kubernetes cannot do so
as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`.
+{{< /alert >}}
+
### Kubernetes 1.16+
-WARNING:
+{{< alert type="warning" >}}
+
The default value for the `deploymentApiVersion` setting was changed from
`extensions/v1beta` to `apps/v1`.
+{{< /alert >}}
+
In Kubernetes 1.16 and later, a number of
[APIs were removed](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/),
including support for `Deployment` in the `extensions/v1beta1` version.
@@ -414,10 +461,13 @@ To use Auto Deploy on a Kubernetes 1.16+ cluster:
`AUTO_DEVOPS_POSTGRES_CHANNEL` set to `1`, follow the
[guide to upgrade PostgreSQL](upgrading_postgresql.md).
-WARNING:
+{{< alert type="warning" >}}
+
Follow the [guide to upgrading PostgreSQL](upgrading_postgresql.md)
to back up and restore your database before opting into version `2`.
+{{< /alert >}}
+
### Migrations
You can configure database initialization and migrations for PostgreSQL to run
diff --git a/doc/topics/autodevops/troubleshooting.md b/doc/topics/autodevops/troubleshooting.md
index 3eb39dabea76fd02bc2c764f9aed286c93d212af..9bc8ad72e38cfa5c46c8550ca6f53aaad374c061 100644
--- a/doc/topics/autodevops/troubleshooting.md
+++ b/doc/topics/autodevops/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Auto DevOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The information in this documentation page describes common errors when using
Auto DevOps, and any available workarounds.
@@ -115,12 +118,15 @@ If you receive this error, you can do one of the following actions:
database by setting `AUTO_DEVOPS_POSTGRES_DELETE_V1` to a non-empty value and
redeploying.
- WARNING:
+ {{< alert type="warning" >}}
+
Deleting the channel 1 PostgreSQL database permanently deletes the existing
channel 1 database and all its data. See
[Upgrading PostgreSQL](upgrading_postgresql.md)
for more information on backing up and upgrading your database.
+ {{< /alert >}}
+
- If you are not using the in-cluster database, you can set
`POSTGRES_ENABLED` to `false` and re-deploy. This option is especially relevant to
users of *custom charts without the in-chart PostgreSQL dependency*.
@@ -129,10 +135,13 @@ If you receive this error, you can do one of the following actions:
and persisted by Helm, regardless of whether or not your chart uses the
variable.
-WARNING:
+{{< alert type="warning" >}}
+
Setting `POSTGRES_ENABLED` to `false` permanently deletes any existing
channel 1 database for your environment.
+{{< /alert >}}
+
## `Error: unable to recognize "": no matches for kind "Deployment" in version "extensions/v1beta1"`
After upgrading your Kubernetes cluster to [v1.16+](stages.md#kubernetes-116),
diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md
index ee20ae3f5aee85251a64bc44fba2f04adcf8f6c7..4152b1604816664fb1924db5097984c95192d7cc 100644
--- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md
+++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Upgrading deployments for newer Auto Deploy dependencies
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Auto Deploy](stages.md#auto-deploy) is a feature that deploys your application to a Kubernetes cluster.
It consists of several dependencies:
@@ -184,10 +187,13 @@ include:
- template: Jobs/Deploy.latest.gitlab-ci.yml
```
-WARNING:
+{{< alert type="warning" >}}
+
Using a [beta](../../policy/development_stages_support.md#beta) or unstable `auto-deploy-image` could cause unrecoverable damage to
your environments. Do not test it with important projects or environments.
+{{< /alert >}}
+
## Resource Architectures of the `auto-deploy-app` chart
### v0 and v1 chart resource architecture
diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md
index 7025ca6f6d72b5747a4c138908bd2f3b13255705..6fd7887a90b360613040bd4c7f106e57894d1010 100644
--- a/doc/topics/autodevops/upgrading_postgresql.md
+++ b/doc/topics/autodevops/upgrading_postgresql.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Upgrading PostgreSQL for Auto DevOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When `POSTGRES_ENABLED` is `true`, Auto DevOps provides an
[in-cluster PostgreSQL database](customize.md#postgresql-database-support) for your application.
@@ -38,11 +41,14 @@ involves:
any existing channel 1 database. For more information, see
[Detected an existing PostgreSQL database](troubleshooting.md#detected-an-existing-postgresql-database).
-NOTE:
+{{< alert type="note" >}}
+
If you have configured Auto DevOps to have staging,
consider trying out the backup and restore steps on staging first, or
trying this out on a review app.
+{{< /alert >}}
+
## Take your application offline
If required, take your application offline to prevent the database from
@@ -169,17 +175,23 @@ pvc-9085e3d3-5239-11ea-9c8d-42010a8e0096 8Gi RWO Retain
## Install new PostgreSQL
-WARNING:
+{{< alert type="warning" >}}
+
Using the newer version of PostgreSQL deletes
the older 0.7.1 PostgreSQL. To prevent the underlying data from being
deleted, you can choose to retain the [persistent volume](#retain-persistent-volumes).
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
You can also
[scope](../../ci/environments/_index.md#limit-the-environment-scope-of-a-cicd-variable) the
`AUTO_DEVOPS_POSTGRES_CHANNEL`, `AUTO_DEVOPS_POSTGRES_DELETE_V1` and
`POSTGRES_VERSION` variables to specific environments, for example, `staging`.
+{{< /alert >}}
+
1. Set `AUTO_DEVOPS_POSTGRES_CHANNEL` to `2`. This opts into using the
newer 8.2.1-based PostgreSQL, and removes the older 0.7.1-based
PostgreSQL.
diff --git a/doc/topics/build_your_application.md b/doc/topics/build_your_application.md
index 0ef6406be82603e1cb64a3824645a10da87793d5..ecf070eb3c0814b9caa4fdaa2c13766b599a15bc 100644
--- a/doc/topics/build_your_application.md
+++ b/doc/topics/build_your_application.md
@@ -1,8 +1,8 @@
---
stage: none
group: unassigned
-description: Runners, jobs, pipelines, variables.
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
+description: Runners, jobs, pipelines, variables.
title: Use CI/CD to build your application
---
diff --git a/doc/topics/git/_index.md b/doc/topics/git/_index.md
index 2e6115c3b93d9131044aeda12f320f2cec47884b..f78a3fa1b646c74675ec3b38f43012e983904ec8 100644
--- a/doc/topics/git/_index.md
+++ b/doc/topics/git/_index.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
+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
description: Common Git commands and workflows.
-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"
title: Use Git
---
diff --git a/doc/topics/git/add_files.md b/doc/topics/git/add_files.md
index d9f3cda58893f7eb92c7184224a97e0145096904..bcf8409b309f1f9a7852d09e164dc2bc1e98bf44 100644
--- a/doc/topics/git/add_files.md
+++ b/doc/topics/git/add_files.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
-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"
-description: "Add, commit, and push a file to your Git repository using the command line."
+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
+description: Add, commit, and push a file to your Git repository using the command line.
title: Add files to your branch
---
diff --git a/doc/topics/git/advanced.md b/doc/topics/git/advanced.md
index f743ee645ecf8c504c10f06d741396a4c6433186..fd4e8795fd3a5e136ae666de7d739e0d4ad5c267 100644
--- a/doc/topics/git/advanced.md
+++ b/doc/topics/git/advanced.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
-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"
-description: "Introduction to Git rebase and force push, methods to resolve merge conflicts through the command line."
+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
+description: Introduction to Git rebase and force push, methods to resolve merge conflicts through the command line.
title: Advanced Git operations
---
diff --git a/doc/topics/git/basics.md b/doc/topics/git/basics.md
index 505487379bc7058f350b2408141623d26152925b..173310bf4364c3555f8017593baf6875d9233929 100644
--- a/doc/topics/git/basics.md
+++ b/doc/topics/git/basics.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
+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
description: Common Git commands and workflows.
-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"
title: Basic Git operations
---
diff --git a/doc/topics/git/cherry_pick.md b/doc/topics/git/cherry_pick.md
index 24d16dca3b83c3d5f153113d926bd28cf2678f9e..b808ffd21d20cc2dbacd38f0a54090346fff8188 100644
--- a/doc/topics/git/cherry_pick.md
+++ b/doc/topics/git/cherry_pick.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Cherry-pick a Git commit when you want to add a single commit from one branch to another."
+description: Cherry-pick a Git commit when you want to add a single commit from one branch to another.
title: Cherry-pick changes with Git
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use `git cherry-pick` to apply the changes from a specific commit to your current
working branch. Use this command to:
@@ -20,10 +23,13 @@ working branch. Use this command to:
You can also use the GitLab UI to cherry-pick. For more information,
see [Cherry-pick changes](../../user/project/merge_requests/cherry_pick_changes.md).
-WARNING:
+{{< alert type="warning" >}}
+
Use `git cherry-pick` carefully because it can create duplicate commits and potentially
complicate your project history.
+{{< /alert >}}
+
## Cherry-pick a single commit
To cherry-pick a single commit from another branch into your current working branch:
diff --git a/doc/topics/git/clone.md b/doc/topics/git/clone.md
index a52e2e11f10cbdec1912a38bd4567d028af18987..c4c8d8cd74a655ed2043d6bc816a1b639a70c384 100644
--- a/doc/topics/git/clone.md
+++ b/doc/topics/git/clone.md
@@ -60,11 +60,14 @@ the number of times you must manually authenticate, making HTTPS a seamless expe
cd <new directory>
```
-NOTE:
+{{< alert type="note" >}}
+
On Windows, if you enter your password incorrectly multiple times and an `Access denied` message appears,
add your namespace (username or group) to the path:
`git clone https://namespace@gitlab.com/gitlab-org/gitlab.git`.
+{{< /alert >}}
+
### Clone using a token
Clone with HTTPS using a token if:
@@ -232,13 +235,16 @@ Deeper integration between partial clone and sparse checkout is possible through
`--filter=sparse:oid=<blob-ish>` filter spec. This mode of filtering uses a format similar to a
`.gitignore` file to specify which files to include when cloning and fetching.
-WARNING:
+{{< alert type="warning" >}}
+
Partial clone using `sparse` filters is still experimental. It might be slow and significantly increase
[Gitaly](../../administration/gitaly/_index.md) resource utilization when cloning and fetching.
[Filter all blobs and use sparse-checkout](#filter-by-object-type) instead, because
[`git-sparse-checkout`](https://git-scm.com/docs/git-sparse-checkout) simplifies
this type of partial clone use and overcomes its limitations.
+{{< /alert >}}
+
For more details, see the Git documentation for
[`rev-list-options`](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt).
@@ -275,11 +281,14 @@ For more details, see the Git documentation for
git rev-list --all --quiet --objects --missing=print | wc -l
```
- WARNING:
+ {{< alert type="warning" >}}
+
Git integrations with `bash`, Zsh, etc and editors that automatically
show Git status information often run `git fetch` which fetches the
entire repository. Disabling or reconfiguring these integrations might be required.
+ {{< /alert >}}
+
### Remove partial clone filtering
Git repositories with partial clone filtering can have the filtering removed. To
diff --git a/doc/topics/git/commit.md b/doc/topics/git/commit.md
index ef406a424678fdeda9f969e31a93fd838996449f..21dd4deb0d3dbd4e7ecdb3b1c022633383dd3636 100644
--- a/doc/topics/git/commit.md
+++ b/doc/topics/git/commit.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
+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
description: Common commands and workflows.
-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"
title: Stage, commit, and push changes
---
@@ -75,9 +75,12 @@ you must [force an update](git_rebase.md#force-push-to-a-remote-branch).
## Push options
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you push changes to a branch, you can use client-side
[Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt).
@@ -105,10 +108,13 @@ For server-side controls and enforcement of best practices, see
You can use push options to skip a CI/CD pipeline, or pass CI/CD variables.
-NOTE:
+{{< alert type="note" >}}
+
Push options are not available for merge request pipelines. For more information,
see [issue 373212](https://gitlab.com/gitlab-org/gitlab/-/issues/373212).
+{{< /alert >}}
+
| Push option | Description | Example |
|--------------------------------|-------------|---------|
| `ci.skip` | Do not create a CI/CD pipeline for the latest push. Skips only branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). This does not skip pipelines for CI/CD integrations, such as Jenkins. | `git push -o ci.skip` |
diff --git a/doc/topics/git/file_management.md b/doc/topics/git/file_management.md
index 0c7e99d632089fa6f6af0fa99fb10f3cf77fc58f..b225975a2e346851d9b892aa416707640cf8e988 100644
--- a/doc/topics/git/file_management.md
+++ b/doc/topics/git/file_management.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
+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
description: Common commands and workflows.
-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"
title: File management
---
@@ -116,10 +116,13 @@ To add a large file into your Git repository and track it with Git LFS:
The `.gitattributes` file must be included in your commit.
It if isn't included, Git does not track the ISO file with Git LFS.
- NOTE:
- Ensure the files you're changing are not listed in a `.gitignore` file.
+ {{< alert type="note" >}}
+
+Ensure the files you're changing are not listed in a `.gitignore` file.
If they are, Git commits the change locally but doesn't push it to your upstream repository.
+ {{< /alert >}}
+
1. Commit both files to your local copy of the repository:
```shell
@@ -134,10 +137,13 @@ To add a large file into your Git repository and track it with Git LFS:
1. Create a merge request.
-NOTE:
+{{< alert type="note" >}}
+
When you add a new file type to Git LFS tracking, existing files of this type
are not converted to Git LFS. Only files of this type, added after you begin tracking, are added to Git LFS. Use `git lfs migrate` to convert existing files to use Git LFS.
+{{< /alert >}}
+
### Stop tracking a file
When you stop tracking a file with Git LFS, the file remains on disk because it's still
@@ -167,10 +173,13 @@ To stop tracking a file with Git LFS:
1. Create a merge request and request a review.
1. Merge the request into the target branch.
-NOTE:
+{{< alert type="note" >}}
+
If you delete an object tracked by Git LFS, without tracking it with `git lfs untrack`,
the object shows as `modified` in `git status`.
+{{< /alert >}}
+
### Stop tracking all files of a single type
To stop tracking all files of a particular type in Git LFS:
@@ -228,8 +237,11 @@ To configure file locks for a specific file type:
1. Push the `.gitattributes` file to the remote repository for the changes to take effect.
- NOTE:
- After a file type is registered as lockable, it is automatically marked as read-only.
+ {{< alert type="note" >}}
+
+After a file type is registered as lockable, it is automatically marked as read-only.
+
+ {{< /alert >}}
#### Configure file locks without LFS
@@ -250,33 +262,41 @@ To lock or unlock a file with exclusive file locking:
1. Open a terminal window in your repository directory.
1. Run one of the following commands:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Lock a file
+ {{< tab title="Lock a file" >}}
```shell
git lfs lock path/to/file.png
```
- :::TabTitle Unlock a file
+ {{< /tab >}}
+
+ {{< tab title="Unlock a file" >}}
```shell
git lfs unlock path/to/file.png
```
- :::TabTitle Unlock a file by ID
+ {{< /tab >}}
+
+ {{< tab title="Unlock a file by ID" >}}
```shell
git lfs unlock --id=123
```
- :::TabTitle Force unlock a file
+ {{< /tab >}}
+
+ {{< tab title="Force unlock a file" >}}
```shell
git lfs unlock --id=123 --force
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
### View locked files
@@ -299,9 +319,12 @@ LFS-Locked files
You can also [view and remove existing locks](../../user/project/file_lock.md) from the GitLab UI.
-NOTE:
+{{< alert type="note" >}}
+
When you rename an exclusively-locked file, the lock is lost. You must lock it again to keep it locked.
+{{< /alert >}}
+
### Lock and edit a file
To lock a file, edit it, and optionally unlock it:
diff --git a/doc/topics/git/forks.md b/doc/topics/git/forks.md
index 86f1ca58d2d87e28806cd890e1f3697db6f9a843..acb190893fcb2dbb4249e62b2676c7f47ecb24a3 100644
--- a/doc/topics/git/forks.md
+++ b/doc/topics/git/forks.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Fork a Git repository when you want to contribute changes back to an upstream repository you don't have permission to contribute to directly."
+description: Fork a Git repository when you want to contribute changes back to an upstream repository you don't have permission to contribute to directly.
title: Update a fork
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A fork is a personal copy of the repository and all its branches, which you create
in a namespace of your choice. You can use forks to propose changes to another project
@@ -57,9 +60,12 @@ To update your fork from the command line:
git checkout main
```
- NOTE:
+ {{< alert type="note" >}}
+
If Git identifies unstaged changes, [commit or stash](commit.md) them before continuing.
+ {{< /alert >}}
+
1. Fetch the changes from the upstream repository:
```shell
@@ -104,7 +110,7 @@ To change or add a commit to the contributor's merge request:
1. On the left sidebar, select **Search or go to** and find your project.
1. Go to **Code** > **Merge requests** and find the merge request.
1. In the upper-right corner, select **Code**, then select **Check out branch**.
-1. On the dialog, select **Copy** (**{copy-to-clipboard}**).
+1. On the dialog, select **Copy** ({{< icon name="copy-to-clipboard" >}}).
1. In your terminal, go to the cloned version of the repository, and paste the commands. For example:
```shell
diff --git a/doc/topics/git/get_started.md b/doc/topics/git/get_started.md
index 58e08f365bac4e97b54d53cad6a5755363e055fe..92cd71b1e1edc6dc0318e3790674f20bba78f061 100644
--- a/doc/topics/git/get_started.md
+++ b/doc/topics/git/get_started.md
@@ -68,10 +68,13 @@ These must be resolved manually by reviewing and editing the code.
After a successful merge, you can delete the branch if it is no longer needed.
Deleting unnecessary branches helps keep your repository organized and manageable.
-NOTE:
+{{< alert type="note" >}}
+
To ensure no work is lost, verify all changes are incorporated into the default branch
before you delete the branch after the final merge.
+{{< /alert >}}
+
For more information, see [Branches](../../user/project/repository/branches/_index.md).
## Understand the Git workflow
diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md
index 4af39c32299ea188f99e3c9d490553d0a7638ce6..08af6828ded8970f9b04e1de4fc3268eb7539881 100644
--- a/doc/topics/git/git_rebase.md
+++ b/doc/topics/git/git_rebase.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
-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"
-description: "Introduction to Git rebase and force push, methods to resolve merge conflicts through the command line."
+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
+description: Introduction to Git rebase and force push, methods to resolve merge conflicts through the command line.
title: Rebase and resolve merge conflicts
---
@@ -25,13 +25,16 @@ While most rebases are performed against `main`, you can rebase against any othe
branch. You can also specify a different remote repository.
For example, `upstream` instead of `origin`.
-WARNING:
+{{< alert type="warning" >}}
+
`git rebase` rewrites the commit history. It can cause conflicts in
shared branches and complex merge conflicts.
Instead of rebasing your branch against the default branch,
consider using `git pull origin master`. Pulling has similar
effects with less risk of compromising others' work.
+{{< /alert >}}
+
## Rebase
When you use Git to rebase, each commit is applied to your branch.
@@ -225,11 +228,14 @@ Prerequisites:
git commit -m "Resolve merge conflicts"
```
- WARNING:
+ {{< alert type="warning" >}}
+
You can run `git rebase --abort` to stop the process before this point.
Git aborts the rebase and rolls back the branch to the state
before running `git rebase`. After you run `git rebase --continue`, you cannot abort the rebase.
+ {{< /alert >}}
+
1. Continue the rebase:
```shell
diff --git a/doc/topics/git/how_to_install_git/_index.md b/doc/topics/git/how_to_install_git/_index.md
index 36b042b5b299ab2e890a91d589e39c87fe3dd4cd..810ab51782324e4e268b1c8eda58f7dd91533335 100644
--- a/doc/topics/git/how_to_install_git/_index.md
+++ b/doc/topics/git/how_to_install_git/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Source Code
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
-description: "How to install Git on your local machine."
+description: How to install Git on your local machine.
title: Install Git
---
@@ -18,9 +18,9 @@ With SSH, you can authenticate to the GitLab remote server without entering your
## Install and update Git
-::Tabs
+{{< tabs >}}
-:::TabTitle macOS
+{{< tab title="macOS" >}}
Though a version of Git is supplied by macOS, you should install the latest version of Git. A common way to
install Git is with [Homebrew](https://brew.sh/index.html).
@@ -42,7 +42,9 @@ Keep Git up to date by periodically running the following command:
brew update && brew upgrade git
```
-:::TabTitle Ubuntu Linux
+{{< /tab >}}
+
+{{< tab title="Ubuntu Linux" >}}
Though a version of Git is supplied by Ubuntu, you should install the latest version of Git. The latest version is
available using a Personal Package Archive (PPA).
@@ -69,7 +71,9 @@ Keep Git up to date by periodically running the following command:
sudo apt-get update && sudo apt-get install git
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Configure Git
@@ -81,9 +85,9 @@ You can configure your Git identity locally or globally:
- Locally: Use for the current project only.
- Globally: Use for all current and future projects.
-::Tabs
+{{< tabs >}}
-:::TabTitle Local setup
+{{< tab title="Local setup" >}}
Configure your Git identity locally to use it for the current project only.
@@ -107,7 +111,9 @@ The full name and email address should match the ones you use in GitLab.
git config --local --list
```
-:::TabTitle Global setup
+{{< /tab >}}
+
+{{< tab title="Global setup" >}}
Configure your Git identity globally to use it for all current and future projects on your machine.
@@ -131,7 +137,9 @@ The full name and email address should match the ones you use in GitLab.
git config --global --list
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Check Git configuration settings
diff --git a/doc/topics/git/lfs/_index.md b/doc/topics/git/lfs/_index.md
index 5bb21da8c4249181f921a54752e8b86575261c90..9a68ed356aa3cc503ef670ccb7e4894d8100a384 100644
--- a/doc/topics/git/lfs/_index.md
+++ b/doc/topics/git/lfs/_index.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
-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"
-description: "Use Git LFS to manage binary assets, like images and video, without bloating your Git repository's size."
+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
+description: Use Git LFS to manage binary assets, like images and video, without bloating your Git repository's size.
title: Git Large File Storage (LFS)
---
@@ -62,9 +62,12 @@ with the _upstream_ project after merge.
## Configure Git LFS for a project
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab enables Git LFS by default for both GitLab Self-Managed and GitLab SaaS.
It offers both server settings and project-specific settings.
@@ -137,9 +140,12 @@ To delete a tracked file with Git LFS, see [Remove a file](../undo.md#remove-a-f
To completely expunge all history of a file, past and present,
see [Handle sensitive information](../undo.md#handle-sensitive-information).
-WARNING:
+{{< alert type="warning" >}}
+
Expunging file history requires rewriting Git history. This action is destructive and irreversible.
+{{< /alert >}}
+
## Reduce repository size after removing large files
If you need to remove large files from your repository's history, to reduce
diff --git a/doc/topics/git/lfs/troubleshooting.md b/doc/topics/git/lfs/troubleshooting.md
index 8156fa04ce5277660dc75799094a190b5d38bfc1..f4bdd416f8481adb7f06b821ef7f44d03e63f60f 100644
--- a/doc/topics/git/lfs/troubleshooting.md
+++ b/doc/topics/git/lfs/troubleshooting.md
@@ -1,7 +1,7 @@
---
stage: Create
group: Source Code
-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"
+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
title: Troubleshooting Git LFS
---
diff --git a/doc/topics/git/merge.md b/doc/topics/git/merge.md
index eed8b2dd50eb4af3319d04dad8b907552863f727..beef96cd9c568fd4e1771cb93f44a4a17c15458e 100644
--- a/doc/topics/git/merge.md
+++ b/doc/topics/git/merge.md
@@ -1,7 +1,7 @@
---
stage: Create
group: Source Code
-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"
+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
title: Merge your branch into the main branch
---
diff --git a/doc/topics/git/project.md b/doc/topics/git/project.md
index 7ed43986484de51459107bae49299f7d0cbbc4ce..900c84b2b92067177b4ee962d65a312497f1e814 100644
--- a/doc/topics/git/project.md
+++ b/doc/topics/git/project.md
@@ -1,18 +1,22 @@
---
stage: Tenant Scale
group: Organizations
-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"
-title: 'Create a project with `git push`'
+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
+title: Create a project with `git push`
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use `git push` to add a local project repository to GitLab. After you add a repository,
GitLab creates your project in your chosen namespace.
-NOTE:
+{{< alert type="note" >}}
+
You cannot use `git push` to create projects with paths that were previously used or
[renamed](../../user/project/working_with_projects.md#rename-a-repository).
Previously used project paths have a redirect. Instead of creating a new project,
@@ -20,6 +24,8 @@ the redirect causes push attempts to redirect requests to the renamed project lo
To create a new project for a previously used or renamed project, use the UI
or the [Projects API](../../api/projects.md#create-a-project).
+{{< /alert >}}
+
Prerequisites:
<!--- To push with SSH, you must have [an SSH key](../ssh.md) that is
diff --git a/doc/topics/git/repository.md b/doc/topics/git/repository.md
index be3ae65d45bf38bba317222575f9cd13bf53951e..43ed47a5710bbf1d50d7b7ebc96bb80b5e1afa60 100644
--- a/doc/topics/git/repository.md
+++ b/doc/topics/git/repository.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "To remove unwanted large files from a Git repository and reduce its storage size, use the filter-repo command."
+description: To remove unwanted large files from a Git repository and reduce its storage size, use the filter-repo command.
title: Reduce repository size
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The size of a Git repository can significantly impact performance and storage costs.
It can differ slightly from one instance to another due to compression, housekeeping, and other factors.
@@ -36,9 +39,12 @@ Prerequisites:
- You must install [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md).
- Optional. Install [`git-sizer`](https://github.com/github/git-sizer#getting-started).
-WARNING:
+{{< alert type="warning" >}}
+
Purging files is a destructive operation. Before proceeding, ensure you have a backup of the repository.
+{{< /alert >}}
+
To purge files from a GitLab repository:
1. [Export the project](../../user/project/settings/import_export.md#export-a-project-and-its-data) that contains
@@ -125,10 +131,13 @@ a copy of your repository, and download it.
For more information about references, see
[Git references used by Gitaly](../../development/gitaly.md#git-references-used-by-gitaly).
- NOTE:
- This step fails for [protected branches](../../user/project/repository/branches/protected.md) and
+ {{< alert type="note" >}}
+
+This step fails for [protected branches](../../user/project/repository/branches/protected.md) and
[protected tags](../../user/project/protected_tags.md). To proceed, temporarily remove protections.
+ {{< /alert >}}
+
1. Wait at least 30 minutes before the next step.
1. Run the [clean up repository](../../user/project/repository/repository_size.md#clean-up-repository) process.
This process only cleans up objects that are more than 30 minutes old.
diff --git a/doc/topics/git/stash.md b/doc/topics/git/stash.md
index f8c258087c036857da7e0c699afc4da3954f2dd1..09b77f79c71a6be14de3ea8d3cf3e83535413d69 100644
--- a/doc/topics/git/stash.md
+++ b/doc/topics/git/stash.md
@@ -1,7 +1,7 @@
---
stage: Create
group: Source Code
-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"
+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
title: Stash changes for later
---
diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md
index 8982a3b1a368bfd8a6eb5c9fc517cbf39275b16a..31ba4362551bfc02a1c5536e42799d7d59e0f973 100644
--- a/doc/topics/git/troubleshooting_git.md
+++ b/doc/topics/git/troubleshooting_git.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
-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"
-description: "Debugging tips for fixing problems in Git."
+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
+description: Debugging tips for fixing problems in Git.
title: Troubleshooting Git
---
@@ -131,9 +131,12 @@ instructions in the [SSH troubleshooting](../../user/ssh_troubleshooting.md#pass
If you're a GitLab administrator with server access, you can also prevent
session timeouts by configuring SSH `keep-alive` on the client or the server.
-NOTE:
+{{< alert type="note" >}}
+
Configuring both the client and the server is unnecessary.
+{{< /alert >}}
+
**To configure SSH on the client side**:
- On UNIX, edit `~/.ssh/config` (create the file if it doesn't exist) and
diff --git a/doc/topics/git/undo.md b/doc/topics/git/undo.md
index ca02f843723f45b125f61f9fa0fd77e58f8f1e83..12475798e7218da2b472869c13a05bb2a072c208 100644
--- a/doc/topics/git/undo.md
+++ b/doc/topics/git/undo.md
@@ -216,10 +216,13 @@ The commits are now `A-B-C-D-E`.
Alternatively, [cherry-pick](../../user/project/merge_requests/cherry_pick_changes.md#cherry-pick-a-single-commit)
that commit into a new merge request.
-NOTE:
+{{< alert type="note" >}}
+
Another solution is to reset to `B` and commit `E`. However, this solution results in `A-B-E`,
which clashes with what others have locally. Don't use this solution if your branch is shared.
+{{< /alert >}}
+
### Recover undone commits
You can recall previous local commits. However, not all previous commits are available, because
@@ -281,9 +284,12 @@ of detached commits is performed, or a cleanup is run manually. Even the cleanup
You should not change the history when you're working in a public branch
or a branch that might be used by others.
-NOTE:
+{{< alert type="note" >}}
+
Never modify the commit history of your [default branch](../../user/project/repository/branches/default.md) or shared branch.
+{{< /alert >}}
+
### Modify history with `git rebase`
A branch of a merge request is a public branch and might be used by
@@ -314,10 +320,13 @@ and delete commits.
# Empty commits are commented out
```
-NOTE:
+{{< alert type="note" >}}
+
If you decide to stop a rebase, do not close your editor.
Instead, remove all uncommented lines and save.
+{{< /alert >}}
+
Use `git rebase` carefully on shared and remote branches.
Experiment locally before you push to the remote repository.
diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md
index 98cc7d73440477c61d35a48d49774579b19955e9..5bad777ac90890fb9d07252698a382a6ba7dd974 100644
--- a/doc/topics/gitlab_flow.md
+++ b/doc/topics/gitlab_flow.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'https://about.gitlab.com/blog/2023/07/27/gitlab-flow-duo/'
-remove_date: '2025-10-08'
+redirect_to: https://about.gitlab.com/blog/2023/07/27/gitlab-flow-duo/
+remove_date: "2025-10-08"
---
<!-- markdownlint-disable -->
diff --git a/doc/topics/manage_code.md b/doc/topics/manage_code.md
index abfcda2ac9aa7c8c7ef9891f695bbb3449efe8fe..db424e6fb753216d361e97ea1b270b1b00c09427 100644
--- a/doc/topics/manage_code.md
+++ b/doc/topics/manage_code.md
@@ -1,8 +1,8 @@
---
stage: none
group: unassigned
-description: Repositories, merge requests, remote development.
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
+description: Repositories, merge requests, remote development.
title: Manage your code
---
diff --git a/doc/topics/offline/_index.md b/doc/topics/offline/_index.md
index 7dbc584ee4dcb1b73227e8c164eaa655d4864976..23a6f6f955adc717c5d56c572014bc537d281efa 100644
--- a/doc/topics/offline/_index.md
+++ b/doc/topics/offline/_index.md
@@ -1,14 +1,17 @@
---
stage: Systems
group: Distribution
-description: Isolated installation.
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
+description: Isolated installation.
title: Offline GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Computers in an offline environment are isolated from the public internet as a security measure. This
page lists all the information available for running GitLab in an offline environment.
diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md
index 1e7e2bc65ce6cc1a09b481636bab1a213f951e0e..6cb19dec2bcf73cdba633baf8215fda45bd1d4e5 100644
--- a/doc/topics/offline/quick_start_guide.md
+++ b/doc/topics/offline/quick_start_guide.md
@@ -5,20 +5,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Install an offline GitLab Self-Managed instance
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This is a step-by-step guide that helps you install, configure, and use a GitLab Self-Managed
instance entirely offline.
## Installation
-NOTE:
+{{< alert type="note" >}}
+
This guide assumes the server is Ubuntu 20.04 using the [Omnibus installation method](https://docs.gitlab.com/omnibus/) and is running GitLab [Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/). Instructions for other servers may vary.
This guide also assumes the server host resolves as `my-host.internal`, which you should replace with your
server's FQDN, and that you have access to a different server with Internet access to download the required package files.
+{{< /alert >}}
+
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For a video walkthrough of this process, see [Offline GitLab Installation: Downloading & Installing](https://www.youtube.com/watch?v=TJaq4ua2Prw).
diff --git a/doc/topics/plan_and_track.md b/doc/topics/plan_and_track.md
index b8b6750c06205afaa62a6ce23142ef6157f309db..1f7a3919581361b3613cdce4d16425f62c7629ed 100644
--- a/doc/topics/plan_and_track.md
+++ b/doc/topics/plan_and_track.md
@@ -1,8 +1,8 @@
---
stage: Plan
group: Project Management
-description: Epics, issues, milestones, labels.
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
+description: Epics, issues, milestones, labels.
title: Plan and track work
---
diff --git a/doc/topics/release_your_application.md b/doc/topics/release_your_application.md
index b8336c69202e1ae073f22d757949bcaed4b4103b..e5099e9b20919c8a6cc921031b53be35fb69bfa9 100644
--- a/doc/topics/release_your_application.md
+++ b/doc/topics/release_your_application.md
@@ -1,8 +1,8 @@
---
stage: none
group: unassigned
-description: Environments, packages, review apps, GitLab Pages.
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
+description: Environments, packages, review apps, GitLab Pages.
title: Deploy and release your application
---
diff --git a/doc/topics/runner_fleet_design_guides/_index.md b/doc/topics/runner_fleet_design_guides/_index.md
index ed537479e77fbe53e850e2c155e1009d170c0683..84763f4c3bbe2580a06d9553bb24fefdd92bf518 100644
--- a/doc/topics/runner_fleet_design_guides/_index.md
+++ b/doc/topics/runner_fleet_design_guides/_index.md
@@ -1,14 +1,17 @@
---
stage: CI
group: Runner
-description: Runner Fleet.
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
+description: Runner Fleet.
title: GitLab Runner fleet configuration and best practices with the Kubernetes executor
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
This section provides a set of best practices to successfully set up GitLab Runner.
diff --git a/doc/topics/runner_fleet_design_guides/gitlab_runner_fleet_config_and_best_practices.md b/doc/topics/runner_fleet_design_guides/gitlab_runner_fleet_config_and_best_practices.md
index 3b5009a4ea185170797a131b32c970e09fde27e1..7337e0e54759581d50b45372e9dbc58fab6bb305 100644
--- a/doc/topics/runner_fleet_design_guides/gitlab_runner_fleet_config_and_best_practices.md
+++ b/doc/topics/runner_fleet_design_guides/gitlab_runner_fleet_config_and_best_practices.md
@@ -1,14 +1,17 @@
---
stage: CI
group: Runner
-description: Runner Fleet.
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
+description: Runner Fleet.
title: Design and configure a GitLab Runner fleet on Google Kubernetes Engine
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
This page describes how to analyze your CI/CD build requirements to design, configure,
and validate a GitLab Runner fleet hosted on Google Kubernetes Engine (GKE).
@@ -505,9 +508,12 @@ tests:
- my-custom-tag
```
-NOTE:
+{{< alert type="note" >}}
+
For an easier configuration, use one GitLab Runner per cluster for job profile. This approach is recommended until GitLab supports either multiple GitLab Runner installations on the same cluster or multiple `[[runners]]` section in the `config.toml` template.
+{{< /alert >}}
+
### Set up monitoring and observability
As a final step in the deployment phase, you must establish a solution to monitor the runner host environment and GitLab Runner. The infrastructure level, runner, and CI/CD job metrics provide insights into the efficiency and reliability of your CI/CD build infrastructure. They also provides the insight needed to tune and optimize the Kubernetes cluster, GitLab Runner, and CI/CD job configuration.
diff --git a/doc/topics/set_up_organization.md b/doc/topics/set_up_organization.md
index 1c1466bc35de15139cc0a88037e32b0ae9eeac9f..c2851a2c258fbda31b06666905ca20260dc32a59 100644
--- a/doc/topics/set_up_organization.md
+++ b/doc/topics/set_up_organization.md
@@ -1,8 +1,8 @@
---
stage: none
group: unassigned
-description: Users, groups, namespaces, SSH keys.
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
+description: Users, groups, namespaces, SSH keys.
title: Manage your organization
---
diff --git a/doc/tutorials/agile_sprint/_index.md b/doc/tutorials/agile_sprint/_index.md
index 5bbfb9f97c618bb537dc80d66755dfca9e48ec6c..d384c8b72e89f0d7c0c0991dd89618c6efd5100c 100644
--- a/doc/tutorials/agile_sprint/_index.md
+++ b/doc/tutorials/agile_sprint/_index.md
@@ -91,7 +91,7 @@ the "Open" list into iteration lists to schedule them for upcoming iterations.
To visualize the workflow for issues in the current iteration, create another issue board called
"Current Iteration." When you're creating the board:
-1. Select **Configure board** (**{settings}**).
+1. Select **Configure board** ({{< icon name="settings" >}}).
1. Next to **Iteration**, select **Edit**.
1. From the dropdown list, select **Current iteration**.
1. Select **Save changes**.
diff --git a/doc/tutorials/automate_runner_creation/_index.md b/doc/tutorials/automate_runner_creation/_index.md
index 15fed723b63a5a622de20f1d0f690ff1f49141d2..7cff2940ba5652ef2020ad8d9b057280c6097df0 100644
--- a/doc/tutorials/automate_runner_creation/_index.md
+++ b/doc/tutorials/automate_runner_creation/_index.md
@@ -14,12 +14,15 @@ To automate runner creation and registration:
1. [Automate GitLab Runner installation and registration](#automate-runner-installation-and-registration).
1. [View runners with the same configuration](#view-runners-with-the-same-configuration).
-NOTE:
+{{< alert type="note" >}}
+
The instructions in this tutorial describe runner creation and registration
with runner authentication tokens, which have replaced the deprecated registration
method that uses registration tokens. For more information, see
[The new runner registration workflow](../../ci/runners/new_creation_workflow.md#the-new-runner-registration-workflow).
+{{< /alert >}}
+
## Before you begin
- GitLab Runner must be installed on your GitLab instance.
@@ -42,12 +45,19 @@ to store the token, like HashiCorp Vault or the Keeper Secrets Manager Terraform
### Create a personal access token
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) the maximum allowable lifetime limit to an increased value of 400 days in GitLab 17.6 [with a flag](../../administration/feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) the maximum allowable lifetime limit to an increased value of 400 days in GitLab 17.6 [with a flag](../../administration/feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the extended maximum allowable lifetime limit is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
1. On the left sidebar, select your avatar.
1. Select **Edit profile**.
1. On the left sidebar, select **Access tokens**.
@@ -61,17 +71,27 @@ For more information, see the history.
### Create a project or group access token
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) the maximum allowable lifetime limit to an increased value of 400 days in GitLab 17.6 [with a flag](../../administration/feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) the maximum allowable lifetime limit to an increased value of 400 days in GitLab 17.6 [with a flag](../../administration/feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the extended maximum allowable lifetime limit is controlled by a feature flag.
For more information, see the history.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
Project access tokens are treated as [internal users](../../administration/internal_users.md).
If an internal user creates a project access token, that token is able to access
all projects that have visibility level set to [Internal](../../user/public_access.md).
+{{< /alert >}}
+
To create a project access token:
1. On the left sidebar, select **Search or go to** and find your project or group.
@@ -123,9 +143,9 @@ REST endpoint to create a runner:
1. Use `curl` to invoke the endpoint to create a runner:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Project
+ {{< tab title="Project" >}}
```shell
curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
@@ -136,7 +156,9 @@ REST endpoint to create a runner:
--header "PRIVATE-TOKEN: <project_access_token>"
```
- :::TabTitle Group
+ {{< /tab >}}
+
+ {{< tab title="Group" >}}
```shell
curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
@@ -147,7 +169,9 @@ REST endpoint to create a runner:
--header "PRIVATE-TOKEN: <group_access_token>"
```
- :::TabTitle Shared
+ {{< /tab >}}
+
+ {{< tab title="Shared" >}}
```shell
curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
@@ -157,7 +181,9 @@ REST endpoint to create a runner:
--header "PRIVATE-TOKEN: <personal_access_token>"
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Save the returned `token` value in a secure location or your secrets management
solution. The `token` value is returned only once in the API response.
diff --git a/doc/tutorials/boards_for_standups/_index.md b/doc/tutorials/boards_for_standups/_index.md
index 201c48104074c21069e0b6993e629055fb7844fe..30563a59683785f4ed098621a6d82f42dd8fbebc 100644
--- a/doc/tutorials/boards_for_standups/_index.md
+++ b/doc/tutorials/boards_for_standups/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Set up an issue board for a team stand-up'
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
<!-- vale gitlab_base.FutureTense = NO -->
@@ -49,7 +52,7 @@ Groups let you manage member access and share settings across projects.
To create a group:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. Select **Create group**.
1. Complete the fields:
- In **Group name**, enter `Paperclip Software Factory`.
@@ -116,7 +119,7 @@ To create a group issue board:
### Add workflow lists to your board
-1. In the upper-right corner, select **Add list** (**{plus}**).
+1. In the upper-right corner, select **Add list** ({{< icon name="plus" >}}).
1. From **New list**, select **Label**.
1. From the **Value** dropdown list, select a workflow label.
1. Select **Add to board**.
@@ -133,7 +136,7 @@ For example, you can show issues only from the current iteration or with specifi
To configure your board:
-1. On your team stand-up board, select **Configure board** (**{settings}**).
+1. On your team stand-up board, select **Configure board** ({{< icon name="settings" >}}).
1. Complete any of these fields to filter issues:
- **Milestone**: to show issues from a specific milestone.
- **Assignee**: to show issues assigned to specific team members.
@@ -153,7 +156,7 @@ You can create issues directly from your board during the team stand-up.
To create an issue:
-1. On your team stand-up board, in the `workflow::ready for development` list, select **Create new issue** (**{plus}**).
+1. On your team stand-up board, in the `workflow::ready for development` list, select **Create new issue** ({{< icon name="plus" >}}).
1. Complete the fields:
- In **Title**, enter `Redesign user profile page`
- From the **Projects** dropdown list, select **Paperclip Software Factory / Paperclip Assistant**
diff --git a/doc/tutorials/boards_for_teams/_index.md b/doc/tutorials/boards_for_teams/_index.md
index 2c3957981c7c36c3a098bcf5b980aaf2bede2441..37e6fda426bd2d391a8c5713998edbf5b360bd4f 100644
--- a/doc/tutorials/boards_for_teams/_index.md
+++ b/doc/tutorials/boards_for_teams/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Set up issue boards for team hand-off'
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
<!-- vale gitlab_base.FutureTense = NO -->
@@ -65,7 +68,7 @@ You add your users as members in the group, and assign them a role.
To create a group:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. Select **Create group**.
1. Complete the fields. Name your group `Paperclip Software Factory`.
1. Select **Create group**.
@@ -80,7 +83,7 @@ upcoming code changes.
To create a blank project:
-1. In your group, on the left sidebar, at the top, select **Create new** (**{plus}**) and then select
+1. In your group, on the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and then select
**In this group > New project/repository**.
1. Select **Create blank project**.
1. Enter the project details:
@@ -169,7 +172,7 @@ To create an issue from your board:
1. In the upper-left corner of the issue board page, select the dropdown list with the current board name.
1. Select **UX workflow**.
-1. On the `Workflow::Ready for development` list, select **Create new issue** (**{plus}**).
+1. On the `Workflow::Ready for development` list, select **Create new issue** ({{< icon name="plus" >}}).
1. Complete the fields:
1. Under **Title**, enter `Redesign user profile page`.
1. Under **Projects**, select **Paperclip Software Factory / Paperclip Assistant**.
diff --git a/doc/tutorials/build_application.md b/doc/tutorials/build_application.md
index 74bb4912c873afd0a56df40c03805391c5527cb1..513848da5fb19ab44fecd01c559d642ebd2f3452 100644
--- a/doc/tutorials/build_application.md
+++ b/doc/tutorials/build_application.md
@@ -1,8 +1,8 @@
---
stage: none
group: Tutorials
-description: CI/CD fundamentals and examples.
info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: CI/CD fundamentals and examples.
title: 'Tutorials: Build your application'
---
@@ -12,10 +12,10 @@ Use CI/CD pipelines to automatically build, test, and deploy your code.
| Topic | Description | Good for beginners |
|-------|-------------|--------------------|
-| [Create and run your first GitLab CI/CD pipeline](../ci/quick_start/_index.md) | Create a `.gitlab-ci.yml` file and start a pipeline. | **{star}** |
+| [Create and run your first GitLab CI/CD pipeline](../ci/quick_start/_index.md) | Create a `.gitlab-ci.yml` file and start a pipeline. | {{< icon name="star" >}} |
| [Create a complex pipeline](../ci/quick_start/tutorial.md) | Learn about the most commonly used GitLab CI/CD keywords by building an increasingly complex pipeline. | |
-| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Get started: Learn about CI/CD](https://www.youtube.com/watch?v=sIegJaLy2ug) (9m 02s) | Learn about the `.gitlab-ci.yml` file and how it's used. | **{star}** |
-| [GitLab CI Fundamentals](https://university.gitlab.com/learn/learning-path/gitlab-ci-fundamentals) | Learn about GitLab CI/CD and build a pipeline in this self-paced course. | **{star}** |
+| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Get started: Learn about CI/CD](https://www.youtube.com/watch?v=sIegJaLy2ug) (9m 02s) | Learn about the `.gitlab-ci.yml` file and how it's used. | {{< icon name="star" >}} |
+| [GitLab CI Fundamentals](https://university.gitlab.com/learn/learning-path/gitlab-ci-fundamentals) | Learn about GitLab CI/CD and build a pipeline in this self-paced course. | {{< icon name="star" >}} |
| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [CI deep dive](https://www.youtube.com/watch?v=ZVUbmVac-m8&list=PL05JrBw4t0KorkxIFgZGnzzxjZRCGROt_&index=27) (22m 51s) | Take a closer look at pipelines and continuous integration concepts. | |
| [Set up CI/CD in the cloud](../ci/examples/_index.md#cicd-in-the-cloud) | Learn how to set up CI/CD in different cloud-based environments. | |
| [Create a GitLab pipeline to push to Google Artifact Registry](create_gitlab_pipeline_push_to_google_artifact_registry/_index.md) | Learn how to connect GitLab to Google Cloud and create a pipeline to push images to Artifact Registry. | |
@@ -32,7 +32,7 @@ Set up runners to run jobs in a pipeline.
| Topic | Description | Good for beginners |
|-------|-------------|--------------------|
-| [Create, register, and run your own project runner](create_register_first_runner/_index.md) | Learn the basics of how to create and register a project runner that runs jobs for your project. | **{star}** |
+| [Create, register, and run your own project runner](create_register_first_runner/_index.md) | Learn the basics of how to create and register a project runner that runs jobs for your project. | {{< icon name="star" >}} |
| [Configure GitLab Runner to use the Google Kubernetes Engine](configure_gitlab_runner_to_use_gke/_index.md) | Learn how to configure GitLab Runner to use the GKE to run jobs. | |
| [Automate runner creation and registration](automate_runner_creation/_index.md) | Learn how to automate runner creation as an authenticated user to optimize your runner fleet. | |
| [Set up the Google Cloud integration](set_up_gitlab_google_integration/_index.md) | Learn how to integrate Google Cloud with GitLab and set up GitLab Runner to run jobs on Google Cloud. | |
@@ -43,6 +43,6 @@ Use GitLab Pages to publish a static website directly from your project.
| Topic | Description | Good for beginners |
|-------|-------------|--------------------|
-| [Create a Pages website from a CI/CD template](../user/project/pages/getting_started/pages_ci_cd_template.md) | Quickly generate a Pages website for your project using a CI/CD template for a popular Static Site Generator (SSG). | **{star}** |
+| [Create a Pages website from a CI/CD template](../user/project/pages/getting_started/pages_ci_cd_template.md) | Quickly generate a Pages website for your project using a CI/CD template for a popular Static Site Generator (SSG). | {{< icon name="star" >}} |
| [Create a Pages website from scratch](../user/project/pages/getting_started/pages_from_scratch.md) | Create all the components of a Pages website from a blank project. | |
-| [Build, test, and deploy your Hugo site with GitLab](hugo/_index.md) | Generate your Hugo site using a CI/CD template and GitLab Pages. | **{star}** |
+| [Build, test, and deploy your Hugo site with GitLab](hugo/_index.md) | Generate your Hugo site using a CI/CD template and GitLab Pages. | {{< icon name="star" >}} |
diff --git a/doc/tutorials/compliance_pipeline/_index.md b/doc/tutorials/compliance_pipeline/_index.md
index 81411e38ab9d38c4cdbc97f9b462fd5c30cd0dce..ddef7f10deadd82f1d2d74faae07c98e5c12774e 100644
--- a/doc/tutorials/compliance_pipeline/_index.md
+++ b/doc/tutorials/compliance_pipeline/_index.md
@@ -7,15 +7,21 @@ title: 'Tutorial: Create a compliance pipeline (deprecated)'
<!--- start_remove The following content will be removed on remove_date: '2025-08-15' -->
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/159841) in GitLab 17.3
and is planned for removal in 18.0. Use [pipeline execution policy type](../../user/application_security/policies/pipeline_execution_policies.md) instead.
This change is a breaking change. For more information, see the [migration guide](../../user/group/compliance_pipelines.md#pipeline-execution-policies-migration).
+{{< /alert >}}
+
You can use [compliance pipelines](../../user/group/compliance_pipelines.md) to ensure specific
compliance-related jobs are run on pipelines for all projects in a group. Compliance pipelines are applied
to projects through [compliance frameworks](../../user/group/compliance_frameworks.md).
@@ -43,7 +49,7 @@ Compliance frameworks are configured in top-level groups. In this tutorial, you
To create the new group:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. Select **Create group**.
1. In the **Group name** field, enter `Tutorial group`.
1. Select **Create group**.
@@ -112,7 +118,7 @@ compliance pipeline configuration in their pipelines.
To create a new project for running the compliance pipeline configuration:
1. On the left sidebar, select **Search or go to** and find the `Tutorial group` group.
-1. Select **Create new** (**{plus}**) and **New project/repository**.
+1. Select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. In the **Project name** field, enter `Tutorial project`.
1. Select **Create project**.
diff --git a/doc/tutorials/container_scanning/_index.md b/doc/tutorials/container_scanning/_index.md
index ddbc5646aa14ff5115e067a676c809e47b15b50c..5b8e25e61e6a1116f8d6a642fd18d0877f6e37bc 100644
--- a/doc/tutorials/container_scanning/_index.md
+++ b/doc/tutorials/container_scanning/_index.md
@@ -5,9 +5,12 @@ info: For assistance with this tutorial, see https://handbook.gitlab.com/handboo
title: 'Tutorial: Scan a Docker container for vulnerabilities'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use [container scanning](../../user/application_security/container_scanning/_index.md) to check for vulnerabilities
in container images stored in the [container registry](../../user/packages/container_registry/_index.md).
@@ -27,7 +30,7 @@ Container scanning configuration is added to the pipeline configuration of a pro
To create the new project
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. In **Project name**, enter `Tutorial container scanning project`.
1. In **Project URL**, select a namespace for the project.
@@ -37,7 +40,7 @@ To create the new project
To provide something for container scanning to work on, create a `Dockerfile` with very minimal configuration:
-1. In your `Tutorial container scanning project` project, select **{plus}** > **New file**.
+1. In your `Tutorial container scanning project` project, select {{< icon name="plus" >}} > **New file**.
1. Enter the filename `Dockerfile`, and provide the following contents for the file:
```Dockerfile
@@ -61,7 +64,7 @@ Now you're ready to create pipeline configuration. The pipeline configuration:
To create the pipeline configuration:
-1. In the root directory of your project, select **{plus}** > **New file**.
+1. In the root directory of your project, select {{< icon name="plus" >}} > **New file**.
1. Enter the filename `.gitlab-ci.yml`, and provide the following contents for the file:
```yaml
diff --git a/doc/tutorials/convert_personal_namespace_to_group/_index.md b/doc/tutorials/convert_personal_namespace_to_group/_index.md
index 03eb1496bc7421c574682125600e271ac24eb1c4..ce832cab542493543f77e1342a7fab8a171c70c4 100644
--- a/doc/tutorials/convert_personal_namespace_to_group/_index.md
+++ b/doc/tutorials/convert_personal_namespace_to_group/_index.md
@@ -5,9 +5,12 @@ info: For assistance with this tutorial, see https://handbook.gitlab.com/handboo
title: 'Tutorial: Convert a personal namespace into a group'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
If you've started out with a personal [namespace](../../user/namespace/_index.md), but find
that you've outgrown its capabilities, you can switch to a group namespace instead.
@@ -35,7 +38,7 @@ rename the `alex` namespace to `alex-user`, and `alex-group` namespace to the no
## Create a group
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. In **Group name**, enter a name for the group.
1. In **Group URL**, enter a path for the group, which is used as the namespace.
Don't worry about the actual path, this is only temporary. You change this URL to the username of the personal namespace in the [final step](#rename-the-new-group-namespace-to-the-original-username).
diff --git a/doc/tutorials/create_gitlab_pipeline_push_to_google_artifact_registry/_index.md b/doc/tutorials/create_gitlab_pipeline_push_to_google_artifact_registry/_index.md
index 627a5b3c2f121fe16eba3b2cf9665df67034eede..7719c7b1da63d2eec342ab0da90b1daf1c6b3e39 100644
--- a/doc/tutorials/create_gitlab_pipeline_push_to_google_artifact_registry/_index.md
+++ b/doc/tutorials/create_gitlab_pipeline_push_to_google_artifact_registry/_index.md
@@ -16,8 +16,11 @@ Learn how to connect GitLab to Google Cloud and create a GitLab pipeline using r
1. Create or select a Google Cloud project.
- NOTE:
- If you don't plan to keep the resources that you create in this procedure, then create a new Google Cloud project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
+ {{< alert type="note" >}}
+
+If you don't plan to keep the resources that you create in this procedure, then create a new Google Cloud project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
+
+ {{< /alert >}}
To create a Google Cloud project, run the following command:
diff --git a/doc/tutorials/create_register_first_runner/_index.md b/doc/tutorials/create_register_first_runner/_index.md
index 5a57c64e1f9c60e990646b7856dc5e918ab09ed3..050210e3ea5f963437182380e825a74d97ffe6f8 100644
--- a/doc/tutorials/create_register_first_runner/_index.md
+++ b/doc/tutorials/create_register_first_runner/_index.md
@@ -34,7 +34,7 @@ First, create a blank project where you can create your CI/CD pipeline and runne
To create a blank project:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details:
- In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces.
@@ -54,7 +54,7 @@ In this file, you define:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Project overview**.
-1. Select the plus icon (**{plus}**), then select **New file**.
+1. Select the plus icon ({{< icon name="plus" >}}), then select **New file**.
1. In the **Filename** field, enter `.gitlab-ci.yml`.
1. In the large text box, paste this sample configuration:
diff --git a/doc/tutorials/dependency_scanning.md b/doc/tutorials/dependency_scanning.md
index 40b593280f7ee95af9995905076ff94e99f3ce4a..07aeccfa7e863c776fdc69dafa9f0a40d5bb86b9 100644
--- a/doc/tutorials/dependency_scanning.md
+++ b/doc/tutorials/dependency_scanning.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Set up dependency scanning'
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Dependency Scanning can automatically find security vulnerabilities in your software dependencies
while you're developing and testing your applications. For example, dependency scanning lets you
diff --git a/doc/tutorials/develop.md b/doc/tutorials/develop.md
index d5e6045f748c00e3abb2bf91bf2cb2c7dcb38919..17f033a05bc6c3b76cb0df2b1acfe0aba9b4cc07 100644
--- a/doc/tutorials/develop.md
+++ b/doc/tutorials/develop.md
@@ -1,8 +1,8 @@
---
stage: none
group: Tutorials
-description: Integrations with third-party services.
info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Integrations with third-party services.
title: 'Tutorials: Extend with GitLab'
---
diff --git a/doc/tutorials/export_sbom.md b/doc/tutorials/export_sbom.md
index 68ccb84031893a34ea4cb8c7c7eb4da35a79a94a..1586fbf3d28f7100b2610ded09c9f30c8b9fd472 100644
--- a/doc/tutorials/export_sbom.md
+++ b/doc/tutorials/export_sbom.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Export dependency list in SBOM format'
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Dependency Scanning output can be exported to the CycloneDX JSON format.
diff --git a/doc/tutorials/fuzz_testing/_index.md b/doc/tutorials/fuzz_testing/_index.md
index 563c29d8a57902d0eb56dc7c5a074551a80aa4f5..85d0a152f6fb598153f03f6aaff1003bb10bdcdb 100644
--- a/doc/tutorials/fuzz_testing/_index.md
+++ b/doc/tutorials/fuzz_testing/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Perform fuzz testing in GitLab'
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Coverage-guided fuzz testing](../../user/application_security/coverage_fuzzing/_index.md#coverage-guided-fuzz-testing-process) sends unexpected, malformed, or random data to your application, and then monitors
your application for unstable behaviors and crashes.
diff --git a/doc/tutorials/gitlab_navigation.md b/doc/tutorials/gitlab_navigation.md
index 861b9edb94c949a190a1cf8715f02cf18cb1aaee..10808c1387f187a41e0581a1079a872625b72e77 100644
--- a/doc/tutorials/gitlab_navigation.md
+++ b/doc/tutorials/gitlab_navigation.md
@@ -1,8 +1,8 @@
---
stage: none
group: Tutorials
-description: Introduction to the product.
info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Introduction to the product.
title: 'Tutorials: Find your way around GitLab'
---
@@ -11,10 +11,10 @@ and running quickly.
| Topic | Description | Good for beginners |
|-------|-------------|--------------------|
-| [GitLab with Git Essentials](https://university.gitlab.com/courses/gitlab-with-git-essentials-s2) | Learn the basics of Git and GitLab in this self-paced course. | **{star}** |
-| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Use GitLab for DevOps](https://www.youtube.com/watch?v=7q9Y1Cv-ib0) (12m 34s) | Use GitLab through the entire DevOps lifecycle, from planning to monitoring. | **{star}** |
-| [Use the left sidebar to navigate GitLab](left_sidebar/_index.md) | Start navigating the GitLab UI. | **{star}** |
-| [Use Markdown at GitLab](../user/markdown.md) | GitLab Flavored Markdown (GLFM) is used in many areas of GitLab, for example, in merge requests. | **{star}** |
+| [GitLab with Git Essentials](https://university.gitlab.com/courses/gitlab-with-git-essentials-s2) | Learn the basics of Git and GitLab in this self-paced course. | {{< icon name="star" >}} |
+| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Use GitLab for DevOps](https://www.youtube.com/watch?v=7q9Y1Cv-ib0) (12m 34s) | Use GitLab through the entire DevOps lifecycle, from planning to monitoring. | {{< icon name="star" >}} |
+| [Use the left sidebar to navigate GitLab](left_sidebar/_index.md) | Start navigating the GitLab UI. | {{< icon name="star" >}} |
+| [Use Markdown at GitLab](../user/markdown.md) | GitLab Flavored Markdown (GLFM) is used in many areas of GitLab, for example, in merge requests. | {{< icon name="star" >}} |
| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [GitLab Continuous Delivery overview](https://www.youtube.com/watch?v=M7rBDZYsx8U&list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED&index=193) (17m 2s) | Learn how to use GitLab features to continuously build, test, and deploy iterative code changes. | |
| [Productivity tips](https://about.gitlab.com/blog/2021/02/18/improve-your-gitlab-productivity-with-these-10-tips/) | Get tips to help make you a productive GitLab user. | |
| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Introducing GitLab Service Desk](https://www.youtube.com/watch?v=LDVQXv3I5rI) (6m 50s) | Learn how GitLab [Service Desk](../user/project/service_desk/_index.md) provides an integrated help desk solution to enhance customer support workflows. This video covers key features, such as [custom email addresses](../user/project/service_desk/configure.md#custom-email-address) and [email templates](../user/project/service_desk/configure.md#customize-emails-sent-to-external-participants), ticket management, [comment templates](../user/profile/comment_templates.md), [CRM integration](../user/crm/_index.md), automation using `gitlab-triage` in scheduled CI/CD pipelines, and analytics and [insights](../user/project/insights/_index.md). | |
diff --git a/doc/tutorials/hugo/_index.md b/doc/tutorials/hugo/_index.md
index 433df6035d9305b3a3572dc868eda96b2d627fd2..6d560f21787694f9d24d62ab4717313a0df8ac4c 100644
--- a/doc/tutorials/hugo/_index.md
+++ b/doc/tutorials/hugo/_index.md
@@ -49,7 +49,7 @@ If you haven't done so already, create a blank GitLab project for your Hugo site
To create a blank project, in GitLab:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details:
- In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces.
diff --git a/doc/tutorials/idea_management/_index.md b/doc/tutorials/idea_management/_index.md
index 911082d7c9256f3983358055cf7dd73205d90a45..845e00e409fb999c2dfa154f4d68cb23eb15db72 100644
--- a/doc/tutorials/idea_management/_index.md
+++ b/doc/tutorials/idea_management/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Set up a project for idea management'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
<!-- vale gitlab_base.FutureTense = NO -->
@@ -46,7 +49,7 @@ A project contains the issues that will be used to track ideas.
To create a blank project:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details.
- For **Project name**, enter `Idea management tutorial`.
@@ -77,9 +80,12 @@ handbook published with [GitLab Pages](../../user/project/pages/_index.md).
## Create scoped labels
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Next, you'll create labels to add to ideas to represent the status workflow.
@@ -95,11 +101,14 @@ used together.
For example, if you add the `status::backlog` label to an issue that already has `status::in review`, the
previous one is removed.
-NOTE:
+{{< alert type="note" >}}
+
Scoped labels are available in the Premium and Ultimate tier.
If you're on the Free tier, you can use regular labels instead.
However, they aren't mutually exclusive.
+{{< /alert >}}
+
To create each label:
1. On the left sidebar, select **Search or go to** and find your project.
diff --git a/doc/tutorials/infrastructure.md b/doc/tutorials/infrastructure.md
index 6babf57a564f491cdfdad31b7e35c3c86c446cf6..d2fb0f49271857e5b1b95ebbb73fcb5e409271aa 100644
--- a/doc/tutorials/infrastructure.md
+++ b/doc/tutorials/infrastructure.md
@@ -1,8 +1,8 @@
---
stage: none
group: Tutorials
-description: GitOps, Kubernetes deployments.
info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: GitOps, Kubernetes deployments.
title: 'Tutorials: Manage your infrastructure'
---
@@ -11,5 +11,5 @@ configure the infrastructure for your application.
| Topic | Description | Good for beginners |
|-------|-------------|--------------------|
-| [Get started connecting a Kubernetes cluster to GitLab](../user/clusters/agent/getting_started.md) | Learn how to set up the agent for Kubernetes with Flux for GitOps. | **{star}** |
-| [Get started deploying to Kubernetes](../user/clusters/agent/getting_started_deployments.md) | Learn how to deploy to a Kubernetes cluster with GitLab CI/CD. | **{star}** |
+| [Get started connecting a Kubernetes cluster to GitLab](../user/clusters/agent/getting_started.md) | Learn how to set up the agent for Kubernetes with Flux for GitOps. | {{< icon name="star" >}} |
+| [Get started deploying to Kubernetes](../user/clusters/agent/getting_started_deployments.md) | Learn how to deploy to a Kubernetes cluster with GitLab CI/CD. | {{< icon name="star" >}} |
diff --git a/doc/tutorials/install_gitlab_single_node/_index.md b/doc/tutorials/install_gitlab_single_node/_index.md
index f5b486fc501580022a8dd098345731346a8426b4..2e7ca5bffca633120d16ffade4b433c7d5950217 100644
--- a/doc/tutorials/install_gitlab_single_node/_index.md
+++ b/doc/tutorials/install_gitlab_single_node/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Install and secure a single node GitLab instance'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
In this tutorial you will learn how to install and securely configure a single
node GitLab instance that can accommodate up to
@@ -155,10 +158,13 @@ they add an extra layer of security.
1. Open a new file with your editor under `/etc/sysctl.d`, for example
`/etc/sysctl.d/99-gitlab-hardening.conf`, and add the following.
- NOTE:
- The naming and source directory decide the order of processing, which is
+ {{< alert type="note" >}}
+
+The naming and source directory decide the order of processing, which is
important because the last parameter processed might override earlier ones.
+ {{< /alert >}}
+
```plaintext
##
## The following help mitigate out of bounds, null pointer dereference, heap and
diff --git a/doc/tutorials/issue_triage/_index.md b/doc/tutorials/issue_triage/_index.md
index 77129d0f1d8fd899204cba6833d306c64ce1f7a7..f51ee08ede747aa20cb7134073fc8b90d1b6d62d 100644
--- a/doc/tutorials/issue_triage/_index.md
+++ b/doc/tutorials/issue_triage/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Set up a project for issue triage'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
<!-- vale gitlab_base.FutureTense = NO -->
@@ -44,7 +47,7 @@ If you already have a project you're working in, proceed to
To create a blank project:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details.
- For **Project name**, enter `Issue triage tutorial`.
@@ -84,9 +87,12 @@ handbook published with [GitLab Pages](../../user/project/pages/_index.md).
## Create scoped labels
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Next, you'll create labels to add to issues to categorize them.
@@ -102,11 +108,14 @@ used together.
For example, if you add the `type::feature` label to an issue that already has `type::bug`, the
previous one is removed.
-NOTE:
+{{< alert type="note" >}}
+
Scoped labels are available in the Premium and Ultimate tier.
If you're on the Free tier, you can use regular labels instead.
However, they aren't mutually exclusive.
+{{< /alert >}}
+
To create each label:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -141,7 +150,7 @@ To learn what happens when you sort by priority or label priority, see
To prioritize a label:
-1. On the Labels page, next to a label you want to prioritize, select the star (**{star-o}**).
+1. On the Labels page, next to a label you want to prioritize, select the star ({{< icon name="star-o" >}}).
This label now appears at the top of the label list, under **Prioritized labels**.
1. To change the relative priority of these labels, drag them up and down the list.
The labels higher in the list get higher priority.
@@ -185,7 +194,7 @@ You can create issues for bugs as you find them (hopefully not too many!).
To create an issue from your **Issue triage (by severity)** board:
-1. On the **Open** list, select **Create new issue** (**{plus}**).
+1. On the **Open** list, select **Create new issue** ({{< icon name="plus" >}}).
The **Open** list shows issues that don't fit any other board list.
If you already know which severity label your issue should have, you can create it directly from that label list.
diff --git a/doc/tutorials/learn_git.md b/doc/tutorials/learn_git.md
index 8ddacfaad9511a7b689979b7b50515be99dada1b..a6770e333353e1fcabe70fff8386894782d10877 100644
--- a/doc/tutorials/learn_git.md
+++ b/doc/tutorials/learn_git.md
@@ -1,8 +1,8 @@
---
stage: none
group: Tutorials
-description: Git basics.
info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Git basics.
title: 'Tutorials: Learn Git'
---
@@ -11,8 +11,8 @@ the most out of GitLab.
| Topic | Description | Good for beginners |
|-------|-------------|--------------------|
-| [Make your first Git commit](make_first_git_commit/_index.md) | Create a project, edit a file, and commit changes to a Git repository from the command line. | **{star}** |
-| [Start using Git on the command line](../topics/git/commands.md) | Learn how to set up Git, clone repositories, and work with branches. | **{star}** |
+| [Make your first Git commit](make_first_git_commit/_index.md) | Create a project, edit a file, and commit changes to a Git repository from the command line. | {{< icon name="star" >}} |
+| [Start using Git on the command line](../topics/git/commands.md) | Learn how to set up Git, clone repositories, and work with branches. | {{< icon name="star" >}} |
| [Take advantage of Git rebase](https://about.gitlab.com/blog/2022/10/06/take-advantage-of-git-rebase/) | Learn how to use the `rebase` command in your workflow. | |
| [Update Git commit messages](update_commit_messages/_index.md) | Learn how to update commit messages and push the changes to GitLab. | |
| [Git cheat sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) | Download a PDF of common Git commands. | |
diff --git a/doc/tutorials/left_sidebar/_index.md b/doc/tutorials/left_sidebar/_index.md
index 39c0993811e8c364a809f36ec8d86d16431d6972..98733bfe9a89500d473af6912effd2f003eca5e0 100644
--- a/doc/tutorials/left_sidebar/_index.md
+++ b/doc/tutorials/left_sidebar/_index.md
@@ -5,12 +5,19 @@ info: For assistance with this tutorial, see https://handbook.gitlab.com/handboo
title: 'Tutorial: Use the left sidebar to navigate GitLab'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9044) in GitLab 16.0.
-> - In 16.0 through 16.5, you can turn the sidebar off by selecting your avatar and turning off the **New navigation** toggle.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9044) in GitLab 16.0.
+- In 16.0 through 16.5, you can turn the sidebar off by selecting your avatar and turning off the **New navigation** toggle.
+
+{{< /history >}}
Follow this tutorial to learn how to use the new left sidebar to navigate the UI.
@@ -22,9 +29,12 @@ merge requests, and to-do items.
-NOTE:
+{{< alert type="note" >}}
+
If you have hidden the left sidebar, you can display it temporarily by hovering your cursor over the left edge of the GitLab window.
+{{< /alert >}}
+
The next area of the left sidebar changes based on the information you're viewing. For example,
you might be viewing a project, exploring projects or groups, or viewing your profile.
To switch to other areas of the left sidebar, use **Search or go to**.
@@ -55,7 +65,7 @@ The left sidebar now shows project-specific options.
You can pin menu items if you tend to use them frequently.
1. Expand the sections until you are viewing the item you want to pin.
-1. Hover over and select the pin (**{thumbtack}**).
+1. Hover over and select the pin ({{< icon name="thumbtack" >}}).
@@ -63,9 +73,12 @@ The item is displayed in the **Pinned** section:
-NOTE:
+{{< alert type="note" >}}
+
The items you pin while you're viewing a project are different than the items you pin while viewing a group.
+{{< /alert >}}
+
## Use a more focused view
On the left sidebar, you can also choose a more focused view into the areas you have access to.
diff --git a/doc/tutorials/make_first_git_commit/_index.md b/doc/tutorials/make_first_git_commit/_index.md
index 286c0e459c60b5933f4ba769cd8dabb3712b184c..db11832bb23a94556ad962ad170b1fdabd216879 100644
--- a/doc/tutorials/make_first_git_commit/_index.md
+++ b/doc/tutorials/make_first_git_commit/_index.md
@@ -88,7 +88,7 @@ Here's an overview of what we're going to do:
To start, create a sample project in GitLab.
-1. In GitLab, on the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. In GitLab, on the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. For **Project name**, enter `My sample project`. The project slug is generated for you.
This slug is the URL you can use to access the project after it's created.
1. Ensure **Initialize repository with a README** is selected.
@@ -240,11 +240,14 @@ to the default branch (`main`).
git push
```
-NOTE:
+{{< alert type="note" >}}
+
For this tutorial, you merge your branch directly to the default branch for your
repository. In GitLab, you typically use a [merge request](../../user/project/merge_requests/_index.md)
to merge your branch.
+{{< /alert >}}
+
### View your changes in GitLab
You did it! You updated the `README.md` file in your branch, and you merged those changes
diff --git a/doc/tutorials/manage_user/_index.md b/doc/tutorials/manage_user/_index.md
index d40031b2a5efd3c699d8333e737cc61c13366026..b116f7e74020c7169180b35ef13625c6758a3d1d 100644
--- a/doc/tutorials/manage_user/_index.md
+++ b/doc/tutorials/manage_user/_index.md
@@ -5,9 +5,12 @@ info: For assistance with this tutorial, see https://handbook.gitlab.com/handboo
title: 'Tutorial: Set up your organization'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
In GitLab, you set up and manage your company's GitLab organization by:
@@ -48,7 +51,7 @@ You first create a group, Development, to serve as the parent group for the whol
software development organization.
1. Open GitLab Self-Managed.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. Select **Create group**.
1. In **Group name**, enter `Development`.
1. Enter `development-group` for the group in **Group URL**. You see a message
@@ -213,7 +216,7 @@ Go back to the parent group and remove everyone except Alex Smith:
1. On the left sidebar, select **Search or go to** and find the parent group.
1. Select **Manage > Members**.
-1. On the member row you want to remove, select the vertical ellipsis (**{ellipsis_v}**)
+1. On the member row you want to remove, select the vertical ellipsis ({{< icon name="ellipsis_v" >}})
and then select **Remove member**.
1. In the **Remove member** confirmation box, select the
**Also remove direct user membership from subgroups and projects** checkbox.
@@ -374,7 +377,7 @@ that work, you are going to create a project in the Development parent group, an
add different users to that project.
1. On the left sidebar, select **Search or go to** and find the **Development** group.
-1. Select **Create new** (**{plus}**) and **New project/repository**.
+1. Select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details:
- In the **Project name** field, enter `Release 2.0` as the name of your project.
diff --git a/doc/tutorials/merge_requests/homepage.md b/doc/tutorials/merge_requests/homepage.md
index 675070b87d9ffe087c9cc1c74e1f45dc1489b024..21a87e0bd0371d3dc9f06df96b25bebb134fb34b 100644
--- a/doc/tutorials/merge_requests/homepage.md
+++ b/doc/tutorials/merge_requests/homepage.md
@@ -2,21 +2,31 @@
stage: Create
group: Code Review
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
-description: "How the GitLab UI helps you track merge requests from creation to merging."
-title: "Tutorial: Understand your merge requests on the Merge requests homepage"
+description: How the GitLab UI helps you track merge requests from creation to merging.
+title: 'Tutorial: Understand your merge requests on the Merge requests homepage'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13448) in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `merge_request_dashboard`. Disabled by default.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/480854) on GitLab.com in GitLab 17.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13448) in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `merge_request_dashboard`. Disabled by default.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/480854) on GitLab.com in GitLab 17.9.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
This tutorial introduces you to the new user interface for managing merge requests.
Whether you're an author awaiting review, or a reviewer providing feedback, this page
@@ -48,9 +58,9 @@ GitLab shows the total number of **Active** merge requests on the left sidebar o
-- 31 open issues (**{issue-type-issue}**)
-- 8 active merge requests (**{merge-request-open}**)
-- 29 to-do items (**{todo-done}**)
+- 31 open issues ({{< icon name="issue-type-issue" >}})
+- 8 active merge requests ({{< icon name="merge-request-open" >}})
+- 29 to-do items ({{< icon name="todo-done" >}})
## The review process for merge requests
diff --git a/doc/tutorials/move_personal_project_to_group/_index.md b/doc/tutorials/move_personal_project_to_group/_index.md
index 563f1713fc0c683a231ba668fde609c85492fad2..6ba09c406ef2e3dc52617a96b9c46fb692025ed6 100644
--- a/doc/tutorials/move_personal_project_to_group/_index.md
+++ b/doc/tutorials/move_personal_project_to_group/_index.md
@@ -5,9 +5,12 @@ info: For assistance with this tutorial, see https://handbook.gitlab.com/handboo
title: 'Tutorial: Move your personal project to a group'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
If you created a project under a [personal namespace](../../user/namespace/_index.md),
you can perform common tasks, like managing issues, merge requests,
@@ -43,7 +46,7 @@ Maintainer role for the group.
If you don't have a group, create one:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. In **Group name**, enter a name for the group.
1. In **Group URL**, enter a path for the group, which is used as the namespace.
1. Choose the [visibility level](../../user/public_access.md).
@@ -71,12 +74,15 @@ You are redirected to the project's new page.
If you have more than one personal project, you can repeat these steps for each
project.
-NOTE:
+{{< alert type="note" >}}
+
For more information about these migration steps,
see [Transferring your project into another namespace](../../user/project/settings/migrate_projects.md#transfer-a-project-to-another-namespace).
A migration might result in follow-up work to update the project path in
your related resources and tools, such as websites and package managers.
+{{< /alert >}}
+
### Work with your group
You can now view your project in your group:
diff --git a/doc/tutorials/observability/observability_django_tutorial.md b/doc/tutorials/observability/observability_django_tutorial.md
index c01c84bad9e7f48b80054147c3b08234894f748b..a63ce1f17196877b9dbbcc3794feee82c809e4bb 100644
--- a/doc/tutorials/observability/observability_django_tutorial.md
+++ b/doc/tutorials/observability/observability_django_tutorial.md
@@ -5,11 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Use GitLab Observability with a Django application'
---
-FLAG:
+{{< alert type="flag" >}}
+
The availability of this feature is controlled by a feature flag.
For more information, see the history of the [**Distributed tracing** feature](../../development/tracing.md).
<!-- Update this note when observability_features flag is removed -->
+{{< /alert >}}
+
In this tutorial, we'll show you how to create, configure, instrument, and monitor a Django application using GitLab observability features.
<!-- vale gitlab_base.SentenceSpacing = NO -->
@@ -28,7 +31,7 @@ To follow along this tutorial, you should have:
First, create a GitLab project and a corresponding access token.
This tutorial uses the project name `animals`.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details.
- In the **Project name** field, enter `animals`.
diff --git a/doc/tutorials/observability/observability_dotnet_tutorial.md b/doc/tutorials/observability/observability_dotnet_tutorial.md
index 7c7d0d25efd34e71773d5483b5f9ed7e353ec247..0e4532f6e91ee44a14d74e0748ba93793182c79f 100644
--- a/doc/tutorials/observability/observability_dotnet_tutorial.md
+++ b/doc/tutorials/observability/observability_dotnet_tutorial.md
@@ -5,11 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Use GitLab Observability with a .NET application'
---
-FLAG:
+{{< alert type="flag" >}}
+
The availability of this feature is controlled by a feature flag.
For more information, see the history of the [**Distributed tracing** feature](../../development/tracing.md).
<!-- Update this note when observability_features flag is removed -->
+{{< /alert >}}
+
In this tutorial, you'll learn how to create, configure, instrument, and monitor a .NET Core application using GitLab Observability features.
## Before you begin
@@ -24,7 +27,7 @@ To follow along this tutorial, you must have:
First, create a GitLab project and a corresponding access token.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details.
- In the **Project name** field, enter `dotnet-O11y-tutorial`.
@@ -199,7 +202,7 @@ Next, we'll create a .NET web application that we can instrument. For this tutor
```
1. Find your project ID:
- 1. On the `dotnet-O11y-tutorial` project overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**).
+ 1. On the `dotnet-O11y-tutorial` project overview page, in the upper-right corner, select **Actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Copy project ID**. Save the copied ID for later.
1. Configure your application with instrumentation.
diff --git a/doc/tutorials/observability/observability_java_tutorial.md b/doc/tutorials/observability/observability_java_tutorial.md
index 2b589f660d6a607ae95985f5ef87daa8e684cdcf..f2372198a81c2712116e19dd9cd01fa09253cab7 100644
--- a/doc/tutorials/observability/observability_java_tutorial.md
+++ b/doc/tutorials/observability/observability_java_tutorial.md
@@ -22,7 +22,7 @@ To follow along this tutorial, you must have:
First, create a GitLab project and a corresponding access token.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. Select **Spring** and then **Use template**.
1. Enter the project details.
diff --git a/doc/tutorials/observability/observability_nodejs_tutorial.md b/doc/tutorials/observability/observability_nodejs_tutorial.md
index 24cda748b074ff425f9aea8f1ab737765521f570..b56fa0224723825cae6997818b4cef6d8009bf24 100644
--- a/doc/tutorials/observability/observability_nodejs_tutorial.md
+++ b/doc/tutorials/observability/observability_nodejs_tutorial.md
@@ -5,11 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Use GitLab Observability with a NodeJS application'
---
-FLAG:
+{{< alert type="flag" >}}
+
The availability of this feature is controlled by a feature flag.
For more information, see the history of the [**Distributed tracing** feature](../../development/tracing.md).
<!-- Update this note when observability_features flag is removed -->
+{{< /alert >}}
+
In this tutorial, you'll learn how to configure, instrument, and monitor a NodeJS application using GitLab Observability features.
## Before you begin
@@ -25,7 +28,7 @@ Take a moment and make sure you have the following:
First, create a new GitLab project and a corresponding access token.
This tutorial uses the project name `nodejs-O11y-tutorial`.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. Select **Use template** for NodeJS Express.
1. Enter the project details.
@@ -66,7 +69,7 @@ Next, we need to instrument the NodeJS application.
```
1. Find your project ID:
- 1. On the `nodejs-O11y-tutorial` project overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**).
+ 1. On the `nodejs-O11y-tutorial` project overview page, in the upper-right corner, select **Actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Copy project ID**. Save the copied ID for later.
1. Configure and run your project with instrumentation:
diff --git a/doc/tutorials/observability/observability_rails_tutorial.md b/doc/tutorials/observability/observability_rails_tutorial.md
index cd9d3f33c88e140485397943fa9ce6c5e5369f0d..b521c921045c81885aa3bee3890cfba21a175d71 100644
--- a/doc/tutorials/observability/observability_rails_tutorial.md
+++ b/doc/tutorials/observability/observability_rails_tutorial.md
@@ -5,11 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Use GitLab Observability with a Ruby on Rails application'
---
-FLAG:
+{{< alert type="flag" >}}
+
The availability of this feature is controlled by a feature flag.
For more information, see the history of the [**Distributed tracing** feature](../../development/tracing.md).
<!-- Update this note when observability_features flag is removed -->
+{{< /alert >}}
+
In this tutorial, you'll learn how to create, configure, instrument, and monitor a Ruby on Rails application using GitLab Observability features.
## Before you begin
@@ -25,7 +28,7 @@ Take a moment and make sure you have the following:
First, create a new GitLab project and a corresponding access token.
This tutorial uses the project name `animals`.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details.
- In the **Project name** field, enter `animals`.
@@ -88,7 +91,7 @@ To create an application:
```
1. Find your project ID:
- 1. On the `animal` project overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**).
+ 1. On the `animal` project overview page, in the upper-right corner, select **Actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Copy project ID**. Save the copied ID for later.
1. Edit `.env` and add the following code:
diff --git a/doc/tutorials/plan_and_track.md b/doc/tutorials/plan_and_track.md
index fc66dea2a16a555301aa10bbf7415343e6476e0e..cab17dc21c9bd03cc128fc3f3dadd0d61b8324f2 100644
--- a/doc/tutorials/plan_and_track.md
+++ b/doc/tutorials/plan_and_track.md
@@ -1,8 +1,8 @@
---
stage: none
group: Tutorials
-description: Planning, agile, issue boards.
info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Planning, agile, issue boards.
title: 'Tutorials: Plan and track your work'
---
@@ -11,14 +11,14 @@ issues, epics, and more.
| Topic | Description | Good for beginners |
|-------|-------------|--------------------|
-| [GitLab Agile Project Management](https://university.gitlab.com/courses/gitlab-agile-project-management-s2) | Learn how to use planning features to manage your projects in this self-paced course. | **{star}** |
+| [GitLab Agile Project Management](https://university.gitlab.com/courses/gitlab-agile-project-management-s2) | Learn how to use planning features to manage your projects in this self-paced course. | {{< icon name="star" >}} |
| [Build a protected workflow for your project](protected_workflow/_index.md) | Set up a workflow for your teams, and enforce protections with approval rules. | |
| [Run an agile iteration](agile_sprint/_index.md) | Use group, projects, and iterations to run an agile development iteration. | |
-| [Use GitLab for Kanban](kanban/_index.md) | Use issue boards, scoped labels, and value stream analytics for Kanban. | **{star}** |
+| [Use GitLab for Kanban](kanban/_index.md) | Use issue boards, scoped labels, and value stream analytics for Kanban. | {{< icon name="star" >}} |
| [Use GitLab for Scrum](scrum_events/_index.md) | Learn to run core Scrum ceremonies and workflows in GitLab. | |
-| [Set up a project for idea management](idea_management/_index.md) | Use an issue board and scoped labels to manage ideas in a team. | **{star}** |
-| [Set up a project for issue triage](issue_triage/_index.md) | Use labels to set up a project for issue triage. | **{star}** |
-| [Set up issue boards for team hand-off](boards_for_teams/_index.md) | Use issue boards and scoped labels to set up collaboration across many teams. | **{star}** |
-| [Set up an issue board for team stand-up](boards_for_standups/_index.md) | Use issue boards and workflow labels to facilitate team stand-ups. | **{star}** |
+| [Set up a project for idea management](idea_management/_index.md) | Use an issue board and scoped labels to manage ideas in a team. | {{< icon name="star" >}} |
+| [Set up a project for issue triage](issue_triage/_index.md) | Use labels to set up a project for issue triage. | {{< icon name="star" >}} |
+| [Set up issue boards for team hand-off](boards_for_teams/_index.md) | Use issue boards and scoped labels to set up collaboration across many teams. | {{< icon name="star" >}} |
+| [Set up an issue board for team stand-up](boards_for_standups/_index.md) | Use issue boards and workflow labels to facilitate team stand-ups. | {{< icon name="star" >}} |
| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Epics and issue boards](https://www.youtube.com/watch?v=eQUnHwbKEkY) | Find out how to use epics and issue boards for project management. | |
| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Portfolio Planning - Portfolio Management](https://www.youtube.com/watch?v=d9scVJUIF4c) | Find out how manage your portfolio with requirements, issues, epics, milestones, and time tracking. | |
diff --git a/doc/tutorials/product_analytics_onboarding_website_project/_index.md b/doc/tutorials/product_analytics_onboarding_website_project/_index.md
index c12d3c1935d8243aa1dae252d2e3423432b0325f..2268fb727287673fcd1b3abd369c9bf8dbddbc67 100644
--- a/doc/tutorials/product_analytics_onboarding_website_project/_index.md
+++ b/doc/tutorials/product_analytics_onboarding_website_project/_index.md
@@ -5,10 +5,13 @@ info: For assistance with this tutorial, see https://handbook.gitlab.com/handboo
title: 'Tutorial: Set up product analytics in a GitLab Pages website project'
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
Understanding how your users engage with your website or application is important for making data-driven decisions.
By identifying the most and least used features by your users, your team can decide where and how to spend their time effectively.
@@ -41,7 +44,7 @@ Here, you'll create a project for a plain HTML website.
To create a project:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. Select the **Pages/Plain HTML** template.
1. In the **Project name** text box, enter a name (for example `My website`).
diff --git a/doc/tutorials/protected_workflow/_index.md b/doc/tutorials/protected_workflow/_index.md
index 4fc3be72a7607ac50dff220af6a5948b6baa45fd..71921575b03aa8f54fefafc5c97f048a91203fca 100644
--- a/doc/tutorials/protected_workflow/_index.md
+++ b/doc/tutorials/protected_workflow/_index.md
@@ -1,16 +1,19 @@
---
stage: Create
group: Code Review
-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"
-description: "Use this tutorial to build a protected workflow for your GitLab project."
+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
+description: Use this tutorial to build a protected workflow for your GitLab project.
title: 'Tutorial: Build a protected workflow for your project'
---
<!-- vale gitlab_base.FutureTense = NO -->
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When your team starts a new project, they need a workflow that balances efficiency
with appropriate reviews. In GitLab, you can create user groups, combine those
@@ -40,7 +43,7 @@ example project named "Excelsior", and creates a minimal approval workflow for t
Before setting up Excelsior Project, you should create a group to own
the project. Here, you'll set up the Engineering group:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. Select **Create group**.
1. For **Group name**, enter `Engineering`.
1. For the **Group URL**, enter `engineering`.
@@ -134,7 +137,7 @@ To create the new `excelsior` project:
1. On the left sidebar, select **Search or go to** and
search for `engineering`. Select the group named `Engineering`.
1. On the overview page for the `engineering` group, on the left sidebar, at the top,
- select **Create new** (**{plus}**) and **In this group > New project/repository**.
+ select **Create new** ({{< icon name="plus" >}}) and **In this group > New project/repository**.
1. Select **Create blank project**.
1. Enter the project details:
- In the **Project name** field, enter `Excelsior`. The **Project slug** should
@@ -160,15 +163,18 @@ the right subgroup. This example sets up four rules:
- Frontend engineers should review changes to frontend files.
- Backend engineers should review changes to backend files.
-NOTE:
+{{< alert type="note" >}}
+
GitLab Free supports only optional reviews. To make reviews required, you need
GitLab Premium or Ultimate.
+{{< /alert >}}
+
To add a CODEOWNERS file to your `excelsior` project:
1. On the left sidebar, select **Search or go to** and
search for `Excelsior`. Select the project named `Excelsior`.
-1. Next to the branch name, select the plus icon (**{plus}**), then **New file**:
+1. Next to the branch name, select the plus icon ({{< icon name="plus" >}}), then **New file**:
1. For **Filename**, enter `CODEOWNERS`. This will create a file named `CODEOWNERS`
in the root directory of your project.
diff --git a/doc/tutorials/reviews/_index.md b/doc/tutorials/reviews/_index.md
index 281b9a8e330674d55d5056b175b2e43cd33c75a7..e23be9d1e4887c95fe00e515ef9427e2b571a3bb 100644
--- a/doc/tutorials/reviews/_index.md
+++ b/doc/tutorials/reviews/_index.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Review
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
-description: "Use merge request reviews to discuss and improve code before it is merged into your project."
+description: Use merge request reviews to discuss and improve code before it is merged into your project.
title: 'Tutorial: Review a merge request'
---
@@ -41,7 +41,7 @@ To review a merge request:
1. On the left sidebar, select **Search or go to** and find your project.
1. Either:
- Press <kbd>Shift</kbd> + <kbd>r</kbd> to go to your **Review requests** page.
- - On the left sidebar, select **Merge requests** (**{merge-request}**) **> Review requests**.
+ - On the left sidebar, select **Merge requests** ({{< icon name="merge-request" >}}) **> Review requests**.
## Understand the structure of merge requests
@@ -132,7 +132,7 @@ more information, scan through the issue descriptions.
you can gain some idea of what aspects of the proposed changes need your attention.
In this example, both Thomas and Nick are reviewers. Thomas has not yet reviewed
- (**{dotted-circle}**) the merge request. Nick has reviewed and approved (**{check-circle}**):
+ ({{< icon name="dotted-circle" >}}) the merge request. Nick has reviewed and approved ({{< icon name="check-circle" >}}):
@@ -151,16 +151,19 @@ Now you're ready to read the proposed changes. For large merge requests,
skim the changes before diving in. Build your understanding of what to
expect before you begin to read changes line by line.
-NOTE:
+{{< alert type="note" >}}
+
The diffs displayed in the **Changes** tab are dense with information. To learn
how to get the most out of this page, see
[Changes in merge requests](../../user/project/merge_requests/changes.md).
+{{< /alert >}}
+
### Skim changes for an overview
When you first open the **Changes** page, focus on the broader details first:
-- **What files have changed?** Expand the file browser (**{file-tree}**) to see
+- **What files have changed?** Expand the file browser ({{< icon name="file-tree" >}}) to see
the list of changed files. Are you familiar with these files? What part of the
codebase are these files in?
@@ -308,7 +311,7 @@ First, write your comments you want to attach to specific lines or files:
1. Select the **Changes** tab.
1. When you find lines you want to ask questions about, or provide feedback on,
- select **Add a comment to this line** (**{comment}**) in the gutter. This expands
+ select **Add a comment to this line** ({{< icon name="comment" >}}) in the gutter. This expands
the diff lines and displays a comment box.
1. You can also
[select multiple lines](../../user/project/merge_requests/reviews/suggestions.md#multi-line-suggestions),
@@ -360,7 +363,7 @@ your review. It's time to think broadly, one last time.
- If the changes need more work, select **Request changes**.
If you [approve a merge request](../../user/project/merge_requests/approvals/_index.md#approve-a-merge-request)
-and are shown in the reviewer list, a green check mark **{check-circle-filled}**
+and are shown in the reviewer list, a green check mark {{< icon name="check-circle-filled" >}}
displays next to your name.
## Perform cleanup tasks
diff --git a/doc/tutorials/scan_execution_policy/_index.md b/doc/tutorials/scan_execution_policy/_index.md
index 3363361065182b39b5e763de9ac91ec83ac51662..ca86c9a8e3c96a917bbb7295659736e1eec6e847 100644
--- a/doc/tutorials/scan_execution_policy/_index.md
+++ b/doc/tutorials/scan_execution_policy/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Set up a scan execution policy'
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This tutorial shows you how to create and apply a
[scan execution policy](../../user/application_security/policies/scan_execution_policies.md).
diff --git a/doc/tutorials/scan_result_policy/_index.md b/doc/tutorials/scan_result_policy/_index.md
index 7332496cfe4e2cc9b30910e3b9b20c83cbbf6959..bb1d9a6828c4a1f998189165869430ff7d3d8fb7 100644
--- a/doc/tutorials/scan_result_policy/_index.md
+++ b/doc/tutorials/scan_result_policy/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Set up a merge request approval policy'
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This tutorial shows you how to create and configure a [merge request approval policy](../../user/application_security/policies/merge_request_approval_policies.md). These policies can be set to take action based on scan results.
For example, in this tutorial, you'll set up a policy that requires approval from two specified users if a vulnerability is detected in a merge request.
@@ -27,7 +30,7 @@ The namespace used for this tutorial must:
## Create a test project
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Complete the fields.
- **Project name**: `sast-scan-result-policy`.
@@ -75,7 +78,7 @@ Nice work, you've created a merge request approval policy. To test it, create so
1. On the left sidebar, select **Search or go to** and find the `sast-scan-result-policy` project.
1. Select **Code > Repository**.
-1. From the **Add** (**{plus}**) dropdown list, select **New file**.
+1. From the **Add** ({{< icon name="plus" >}}) dropdown list, select **New file**.
1. In the **Filename** field enter `main.ts`.
1. In the file's content, copy the following:
diff --git a/doc/tutorials/scrum_events/_index.md b/doc/tutorials/scrum_events/_index.md
index 50ca75bb75b6b9758a3f6cd43b86256a01cc5e20..c16a7cb53fd5e2d08ef0298b4f1ab6ca749bdd6c 100644
--- a/doc/tutorials/scrum_events/_index.md
+++ b/doc/tutorials/scrum_events/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Use GitLab to facilitate Scrum'
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
<!-- vale gitlab_base.FutureTense = NO -->
@@ -99,7 +102,7 @@ It will contain your boards, features (epics), story (issue) roll up, and labels
To create a group:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. Select **Create group**.
1. In the **Group name** text box, enter the name of the group. For a list of words that cannot be used as group names, see
[reserved names](../../user/reserved_names.md).
@@ -119,7 +122,7 @@ Your project will contain the stories that roll up to your parent group.
To create a blank project:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details:
- In the **Project name** field, enter the name of your project. See the
@@ -333,7 +336,7 @@ Use each list in your release planning board to represent the following time hor
Next, create a new epic in the `priority::now` list:
-1. On the top of the **`priority::now`** list, select the **New epic** (**{plus}**) icon.
+1. On the top of the **`priority::now`** list, select the **New epic** ({{< icon name="plus" >}}) icon.
1. Enter the new epic's title:
```plaintext
@@ -479,7 +482,7 @@ Provide all team members the appropriate time to contribute and collaborate.
1. Select **Plan > Issue boards**.
1. In the upper-left corner, select the dropdown list with the current board name.
1. Select **Backlog**.
-1. In the list for the upcoming sprint, select **Create new issue** (**{plus-square}**).
+1. In the list for the upcoming sprint, select **Create new issue** ({{< icon name="plus-square" >}}).
1. Enter the issue's title: `Release Planning`.
1. Select **Create issue**.
1. Open the issue and create a discussion thread for each story assigned to the upcoming sprint.
diff --git a/doc/tutorials/scrum_events/standups_retrospectives_velocity.md b/doc/tutorials/scrum_events/standups_retrospectives_velocity.md
index 12c8599f5670537a08b886be504b2784396fad2e..1bc4d80a912aeb19f8efe746c80750cfbf26043d 100644
--- a/doc/tutorials/scrum_events/standups_retrospectives_velocity.md
+++ b/doc/tutorials/scrum_events/standups_retrospectives_velocity.md
@@ -123,10 +123,13 @@ For example, if you set the goal to deliver four to ten user stories per iterati
with a point value greater than three into two or more smaller stories.
Ideally, your team should work toward splitting or combining stories until they weigh one or two.
-NOTE:
+{{< alert type="note" >}}
+
Stakeholders should never use story points to measure the team's performance or
[compare one team to another](https://towardsdatascience.com/why-story-points-are-a-horrible-metric-for-software-engineers-421bc8971f11).
+{{< /alert >}}
+
## Velocity and volatility
Over time, teams can use story points to understand their velocity.
diff --git a/doc/tutorials/secure_application.md b/doc/tutorials/secure_application.md
index 3775f0e60a7fd63064313e7c0f46440342c9360e..f617c28b6681f2d28aa1444796d821f7de5d89c4 100644
--- a/doc/tutorials/secure_application.md
+++ b/doc/tutorials/secure_application.md
@@ -1,8 +1,8 @@
---
stage: none
group: Tutorials
-description: Dependency and compliance scanning.
info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+description: Dependency and compliance scanning.
title: 'Tutorials: Secure your application and check compliance'
---
@@ -10,13 +10,13 @@ GitLab can check your application for security vulnerabilities and that it meets
| Topic | Description | Good for beginners |
|-------|-------------|--------------------|
-| [Set up dependency scanning](dependency_scanning.md) | Learn how to detect vulnerabilities in an application's dependencies. | **{star}** |
-| [Export Dependency List in SBOM format](export_sbom.md) | Learn how to export an application's dependencies to the CycloneDX SBOM format. | **{star}** |
-| [Create a compliance pipeline](compliance_pipeline/_index.md) | Learn how to create compliance pipelines for your groups. | **{star}** |
-| [Set up a merge request approval policy](scan_result_policy/_index.md) | Learn how to configure a merge request approval policy that takes action based on scan results. | **{star}** |
-| [Set up a scan execution policy](scan_execution_policy/_index.md) | Learn how to create a scan execution policy to enforce security scanning of your project. | **{star}** |
-| [Scan a Docker container for vulnerabilities](container_scanning/_index.md) | Learn how to use container scanning templates to add container scanning to your projects. | **{star}** |
-| [Protect your project with secret push protection](../user/application_security/secret_detection/push_protection_tutorial.md) | Enable secret push protection in your project. | **{star}** |
-| [Remove a secret from your commits](../user/application_security/secret_detection/remove_secrets_tutorial.md) | Learn how to remove a secret from your commit history. | **{star}** |
+| [Set up dependency scanning](dependency_scanning.md) | Learn how to detect vulnerabilities in an application's dependencies. | {{< icon name="star" >}} |
+| [Export Dependency List in SBOM format](export_sbom.md) | Learn how to export an application's dependencies to the CycloneDX SBOM format. | {{< icon name="star" >}} |
+| [Create a compliance pipeline](compliance_pipeline/_index.md) | Learn how to create compliance pipelines for your groups. | {{< icon name="star" >}} |
+| [Set up a merge request approval policy](scan_result_policy/_index.md) | Learn how to configure a merge request approval policy that takes action based on scan results. | {{< icon name="star" >}} |
+| [Set up a scan execution policy](scan_execution_policy/_index.md) | Learn how to create a scan execution policy to enforce security scanning of your project. | {{< icon name="star" >}} |
+| [Scan a Docker container for vulnerabilities](container_scanning/_index.md) | Learn how to use container scanning templates to add container scanning to your projects. | {{< icon name="star" >}} |
+| [Protect your project with secret push protection](../user/application_security/secret_detection/push_protection_tutorial.md) | Enable secret push protection in your project. | {{< icon name="star" >}} |
+| [Remove a secret from your commits](../user/application_security/secret_detection/remove_secrets_tutorial.md) | Learn how to remove a secret from your commit history. | {{< icon name="star" >}} |
| [Get started with GitLab application security](../user/application_security/get-started-security.md) | Follow recommended steps to set up security tools. | |
| [GitLab Security Essentials](https://university.gitlab.com/courses/security-essentials) | Learn about the essential security capabilities of GitLab in this self-paced course. | |
diff --git a/doc/tutorials/update_commit_messages/_index.md b/doc/tutorials/update_commit_messages/_index.md
index edf1ef87dd14ce5b738b118756ba59bb5af1e3b7..83ba5624695d2315b59ab58cc6d3c57c2e8f17f9 100644
--- a/doc/tutorials/update_commit_messages/_index.md
+++ b/doc/tutorials/update_commit_messages/_index.md
@@ -1,13 +1,16 @@
---
stage: Create
group: Source Code
-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"
+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
title: 'Tutorial: Update Git commit messages'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Occasionally, after you've made a few commits to your branch, you realize you need
to update one or more commit messages. Perhaps you found a typo, or some automation warned you
@@ -57,7 +60,7 @@ disabled to authenticate from the CLI. Alternatively, you can [use an SSH key to
The first step is to get a clone of the repository on your local machine:
1. In GitLab, on your project's overview page, in the upper-right corner, select **Code**.
-1. In the dropdown list, copy the URL for your repository by selecting **{copy-to-clipboard}** next to:
+1. In the dropdown list, copy the URL for your repository by selecting {{< icon name="copy-to-clipboard" >}} next to:
- **Clone with HTTPS** if your GitLab account uses basic username and password authentication.
- **Clone with SSH** if you use SSH to authenticate with GitLab.
1. Now switch to the CLI (Terminal, PowerShell, or similar) on your local machine, and go to
diff --git a/doc/tutorials/update_git_remote_url/_index.md b/doc/tutorials/update_git_remote_url/_index.md
index e5f390293f97300da65edc9827f83d583d5180ab..8f09368f6dd2cd22bc9ea6db44f3276fb3973353 100644
--- a/doc/tutorials/update_git_remote_url/_index.md
+++ b/doc/tutorials/update_git_remote_url/_index.md
@@ -1,13 +1,16 @@
---
stage: Create
group: Source Code
-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"
+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
title: 'Tutorial: Update Git remote URLs'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Update your Git remote URLs if:
@@ -15,10 +18,13 @@ Update your Git remote URLs if:
- Your organization has moved your projects to a new GitLab instance with a new domain name.
- The project was renamed to a new path in the same GitLab instance.
-NOTE:
+{{< alert type="note" >}}
+
If you don't have an existing local working copy from the old remote, then you don't need this tutorial.
You can instead clone the project from the new GitLab URL.
+{{< /alert >}}
+
This tutorial explains how to update the remote URL for your local repository without:
- Losing any of your local changes that are incomplete.
diff --git a/doc/tutorials/website_project_with_analytics/_index.md b/doc/tutorials/website_project_with_analytics/_index.md
index f9534600966a2244e096e0fa318d062c72ce4c5c..292f314834da93508e31334f18bad2e7a5cf5633 100644
--- a/doc/tutorials/website_project_with_analytics/_index.md
+++ b/doc/tutorials/website_project_with_analytics/_index.md
@@ -5,9 +5,12 @@ info: For assistance with this tutorial, see https://handbook.gitlab.com/handboo
title: 'Tutorial: Set up an analytics-powered website project'
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you work on a complex project (for example, a website), you likely collaborate with other people to build and maintain it.
The way you collaborate and communicate in your team can make or break the project, so you want processes in place that help team members follow and achieve the common goal.
@@ -41,7 +44,7 @@ Here, you'll create a project for a Hugo website.
To create a project:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. Select the **Pages/Hugo** template.
1. In the **Project name** text box, enter a name (for example `My website`).
diff --git a/doc/update/_index.md b/doc/update/_index.md
index 8e109ebb898796d391419df94bcdc88310e28302..1ebe1e14d5170e75a6394297774fcc14909c182e 100644
--- a/doc/update/_index.md
+++ b/doc/update/_index.md
@@ -1,14 +1,17 @@
---
stage: Systems
group: Distribution
-description: Latest version instructions.
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
+description: Latest version instructions.
title: Upgrading GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Upgrading GitLab is a relatively straightforward process, but the complexity can increase based on:
@@ -63,14 +66,16 @@ To upgrade GitLab:
Depending on the installation method and your GitLab version, there are multiple
official ways to upgrade GitLab:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux packages (Omnibus)
+{{< tab title="Linux packages (Omnibus)" >}}
As part of a GitLab upgrade, the [Linux package upgrade guide](package/_index.md) contains the specific steps to follow
to upgrade a Linux package instance.
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
GitLab can be deployed into a Kubernetes cluster using Helm. For production deployments,
the setup follows the [Cloud Native Hybrid](../administration/reference_architectures/_index.md#cloud-native-hybrid)
@@ -87,13 +92,17 @@ A full cloud-native deployment is [not supported](../administration/reference_ar
for production. However, instructions on how to upgrade such an environment are in
[a separate document](https://docs.gitlab.com/charts/installation/upgrade.html).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
GitLab provides official Docker images for both Community and Enterprise
editions, and they are based on the Omnibus package. See how to
[install GitLab using Docker](../install/docker/_index.md).
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
- [Upgrading Community Edition and Enterprise Edition from source](upgrading_from_source.md) -
The guidelines for upgrading Community Edition and Enterprise Edition from source.
@@ -108,7 +117,9 @@ can still be found in the Git repository:
- [Old upgrading guidelines for Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/tree/11-8-stable/doc/update)
- [Old upgrading guidelines for Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/-/tree/11-8-stable-ee/doc/update)
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Pre-upgrade and post-upgrade checks
@@ -185,9 +196,12 @@ Below you can find some guides to help you change GitLab editions.
### Community to Enterprise Edition
-NOTE:
+{{< alert type="note" >}}
+
The following guides are for subscribers of the Enterprise Edition only.
+{{< /alert >}}
+
If you wish to upgrade your GitLab installation from Community to Enterprise
Edition, follow the guides below based on the installation method:
diff --git a/doc/update/background_migrations.md b/doc/update/background_migrations.md
index 9fba2f92990faadfff37a809cb11c39abad2c78e..0616ab7729928eaa5df785fa6336dffa41ad767b 100644
--- a/doc/update/background_migrations.md
+++ b/doc/update/background_migrations.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrations for upgrades
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
When upgrading GitLab, there are two types of migrations to check:
@@ -18,8 +21,12 @@ Read below for detailed information about the two types of migrations.
## Database background migrations
-> - Feature [flag](../user/feature_flags.md) `execute_batched_migrations_on_schedule` [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/329511) in GitLab 13.12.
-> - For GitLab Self-Managed, administrators can opt to [disable it](../development/database/batched_background_migrations.md#enable-or-disable-background-migrations).
+{{< history >}}
+
+- Feature [flag](../user/feature_flags.md) `execute_batched_migrations_on_schedule` [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/329511) in GitLab 13.12.
+- For GitLab Self-Managed, administrators can opt to [disable it](../development/database/batched_background_migrations.md#enable-or-disable-background-migrations).
+
+{{< /history >}}
Certain releases may require different migrations to be finished before you
update to the newer version. Two kinds of migrations exist. They differ, and you
@@ -120,10 +127,13 @@ advanced users who understand the risks of doing so.
##### Pause batched background migrations
-WARNING:
+{{< alert type="warning" >}}
+
There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to each feature's history for more details.
+{{< /alert >}}
+
To pause an ongoing batched background migration,
[disable the batched background migrations feature](../development/database/batched_background_migrations.md#enable-or-disable-background-migrations).
Disabling the feature completes the current batch of migrations, then waits to start
@@ -175,28 +185,45 @@ Use the following database queries to see the state of the current batched backg
##### Automatic batch size optimization
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60133) in GitLab 13.2 [with a flag](../administration/feature_flags.md) named `optimize_batched_migrations`. Enabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60133) in GitLab 13.2 [with a flag](../administration/feature_flags.md) named `optimize_batched_migrations`. Enabled by default.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's history for more details.
-FLAG:
+{{< /alert >}}
+
+{{< alert type="flag" >}}
+
On GitLab Self-Managed, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `optimize_batched_migrations`.
On GitLab.com, this feature is available. On GitLab Dedicated, this feature is not available.
+{{< /alert >}}
+
To maximize throughput of batched background migrations (in terms of the number of tuples updated per time unit), batch sizes are automatically adjusted based on how long the previous batches took to complete.
##### Parallel execution
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104027) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `batched_migrations_parallel_execution`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/372316) in GitLab 15.11.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120808) in GitLab 16.1. Feature flag `batched_migrations_parallel_execution` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104027) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `batched_migrations_parallel_execution`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/372316) in GitLab 15.11.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120808) in GitLab 16.1. Feature flag `batched_migrations_parallel_execution` removed.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's history for more details.
+{{< /alert >}}
+
To speed up the execution of batched background migrations, two migrations are executed at the same time.
[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) can change
@@ -249,7 +276,7 @@ Prerequisites:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Monitoring > Background migrations**.
1. Select the **Failed** tab. This displays a list of failed batched background migrations.
-1. Select a failed batched background migration to retry by clicking on the retry button (**{retry}**).
+1. Select a failed batched background migration to retry by clicking on the retry button ({{< icon name="retry" >}}).
To monitor the retried batched background migrations, you can
[check the status of batched background migrations](#check-the-status-of-batched-background-migrations)
@@ -260,9 +287,9 @@ on a regular interval.
To manually finish a batched background migration that failed with an error,
use the information in the failure error logs or the database:
-::Tabs
+{{< tabs >}}
-:::TabTitle From the failure error logs
+{{< tab title="From the failure error logs" >}}
1. [View the failure error logs](../development/database/batched_background_migrations.md#viewing-failure-error-logs)
and look for an `An error has occurred, all later migrations canceled` error message, like this:
@@ -294,7 +321,9 @@ use the information in the failure error logs or the database:
sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,push_event_payloads,event_id,'[["event_id"]\, ["event_id_convert_to_bigint"]]']
```
-:::TabTitle From the database
+{{< /tab >}}
+
+{{< tab title="From the database" >}}
1. [Check the status](#check-the-status-of-batched-background-migrations) of the
migration in the database.
@@ -322,24 +351,32 @@ use the information in the failure error logs or the database:
sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,ci_builds,id,'[["id"\, "stage_id"]\,["id_convert_to_bigint"\,"stage_id_convert_to_bigint"]]']
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
##### Mark a failed migration finished
-WARNING:
+{{< alert type="warning" >}}
+
[Contact GitLab Support](https://about.gitlab.com/support/#contact-support) before using
these instructions. This action can cause data loss, and make your instance fail
in ways that are difficult to recover from.
+{{< /alert >}}
+
There can be cases where the background migration fails: when jumping too many version upgrades,
or backward-incompatible database schema changes. (For an example, see [issue 393216](https://gitlab.com/gitlab-org/gitlab/-/issues/393216)).
Failed background migrations prevent further application upgrades.
When the background migration is determined to be "safe" to skip, the migration can be manually marked finished:
-WARNING:
+{{< alert type="warning" >}}
+
Make sure you create a backup before proceeding.
+{{< /alert >}}
+
```ruby
# Start the rails console
@@ -374,16 +411,18 @@ used in GitLab 15.0.
To check for pending non-batched background migrations:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count'
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
cd /home/git/gitlab
@@ -391,15 +430,17 @@ sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMi
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count'
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Check for failed background migrations
To check for non-batched background migrations that have failed:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
For GitLab versions 14.10 and later:
@@ -413,7 +454,9 @@ For GitLab versions 14.0-14.9:
sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.failed.count'
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
For GitLab versions 14.10 and later:
@@ -429,13 +472,18 @@ cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.failed.count'
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Check for pending advanced search migrations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This section is only applicable if you have enabled the [Elasticsearch integration](../integration/advanced_search/elasticsearch.md).
Major releases require all [advanced search migrations](../integration/advanced_search/elasticsearch.md#advanced-search-migrations)
@@ -443,19 +491,23 @@ to be finished from the most recent minor release in your current version
before the major version upgrade. You can find pending migrations by
running the following command.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
sudo gitlab-rake gitlab:elastic:list_pending_migrations
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/update/background_migrations_troubleshooting.md b/doc/update/background_migrations_troubleshooting.md
index bc213ced12920c83d1aff3a9d8f7c3939d4ca3d3..7d3a712ece75d879619377dea8d123575baa60ba 100644
--- a/doc/update/background_migrations_troubleshooting.md
+++ b/doc/update/background_migrations_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
<!-- Linked from lib/gitlab/database/migrations/batched_background_migration_helpers.rb -->
@@ -87,9 +90,12 @@ version and wait for the batched background migrations to finish.
## Background migrations remain in the Sidekiq queue
-WARNING:
+{{< alert type="warning" >}}
+
The following operations can disrupt your GitLab performance. They run Sidekiq jobs that perform various database or file updates.
+{{< /alert >}}
+
Run the following check. If the check returns non-zero and the count does not decrease over time, follow the rest of the steps in this section.
```shell
@@ -103,9 +109,9 @@ sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMi
It is safe to re-execute the following commands, especially if you have 1000+ pending jobs which would likely overflow your runtime memory.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
# Start the rails console
@@ -117,7 +123,9 @@ pending_job_classes = scheduled_queue.select { |job| job["class"] == "Background
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
# Start the rails console
@@ -129,7 +137,9 @@ pending_job_classes = scheduled_queue.select { |job| job["class"] == "Background
pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) }
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Background migrations stuck in 'pending' state
@@ -148,9 +158,9 @@ sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::Ba
It is safe to re-attempt these migrations to clear them out from a pending status:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
# Start the rails console
@@ -164,7 +174,9 @@ Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
end
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```shell
# Start the rails console
@@ -178,7 +190,9 @@ Gitlab::Database::BackgroundMigrationJob.pending.find_each do |job|
end
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Advanced search migrations are stuck
diff --git a/doc/update/package/_index.md b/doc/update/package/_index.md
index ce6c5061fb3dde6e7b8b0200c445f76a7b703762..e0fceacf65e71135ea61b16a386c51cc733f990c 100644
--- a/doc/update/package/_index.md
+++ b/doc/update/package/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Upgrading Linux package instances
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Upgrading Linux package instances to a later version of GitLab requires several steps, many specific to Linux package
installations.
@@ -95,10 +98,13 @@ sudo dnf install gitlab-ee
sudo zypper install gitlab-ee
```
-NOTE:
+{{< alert type="note" >}}
+
For the GitLab Community Edition, replace `gitlab-ee` with
`gitlab-ce`.
+{{< /alert >}}
+
#### Upgrade to a specific version
Linux package managers default to installing the latest available version of a
@@ -151,10 +157,13 @@ or upgrade command:
sudo zypper install gitlab-ee=<version>-ee.0.sles12
```
-NOTE:
+{{< alert type="note" >}}
+
For the GitLab Community Edition, replace `ee` with
`ce`.
+{{< /alert >}}
+
### By using a downloaded package
If you don't want to use the official repositories, you can
@@ -188,9 +197,12 @@ To download and install or upgrade GitLab:
zypper install <package_name>
```
-NOTE:
+{{< alert type="note" >}}
+
For the GitLab Community Edition, replace `gitlab-ee` with `gitlab-ce`.
+{{< /alert >}}
+
## Upgrade the product documentation (optional)
If you [installed the product documentation](../../administration/docs_self_host.md),
diff --git a/doc/update/package/convert_to_ee.md b/doc/update/package/convert_to_ee.md
index 1f2d1c797891740e5f2e715a92a75d02ab0b2854..d4c987a8d610be69a3b336ed2dd3246fb6ceaf27 100644
--- a/doc/update/package/convert_to_ee.md
+++ b/doc/update/package/convert_to_ee.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Convert a Linux package CE instance to EE
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can convert an existing Linux package instance from Community Edition (CE) to Enterprise Edition (EE).
To convert the instance, you install the EE Linux package on top of the CE instance.
@@ -15,11 +18,14 @@ To convert the instance, you install the EE Linux package on top of the CE insta
You don't need the same version of CE to EE. For example, CE 17.0 to EE 17.1 should work. However, upgrading the same
version (for example, CE 17.1 to EE 17.1) is **recommended**.
-WARNING:
+{{< alert type="warning" >}}
+
After you convert from EE from CE, don't revert back to CE if you plan to go to EE again. Reverting back to CE can cause
[database issues](package_troubleshooting.md#500-error-when-accessing-project-repository-settings) that may require
Support intervention.
+{{< /alert >}}
+
## Convert from CE to EE
To convert a Linux package CE instance to EE:
@@ -27,9 +33,9 @@ To convert a Linux package CE instance to EE:
1. Make a [GitLab backup](../../administration/backup_restore/backup_gitlab.md).
1. Find the installed GitLab version:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Debian/Ubuntu
+ {{< tab title="Debian/Ubuntu" >}}
```shell
sudo apt-cache policy gitlab-ce | grep Installed
@@ -37,7 +43,9 @@ To convert a Linux package CE instance to EE:
Note down the returned version.
- :::TabTitle CentOS/RHEL
+ {{< /tab >}}
+
+ {{< tab title="CentOS/RHEL" >}}
```shell
sudo rpm -q gitlab-ce
@@ -45,36 +53,42 @@ To convert a Linux package CE instance to EE:
Note down the returned version.
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Add the `gitlab-ee` [Apt or Yum repository](https://packages.gitlab.com/gitlab/gitlab-ee/install). These commands
find your OS version and automatically set up the repository. If you are not comfortable installing the repository
through a piped script, you can first [check the script's contents](https://packages.gitlab.com/gitlab/gitlab-ee/install).
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Debian/Ubuntu
+ {{< tab title="Debian/Ubuntu" >}}
```shell
curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh" | sudo bash
```
- :::TabTitle CentOS/RHEL
+ {{< /tab >}}
+
+ {{< tab title="CentOS/RHEL" >}}
```shell
curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh" | sudo bash
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
To use `dpkg` or `rpm` instead of using `apt-get` or `yum` follow
[Upgrade using a manually downloaded package](_index.md#by-using-a-downloaded-package).
1. Install the `gitlab-ee` Linux package. The install automatically uninstalls the `gitlab-ce` package on your GitLab.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Debian/Ubuntu
+ {{< tab title="Debian/Ubuntu" >}}
```shell
## Make sure the repositories are up-to-date
@@ -87,7 +101,9 @@ To convert a Linux package CE instance to EE:
sudo gitlab-ctl reconfigure
```
- :::TabTitle CentOS/RHEL
+ {{< /tab >}}
+
+ {{< tab title="CentOS/RHEL" >}}
```shell
## Install the package using the version you wrote down from step 1
@@ -97,26 +113,32 @@ To convert a Linux package CE instance to EE:
sudo gitlab-ctl reconfigure
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. [Add your license](../../administration/license.md) to activate Enterprise Edition.
1. Confirm that GitLab is working as expected, then you can remove the old Community Edition repository:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Debian/Ubuntu
+ {{< tab title="Debian/Ubuntu" >}}
```shell
sudo rm /etc/apt/sources.list.d/gitlab_gitlab-ce.list
```
- :::TabTitle CentOS/RHEL
+ {{< /tab >}}
+
+ {{< tab title="CentOS/RHEL" >}}
```shell
sudo rm /etc/yum.repos.d/gitlab_gitlab-ce.repo
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Optional. [Set up the Elasticsearch integration](../../integration/advanced_search/elasticsearch.md) to enable
[advanced search](../../user/search/advanced_search.md).
diff --git a/doc/update/package/downgrade.md b/doc/update/package/downgrade.md
index 9c84911f69ba22cb4a0a83fa9531d58fbb1afddf..1c21c15cd34bea0345133d0b7fd16479c13bf03b 100644
--- a/doc/update/package/downgrade.md
+++ b/doc/update/package/downgrade.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Roll back to earlier GitLab versions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can roll back to earlier versions of GitLab instances that were installed by using the Linux package.
diff --git a/doc/update/package/package_troubleshooting.md b/doc/update/package/package_troubleshooting.md
index d55f6a72fdfc36b743e937ec8ddf471802e42e6b..61d8c50ac6856449315b69df2fe2c7594fcfaeb9 100644
--- a/doc/update/package/package_troubleshooting.md
+++ b/doc/update/package/package_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To help with troubleshooting, run the following commands.
diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md
index b80873a20df04299fbbce04631bf4f63c0ddacb7..0594706835a58541603aa03eb9544bc50756945e 100644
--- a/doc/update/patch_versions.md
+++ b/doc/update/patch_versions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Update self-compiled installations with patch versions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Update self-compiled installations with patch versions.
@@ -124,9 +127,12 @@ sudo -u git -H make
## Install or update `gitlab-elasticsearch-indexer`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To install or update `gitlab-elasticsearch-indexer`, follow the
[installation instruction](../integration/advanced_search/elasticsearch.md#install-an-elasticsearch-or-aws-opensearch-cluster).
diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md
index 6257b65df4f0a5aef3d747cbd8c191a18a976dcc..a93b2daf0dce6a6c3feeb227e0f16723c166b752 100644
--- a/doc/update/plan_your_upgrade.md
+++ b/doc/update/plan_your_upgrade.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Create an upgrade plan
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Creating an upgrade plan involves documenting:
diff --git a/doc/update/upgrade_paths.md b/doc/update/upgrade_paths.md
index f825dba739984d5d7b7417d8c42d863499105723..e3b4f0e92dad072bcea1064508a9d408f066ed99 100644
--- a/doc/update/upgrade_paths.md
+++ b/doc/update/upgrade_paths.md
@@ -1,14 +1,17 @@
---
stage: Systems
group: Distribution
-description: Latest version instructions.
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
+description: Latest version instructions.
title: Upgrade paths
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Upgrading across multiple GitLab versions in one go is *only possible by accepting downtime*.
If you don't want any downtime, read how to [upgrade with zero downtime](zero_downtime.md).
diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md
index 23e9acfd04c6616fe75a10a9f529353c4c61ca77..a170e85f3aee7659ecf73cf78ce90524e9ab4395 100644
--- a/doc/update/upgrading_from_ce_to_ee.md
+++ b/doc/update/upgrading_from_ce_to_ee.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Convert a self-compiled CE instance to EE
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can convert an existing self-compiled instance from Community Edition (CE) to Enterprise Edition (EE).
@@ -78,9 +81,12 @@ sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
### Install `gitlab-elasticsearch-indexer`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
To install `gitlab-elasticsearch-indexer`, follow the
[install instruction](../integration/advanced_search/elasticsearch.md#install-an-elasticsearch-or-aws-opensearch-cluster).
diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md
index ad0c7bb88eb83d88117e63dc2d75d08c7738abf3..d1ea91738d2a65d3ebfe3567c10df2009f7bf5fe 100644
--- a/doc/update/upgrading_from_source.md
+++ b/doc/update/upgrading_from_source.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Upgrading self-compiled instances
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Upgrading self-compiled instances to a later version of GitLab requires several steps, many specific to self-compiled
installations.
@@ -162,9 +165,12 @@ than what you are running. You may also have to enable some
extensions. For more information, see the
[PostgreSQL requirements](../install/requirements.md#postgresql)
-WARNING:
+{{< alert type="warning" >}}
+
GitLab 17.0 requires PostgreSQL 14. GitLab 17.5 is compatible with up to PostgreSQL 16.
+{{< /alert >}}
+
To upgrade PostgreSQL, refer to its [documentation](https://www.postgresql.org/docs/11/upgrading.html).
### Update the GitLab codebase
@@ -225,7 +231,11 @@ There might be new configuration options available for
#### New configuration for `database.yml`
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119139) in GitLab 16.0 to have `ci:` section in `config/database.yml.postgresql`.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119139) in GitLab 16.0 to have `ci:` section in `config/database.yml.postgresql`.
+
+{{< /history >}}
There might be new configuration options available for
[`database.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/database.yml.postgresql).
diff --git a/doc/update/versions/gitlab_15_changes.md b/doc/update/versions/gitlab_15_changes.md
index b433aa3405bb33536cf8bd312e2ee4a2e4f908e0..1b6ce3f4a371908cb28955fc5a2c41189014e6dd 100644
--- a/doc/update/versions/gitlab_15_changes.md
+++ b/doc/update/versions/gitlab_15_changes.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab 15 changes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page contains upgrade information for minor and patch versions of GitLab 15.
Ensure you review these instructions for:
@@ -58,9 +61,12 @@ see [Packaged PostgreSQL deployed in an HA/Geo Cluster](https://docs.gitlab.com/
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- Some project imports do not initialize wiki repositories on project creation. See
[the details and workaround](gitlab_16_changes.md#wiki-repositories-not-initialized-on-project-creation).
@@ -171,9 +177,12 @@ if you can't upgrade to 15.11.12 and later.
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- `pg_upgrade` fails to upgrade the bundled PostregSQL database to version 13. See
[the details and workaround](#pg_upgrade-fails-to-upgrade-the-bundled-postregsql-database-to-version-13).
@@ -221,9 +230,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- `pg_upgrade` fails to upgrade the bundled PostregSQL database to version 13. See
[the details and workaround](#pg_upgrade-fails-to-upgrade-the-bundled-postregsql-database-to-version-13).
@@ -233,9 +245,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
- Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2.
@@ -247,9 +262,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
- Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2.
@@ -262,9 +280,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- `pg_upgrade` fails to upgrade the bundled PostregSQL database to version 13. See
[the details and workaround](#pg_upgrade-fails-to-upgrade-the-bundled-postregsql-database-to-version-13).
@@ -279,9 +300,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
- Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2.
@@ -293,9 +317,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
- Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2.
@@ -307,9 +334,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
- Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2.
@@ -321,9 +351,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
- Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2.
@@ -335,9 +368,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the upgrades. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover.
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
@@ -350,9 +386,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover.
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
@@ -412,9 +451,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- `pg_upgrade` fails to upgrade the bundled PostregSQL database to version 13. See
[the details and workaround](#pg_upgrade-fails-to-upgrade-the-bundled-postregsql-database-to-version-13).
@@ -429,9 +471,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
- Affected versions: GitLab versions 15.6.x, 15.7.x, and 15.8.0 - 15.8.2.
@@ -443,9 +488,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover.
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
@@ -456,9 +504,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover.
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
@@ -470,9 +521,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6, and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover.
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
@@ -484,9 +538,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover.
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
@@ -498,9 +555,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover.
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
@@ -512,9 +572,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- [Container registry push events are rejected](https://gitlab.com/gitlab-org/gitlab/-/issues/386389) by the `/api/v4/container_registry_event/events` endpoint resulting in Geo secondary sites not being aware of updates to container registry images and subsequently not replicating the updates. Secondary sites may contain out of date container images after a failover as a consequence. This affects versions 15.6.0 - 15.6.6 and 15.7.0 - 15.7.2. If you're using Geo with container repositories, you are advised to upgrade to GitLab 15.6.7, 15.7.3, or 15.8.0 which contain a fix for this issue and avoid potential data loss after a failover.
- We discovered an issue where [replication and verification of projects and wikis was not keeping up](https://gitlab.com/gitlab-org/gitlab/-/issues/387980) on small number of Geo installations. Your installation may be affected if you see some projects and/or wikis persistently in the "Queued" state for verification. This can lead to data loss after a failover.
@@ -551,9 +614,12 @@ potentially cause downtime.
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- `pg_upgrade` fails to upgrade the bundled PostregSQL database to version 13. See
[the details and workaround](#pg_upgrade-fails-to-upgrade-the-bundled-postregsql-database-to-version-13).
@@ -622,9 +688,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- `pg_upgrade` fails to upgrade the bundled PostregSQL database to version 13. See
[the details and workaround](#pg_upgrade-fails-to-upgrade-the-bundled-postregsql-database-to-version-13).
@@ -701,9 +770,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- `pg_upgrade` fails to upgrade the bundled PostregSQL database to version 13. See
[the details and workaround](#pg_upgrade-fails-to-upgrade-the-bundled-postregsql-database-to-version-13).
@@ -776,9 +848,12 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706)
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- `pg_upgrade` fails to upgrade the bundled PostregSQL database to version 13. See
[the details and workaround](#pg_upgrade-fails-to-upgrade-the-bundled-postregsql-database-to-version-13).
@@ -853,9 +928,12 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706)
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- `pg_upgrade` fails to upgrade the bundled PostregSQL database to version 13. See
[the details and workaround](#pg_upgrade-fails-to-upgrade-the-bundled-postregsql-database-to-version-13).
@@ -897,9 +975,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- [Geo proxying](../../administration/geo/secondary_proxy/_index.md) was [enabled by default for different URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in 15.1. This may be a breaking change. If needed, you may [disable Geo proxying](../../administration/geo/secondary_proxy/_index.md#disable-secondary-site-http-proxying). If you are using SAML with different URLs, you must modify your SAML configuration and your Identity Provider configuration. For more information, see the [Geo with Single Sign-On (SSO) documentation](../../administration/geo/replication/single_sign_on.md).
- LFS transfers can redirect to the primary from secondary site mid-session. See
@@ -993,13 +1074,16 @@ DETAILS:
sudo gitlab-ctl reconfigure
```
- NOTE:
- It is mandatory to restart PostgreSQL when underlying version changes, to avoid
+ {{< alert type="note" >}}
+
+It is mandatory to restart PostgreSQL when underlying version changes, to avoid
errors like the [one related to loading necessary libraries](https://docs.gitlab.com/omnibus/settings/database.html#could-not-load-library-plpgsqlso)
that can cause downtime. So, if you skip the automatic restarts using the above
method, ensure that you restart the services manually before upgrading to GitLab
15.0.
+ {{< /alert >}}
+
- Starting with GitLab 15.0, the `AES256-GCM-SHA384` SSL cipher will not be allowed by
NGINX by default. If you use the
[AWS Classic Load Balancer](https://docs.aws.amazon.com/en_en/elasticloadbalancing/latest/classic/elb-ssl-security-policy.html#ssl-ciphers) and require the cipher,
@@ -1079,9 +1163,12 @@ DETAILS:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- Incorrect object storage LFS files deletion on Geo secondary sites. See
[the details and workaround](#incorrect-object-storage-lfs-file-deletion-on-secondary-sites).
diff --git a/doc/update/versions/gitlab_16_changes.md b/doc/update/versions/gitlab_16_changes.md
index badb2a5940187d332672a4429f7decb7e39b68d0..e32b39bf1f05e2a95b3d6a384a52785dcdbfb982 100644
--- a/doc/update/versions/gitlab_16_changes.md
+++ b/doc/update/versions/gitlab_16_changes.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab 16 changes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page contains upgrade information for minor and patch versions of GitLab 16.
Ensure you review these instructions for:
@@ -1153,9 +1156,12 @@ Workaround: A possible workaround is to [disable proxying](../../administration/
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Specific information applies to installations using Geo:
@@ -1267,9 +1273,12 @@ For more information, see the:
### Geo installations
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Specific information applies to installations using Geo:
@@ -1300,13 +1309,16 @@ Migrate by moving your existing configuration under the new structure. `git_data
**Migrate to the new structure**
-WARNING:
+{{< alert type="warning" >}}
+
If you are running Gitaly cluster, [migrate Praefect to the new configuration structure **first**](#praefect-configuration-structure-change).
Once this change is tested, proceed with your Gitaly nodes.
If Gitaly is misconfigured as part of the configuration structure change, [repository verification](../../administration/gitaly/praefect.md#repository-verification)
will [delete metadata required for Gitaly cluster to work](https://gitlab.com/gitlab-org/gitaly/-/issues/5529).
To protect against configuration mistakes, temporarily disable repository verification in Praefect.
+{{< /alert >}}
+
1. If you're running Gitaly Cluster, ensure repository verification is disabled on all Praefect nodes.
Configure `verification_interval: 0`, and apply with `gitlab-ctl reconfigure`.
1. To apply the new structure to your configuration:
@@ -1324,9 +1336,12 @@ To protect against configuration mistakes, temporarily disable repository verifi
The new structure is documented below with the old keys described in a comment above the new keys.
-WARNING:
+{{< alert type="warning" >}}
+
Double check your update to `storage`. You must append `/repositories` to the value of `path`.
+{{< /alert >}}
+
```ruby
gitaly['configuration'] = {
# gitaly['socket_path']
@@ -1486,13 +1501,16 @@ Migrate by moving your existing configuration under the new structure. The new s
**Migrate to the new structure**
-WARNING:
+{{< alert type="warning" >}}
+
Migrate Praefect to the new configuration structure **first**.
Once this change is tested, [proceed with your Gitaly nodes](#gitaly-configuration-structure-change).
If Gitaly is misconfigured as part of the configuration structure change, [repository verification](../../administration/gitaly/praefect.md#repository-verification)
will [delete metadata required for Gitaly cluster to work](https://gitlab.com/gitlab-org/gitaly/-/issues/5529).
To protect against configuration mistakes, temporarily disable repository verification in Praefect.
+{{< /alert >}}
+
1. When applying the new structure to your configuration:
- Replace the `...` with the value from the old key.
- Disable repository verification using `verification_interval: 0`, as shown below.
@@ -1649,9 +1667,9 @@ If you have PgBouncer deployed:
Follow the instructions for your installation type to switch back to a single database connection:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package and Docker
+{{< tab title="Linux package and Docker" >}}
1. Add this setting to `/etc/gitlab/gitlab.rb`:
@@ -1663,7 +1681,9 @@ Follow the instructions for your installation type to switch back to a single da
In a multi-node environment, this setting should be updated on all Rails and Sidekiq nodes.
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Set the `ci.enabled` key to `false`:
@@ -1674,11 +1694,15 @@ global:
enabled: false
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
Remove the `ci:` section from `config/database.yml`.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Long-running user type data change
@@ -1775,9 +1799,9 @@ on the source instance.
The commands in the following sections are for Linux package installations, and
differ for other installation types:
-::Tabs
+{{< tabs >}}
-:::TabTitle Docker
+{{< tab title="Docker" >}}
- Omit `sudo`
- Shell into the GitLab container and run the same commands:
@@ -1786,19 +1810,25 @@ differ for other installation types:
docker exec -it <container-id> bash
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
- Use `sudo -u git -H bundle exec rake RAILS_ENV=production` instead of `sudo gitlab-rake`
- Run the SQL on [your PostgreSQL database console](../../administration/troubleshooting/postgresql.md#start-a-database-console)
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
- Omit `sudo`.
- Shell into the `toolbox` pod to run the Rake commands: `gitlab-rake` is in `/usr/local/bin` if not in the `PATH`.
- Refer to our [Kubernetes cheat sheet](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html#gitlab-specific-kubernetes-information) for details.
- Run the SQL on [your PostgreSQL database console](../../administration/troubleshooting/postgresql.md#start-a-database-console)
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Workaround: instance created with 15.9 or earlier
diff --git a/doc/update/versions/gitlab_17_changes.md b/doc/update/versions/gitlab_17_changes.md
index 87d372ed53412bf998c415329b3bb5271abb637a..135b8116c3d32371ebb0fe303c828159b93a7272 100644
--- a/doc/update/versions/gitlab_17_changes.md
+++ b/doc/update/versions/gitlab_17_changes.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab 17 changes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This page contains upgrade information for minor and patch versions of GitLab 17.
Ensure you review these instructions for:
@@ -242,10 +245,13 @@ ensure that your proxy server does not alter or remove signed HTTP headers.
### OpenSSL 3 upgrade
-NOTE:
+{{< alert type="note" >}}
+
Before upgrading to GitLab 17.7, use the [OpenSSL 3 guide](https://docs.gitlab.com/omnibus/settings/ssl/openssl_3.html)
to identify and assess the compatibility of your external integrations.
+{{< /alert >}}
+
- The Linux package upgrades OpenSSL from v1.1.1w to v3.0.0.
- Cloud Native GitLab (CNG) already upgraded to OpenSSL 3 in GitLab 16.7.0. If you are using Cloud Native GitLab, no
action is needed. However, note that [Cloud Native Hybrid](../../administration/reference_architectures/_index.md#recommended-cloud-providers-and-services) installations
@@ -285,9 +291,12 @@ for more details.
## 17.5.0
-NOTE:
+{{< alert type="note" >}}
+
The OpenSSL 3 upgrade has been postponed to GitLab 17.7.0.
+{{< /alert >}}
+
- S3 object storage access for the GitLab Runner distributed cache is now handled by the
[AWS SDK v2 for Go](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/4987) instead of the MinIO client.
You can enable the MinIO client again by setting the `FF_USE_LEGACY_S3_CACHE_ADAPTER`
diff --git a/doc/update/with_downtime.md b/doc/update/with_downtime.md
index d0524aac511efe0c2521b86984c2bcc0a225244e..cd24f32751a453cd95005520c2d4bcd2c291d5c1 100644
--- a/doc/update/with_downtime.md
+++ b/doc/update/with_downtime.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Multi-node upgrades with downtime
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
While you can upgrade a multi-node GitLab deployment [with zero downtime](zero_downtime.md),
there are a number of constraints. In particular, you can upgrade to only one minor release
@@ -43,9 +46,9 @@ At a high level, the process is:
Before upgrade, you need to stop writes to the database. The process is different
depending on your [reference architecture](../administration/reference_architectures/_index.md).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package
+{{< tab title="Linux package" >}}
Shut down Puma and Sidekiq on all servers running these processes:
@@ -54,7 +57,9 @@ sudo gitlab-ctl stop sidekiq
sudo gitlab-ctl stop puma
```
-:::TabTitle Cloud Native Hybrid
+{{< /tab >}}
+
+{{< tab title="Cloud Native Hybrid" >}}
For [Cloud Native Hybrid](../administration/reference_architectures/_index.md#cloud-native-hybrid) environments:
@@ -70,7 +75,9 @@ kubectl get deploy -n <namespace> -l release=<helm release name> -l 'app in (pro
kubectl scale deploy -n <namespace> -l release=<helm release name> -l 'app in (prometheus,webservice,sidekiq)' --replicas=0
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Upgrade the Consul nodes
@@ -196,18 +203,21 @@ Upgrade a standalone Redis server by [upgrading the GitLab package](package/_ind
## Upgrade Redis HA (using Sentinel)
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Follow [the zero-downtime instructions](zero_downtime.md)
for upgrading your Redis HA cluster.
## Upgrade the Rails components
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package
+{{< tab title="Linux package" >}}
All the Puma and Sidekiq processes were previously shut down. On each node:
@@ -286,7 +296,9 @@ They can be upgraded in parallel:
sudo gitlab-ctl restart
```
-:::TabTitle Cloud Native Hybrid
+{{< /tab >}}
+
+{{< tab title="Cloud Native Hybrid" >}}
Now that all stateful components are upgraded, you need to follow
[GitLab chart upgrade steps](https://docs.gitlab.com/charts/installation/upgrade.html)
@@ -300,7 +312,9 @@ kubectl scale deploy -lapp=webservice,release=<helm release name> -n <namespace>
kubectl scale deploy -lapp=prometheus,release=<helm release name> -n <namespace> --replicas=<value>
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Upgrade the Monitor node
diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md
index 63089611b69cb88de9aa201d7c464fdc3a4cdfd6..3eedefb46a2965c10352030026bf1934d764fa25 100644
--- a/doc/update/zero_downtime.md
+++ b/doc/update/zero_downtime.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Zero-downtime upgrades
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
With zero-downtime upgrades, it's possible to upgrade a live GitLab environment without having to
take it offline. This guide will take you through the core process of performing
@@ -60,9 +63,12 @@ In addition to the above, please be aware of the following considerations:
- Zero-downtime upgrades are supported for any GitLab components you've deployed with the GitLab Linux package. If you've deployed select components through a supported third party service, such as PostgreSQL in AWS RDS or Redis in GCP Memorystore, upgrades for those services will need to be performed separately as per their standard processes.
- As a general guideline, the larger amount of data you have, the more time it will take for the upgrade to complete. In testing, any database smaller than 10 GB shouldn't generally take longer than an hour, but your mileage may vary.
-NOTE:
+{{< alert type="note" >}}
+
If you want to upgrade multiple releases or do not meet these requirements [upgrades with downtime](with_downtime.md) should be explored instead.
+{{< /alert >}}
+
## Upgrade order
We recommend a "back to front" approach for the order of what components to upgrade with zero downtime.
@@ -114,11 +120,14 @@ Run through the following steps sequentially on each component's node to perform
that the Gitaly process itself is not restarted as it has a built-in process to gracefully reload
at the earliest opportunity. Note that any other component will still need to be restarted.
-NOTE:
+{{< alert type="note" >}}
+
The upgrade process attempts to do a graceful handover to a new Gitaly process.
Existing long-running Git requests that were started before the upgrade may eventually be dropped as this handover occurs.
In the future this functionality may be changed, [refer to this Epic](https://gitlab.com/groups/gitlab-org/-/epics/10328) for more information.
+{{< /alert >}}
+
This process applies to both Gitaly Sharded and Cluster setups. Run through the following steps sequentially on each Gitaly node to perform the upgrade:
1. Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab:
@@ -148,11 +157,14 @@ This process applies to both Gitaly Sharded and Cluster setups. Run through the
For Gitaly Cluster setups, you must deploy and upgrade Praefect in a similar way by using a graceful reload.
-NOTE:
+{{< alert type="note" >}}
+
The upgrade process attempts to do a graceful handover to a new Praefect process.
Existing long-running Git requests that were started before the upgrade may eventually be dropped as this handover occurs.
In the future this functionality may be changed, [refer to this Epic](https://gitlab.com/groups/gitlab-org/-/epics/10328) for more information.
+{{< /alert >}}
+
One additional step though for Praefect is that it will also need to run through its database migrations to upgrade its data.
Migrations need to be run on only one Praefect node to avoid clashes. This is best done by selecting one of the
nodes to be a deploy node. This target node will be configured to run migrations while the rest are not. We'll refer to this as the **Praefect deploy node** below:
@@ -344,9 +356,12 @@ Run through the following steps sequentially on each component node to perform t
## Multi-node / HA deployment with Geo
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
This section describes the steps required to upgrade live GitLab environment
deployment with Geo.
@@ -357,9 +372,12 @@ for each secondary site. The required order is upgrading the primary first, then
the secondaries. You must also run any post-deployment migrations on the primary _after_
all secondaries have been updated.
-NOTE:
+{{< alert type="note" >}}
+
The same [requirements and consideration](#requirements-and-considerations) apply for upgrading a live GitLab environment with Geo.
+{{< /alert >}}
+
### Primary site
The upgrade process for the Primary site is the same as the [normal process](#multi-node--ha-deployment) with one exception being
diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md
index 98ed5ce1b29680636433beebbb2e9d352498130d..20739a73937ee436449e6bfbd29dcbfaec80a022 100644
--- a/doc/user/admin_area/license_file.md
+++ b/doc/user/admin_area/license_file.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../../administration/license_file.md'
-remove_date: '2025-04-14'
+redirect_to: ../../administration/license_file.md
+remove_date: "2025-04-14"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/ai_experiments.md b/doc/user/ai_experiments.md
index 3fa96d6f9959d969cc73cd86a9d21765114e727f..d803d6fbf3f1b7f1e127f9ebce8c7e471323b2e7 100644
--- a/doc/user/ai_experiments.md
+++ b/doc/user/ai_experiments.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../user/gitlab_duo/experiments.md'
-remove_date: '2025-06-11'
+redirect_to: ../user/gitlab_duo/experiments.md
+remove_date: "2025-06-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/ai_features.md b/doc/user/ai_features.md
index aa287f00a7fabcb4e4c45c44f77c234a6971dacf..9df5cc739417302a576f0c12995a0466536a24ab 100644
--- a/doc/user/ai_features.md
+++ b/doc/user/ai_features.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../user/gitlab_duo/_index.md'
-remove_date: '2025-06-11'
+redirect_to: ../user/gitlab_duo/_index.md
+remove_date: "2025-06-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/ai_features_enable.md b/doc/user/ai_features_enable.md
index 2f4b5d2610f4de51782ec4c837aff1dd68971e22..77c5292abb5deff1b628f817ea5c64ad76dd847b 100644
--- a/doc/user/ai_features_enable.md
+++ b/doc/user/ai_features_enable.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../user/gitlab_duo/turn_on_off.md'
-remove_date: '2025-06-11'
+redirect_to: ../user/gitlab_duo/turn_on_off.md
+remove_date: "2025-06-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/analytics/_index.md b/doc/user/analytics/_index.md
index f0b8740973f181d133a26d3162afe54d5dbea260..f1b9ffcfa95e245186a70f7a74fac99cc5615701 100644
--- a/doc/user/analytics/_index.md
+++ b/doc/user/analytics/_index.md
@@ -1,12 +1,16 @@
---
stage: Plan
group: Optimize
-description: Instance, group, and project analytics.
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
+description: Instance, group, and project analytics.
title: Analyze GitLab usage
---
-> - Group-level analytics moved to GitLab Premium in 13.9.
+{{< history >}}
+
+- Group-level analytics moved to GitLab Premium in 13.9.
+
+{{< /history >}}
GitLab provides different types of analytics insights for instances, groups, and [projects](../project/settings/_index.md#turn-off-project-analytics).
@@ -18,13 +22,13 @@ Use these features to gain insights into your overall software development lifec
| Feature | Description | Project-level | Group-level | Instance-level |
| ------- | ----------- | ------------- | ----------- | -------------- |
-| [Value Streams Dashboard](value_streams_dashboard.md) | Insights into DevSecOps trends, patterns, and opportunities for digital transformation improvements. | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [Value Stream Management Analytics](../group/value_stream_analytics/_index.md) | Insights into time-to-value through customizable stages. | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| DevOps adoption [by group](../group/devops_adoption/_index.md) and [by instance](../../administration/analytics/dev_ops_reports.md) | Organization's maturity in DevOps adoption, with feature adoption over time and feature distribution by group. | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes |
-| [Usage trends](../../administration/analytics/usage_trends.md) | Overview of instance data and changes in data volume over time. | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Insights](../project/insights/_index.md) | Customizable reports to explore issues, merged merge requests, and triage hygiene. | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [Product analytics](../../development/internal_analytics/product_analytics.md) | Understanding how users behave and interact with your product.| **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [Analytics dashboards](analytics_dashboards.md) | Built-in and customizable dashboards to visualize collected data. | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
+| [Value Streams Dashboard](value_streams_dashboard.md) | Insights into DevSecOps trends, patterns, and opportunities for digital transformation improvements. | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [Value Stream Management Analytics](../group/value_stream_analytics/_index.md) | Insights into time-to-value through customizable stages. | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| DevOps adoption [by group](../group/devops_adoption/_index.md) and [by instance](../../administration/analytics/dev_ops_reports.md) | Organization's maturity in DevOps adoption, with feature adoption over time and feature distribution by group. | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [Usage trends](../../administration/analytics/usage_trends.md) | Overview of instance data and changes in data volume over time. | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Insights](../project/insights/_index.md) | Customizable reports to explore issues, merged merge requests, and triage hygiene. | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [Product analytics](../../development/internal_analytics/product_analytics.md) | Understanding how users behave and interact with your product.| {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [Analytics dashboards](analytics_dashboards.md) | Built-in and customizable dashboards to visualize collected data. | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
### Productivity analytics
@@ -32,10 +36,10 @@ Use these features to gain insights into the productivity of your team on issues
| Feature | Description | Project-level | Group-level | Instance-level |
| ------- | ----------- | ------------- | ----------- | -------------- |
-| [Issue analytics](../group/issues_analytics/_index.md) | Visualization of issues created each month. | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [Merge request analytics](merge_request_analytics.md) | Overview of merge requests, with mean time to merge, throughput, and activity details. | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [Productivity analytics](productivity_analytics.md) | Merge request lifecycle, filterable down to author level. | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [Code review analytics](code_review_analytics.md) | Open merge requests with information about merge request activity. | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
+| [Issue analytics](../group/issues_analytics/_index.md) | Visualization of issues created each month. | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [Merge request analytics](merge_request_analytics.md) | Overview of merge requests, with mean time to merge, throughput, and activity details. | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [Productivity analytics](productivity_analytics.md) | Merge request lifecycle, filterable down to author level. | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [Code review analytics](code_review_analytics.md) | Open merge requests with information about merge request activity. | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
### Developer analytics
@@ -43,9 +47,9 @@ Use these features to gain insights into developer productivity and code coverag
| Feature | Description | Project-level | Group-level | Instance-level |
| ------- | ----------- | ------------- | ----------- | -------------- |
-| [Contribution analytics](../group/contribution_analytics/_index.md) | Overview of [contribution events](../profile/contributions_calendar.md) made by group members, with bar chart of push events, merge requests, and issues. | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [Contributor analytics](../analytics/contributor_analytics.md) | Overview of commits made by project members, with line chart of number of commits. | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [Repository analytics](../group/repositories_analytics/_index.md) | Programming languages used in the repository and code coverage statistics. | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
+| [Contribution analytics](../group/contribution_analytics/_index.md) | Overview of [contribution events](../profile/contributions_calendar.md) made by group members, with bar chart of push events, merge requests, and issues. | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [Contributor analytics](../analytics/contributor_analytics.md) | Overview of commits made by project members, with line chart of number of commits. | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [Repository analytics](../group/repositories_analytics/_index.md) | Programming languages used in the repository and code coverage statistics. | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
### CI/CD analytics
@@ -53,8 +57,8 @@ Use these features to gain insights into CI/CD performance.
| Feature | Description | Project-level | Group-level | Instance-level |
| ------- | ----------- | ------------- | ----------- | -------------- |
-| [CI/CD analytics](ci_cd_analytics.md) | Pipeline duration and successes or failures. | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [DORA metrics](dora_metrics.md) | DORA metrics over time. | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
+| [CI/CD analytics](ci_cd_analytics.md) | Pipeline duration and successes or failures. | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [DORA metrics](dora_metrics.md) | DORA metrics over time. | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
### Security analytics
@@ -62,7 +66,7 @@ Use these features to gain insights into security vulnerabilities and metrics.
| Feature | Description | Project-level | Group-level | Instance-level |
| ------- | ----------- | ------------- | ----------- | -------------- |
-| [Security Dashboards](../application_security/security_dashboard/_index.md) | Collection of metrics, ratings, and charts for vulnerabilities detected by security scanners. | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
+| [Security Dashboards](../application_security/security_dashboard/_index.md) | Collection of metrics, ratings, and charts for vulnerabilities detected by security scanners. | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
## Glossary
diff --git a/doc/user/analytics/ai_impact_analytics.md b/doc/user/analytics/ai_impact_analytics.md
index 5a7bd114223f8aa336fefd0878ae38b5a6bfaf4d..bd83fd073ebe86e4a0dc4d8bb3b3689fdb5ee7ec 100644
--- a/doc/user/analytics/ai_impact_analytics.md
+++ b/doc/user/analytics/ai_impact_analytics.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: AI impact analytics
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443696) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `ai_impact_analytics_dashboard`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/451873) in GitLab 17.2. Feature flag `ai_impact_analytics_dashboard` removed.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443696) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `ai_impact_analytics_dashboard`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/451873) in GitLab 17.2. Feature flag `ai_impact_analytics_dashboard` removed.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+
+{{< /history >}}
The primary goal of AI impact analytics is to measure GitLab Duo's impact on software development lifecycle (SDLC) performance.
This dashboard provides visibility into key SDLC metrics in the context of AI adoption, helping you measure which metrics have improved as a result of AI investments.
@@ -56,10 +63,13 @@ The **Metric trends** table displays metrics for the last six months, with month
- The baseline for the AI Usage trend is the total number of code contributors, not just users with GitLab Duo seats. This baseline gives a more accurate representation of AI usage by team members. To learn more about AI impact analytics, see the blog post [Developing GitLab Duo: AI impact analytics dashboard measures the ROI of AI](https://about.gitlab.com/blog/2024/05/15/developing-gitlab-duo-ai-impact-analytics-dashboard-measures-the-roi-of-ai/).
- To analyze the performance of teams that use AI versus teams that don't, you can create a custom [Value Streams Dashboard Scheduled Report](https://gitlab.com/explore/catalog/components/vsd-reports-generator) based on the AI impact view of projects and groups with and without GitLab Duo.
-NOTE:
+{{< alert type="note" >}}
+
Usage rate for Code Suggestions is calculated with data starting from GitLab 16.11.
For more information, see [epic 12978](https://gitlab.com/groups/gitlab-org/-/epics/12978).
+{{< /alert >}}
+
## View AI impact analytics
Prerequisites:
diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md
index e29c6efd639ea6df190fbc37506fec0af586f440..52c62a4f9283a85bcf378c705008bb42467a93e5 100644
--- a/doc/user/analytics/analytics_dashboards.md
+++ b/doc/user/analytics/analytics_dashboards.md
@@ -5,22 +5,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Analytics dashboards
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - Introduced in GitLab 15.9 as an [experiment](../../policy/development_stages_support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. Disabled by default.
-> - `combined_analytics_dashboards` [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/389067) by default in GitLab 16.11.
-> - `combined_analytics_dashboards` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454350) in GitLab 17.1.
-> - `filters` configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/505317) in GitLab 17.9. Disabled by default.
-> - Inline visualizations configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/509111) in GitLab 17.9.
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced in GitLab 15.9 as an [experiment](../../policy/development_stages_support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. Disabled by default.
+- `combined_analytics_dashboards` [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/389067) by default in GitLab 16.11.
+- `combined_analytics_dashboards` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454350) in GitLab 17.1.
+- `filters` configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/505317) in GitLab 17.9. Disabled by default.
+- Inline visualizations configuration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/509111) in GitLab 17.9.
+
+{{< /history >}}
Analytics dashboards help you visualize the collected data.
You can use built-in dashboards by GitLab or create your own dashboards with custom visualizations.
## Data sources
-> - Product analytics and custom visualization data sources [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/497577) in GitLab 17.7.
+{{< history >}}
+
+- Product analytics and custom visualization data sources [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/497577) in GitLab 17.7.
+
+{{< /history >}}
A data source is a connection to a database or collection of data which can be used by your dashboard
filters and visualizations to query and retrieve results.
@@ -51,8 +62,12 @@ Your dashboard files are versioned in source control with the rest of a project'
## Dashboard designer
-> - Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/411407) in GitLab 16.6. Feature flag `combined_analytics_dashboards_editor` removed.
+{{< history >}}
+
+- Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/411407) in GitLab 16.6. Feature flag `combined_analytics_dashboards_editor` removed.
+
+{{< /history >}}
You can use the dashboard designer to:
@@ -66,16 +81,26 @@ You can use the dashboard designer to:
## Data explorer (deprecated)
-> - Introduced in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `combined_analytics_visualization_editor`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/425048) in GitLab 16.7. Feature flag `combined_analytics_visualization_editor` removed.
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/470875) from "Visualization designer" to "Data explorer" in GitLab 17.6.
+{{< history >}}
+
+- Introduced in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `combined_analytics_visualization_editor`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/425048) in GitLab 16.7. Feature flag `combined_analytics_visualization_editor` removed.
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/470875) from "Visualization designer" to "Data explorer" in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/497577) in GitLab 17.7.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
This feature is only compatible with the product analytics data source.
+{{< /alert >}}
+
You can use the data explorer to explore available data.
<!--- end_remove -->
@@ -94,13 +119,20 @@ To view a list of dashboards (both built-in and custom) for a project:
## View group dashboards
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390542) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/416970) in GitLab 16.8.
-> - Feature flag `group_analytics_dashboards` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/439718) in GitLab 16.11.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390542) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/416970) in GitLab 16.8.
+- Feature flag `group_analytics_dashboards` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/439718) in GitLab 16.11.
+
+{{< /history >}}
Prerequisites:
@@ -122,9 +154,12 @@ Prerequisites:
### Group dashboards
-NOTE:
+{{< alert type="note" >}}
+
[Issue 411572](https://gitlab.com/gitlab-org/gitlab/-/issues/411572) proposes connecting this feature to group-level dashboards.
+{{< /alert >}}
+
To change the location of a group's custom dashboards:
1. On the left sidebar, select **Search or go to** and find the project you want to store your dashboard files in.
@@ -141,13 +176,16 @@ dashboards are usually defined in the project where the analytics data is retrie
However, you can also have a separate project for dashboards.
This setup is recommended if you want to enforce specific access rules to the dashboard definitions or share dashboards across multiple projects.
-NOTE:
+{{< alert type="note" >}}
+
You can share dashboards only between projects that are located in the same group.
+{{< /alert >}}
+
To change the location of project dashboards:
1. On the left sidebar, select **Search or go to** and find your project,
- or select **Create new** (**{plus}**) and **New project/repository**
+ or select **Create new** ({{< icon name="plus" >}}) and **New project/repository**
to create the project to store your dashboard files.
1. On the left sidebar, select **Search or go to** and find the analytics project.
1. Select **Settings > Analytics**.
@@ -185,9 +223,12 @@ To edit an existing custom dashboard:
## Create a custom visualization (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/497577) in GitLab 17.7.
+{{< /alert >}}
+
To create a custom visualization:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -202,13 +243,20 @@ After you save a visualization, you can add it to a new or existing custom dashb
### Generate a custom visualization with GitLab Duo
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com
+- Status: Experiment
+
+{{< /details >}}
-> - Introduced in GitLab 16.11 as an [experiment](../../policy/development_stages_support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `generate_cube_query`. Disabled by default.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+{{< history >}}
+
+- Introduced in GitLab 16.11 as an [experiment](../../policy/development_stages_support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `generate_cube_query`. Disabled by default.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+
+{{< /history >}}
Prerequisites:
@@ -238,8 +286,12 @@ Provide feedback on this experimental feature in [issue 455363](https://gitlab.c
### Visualization query builder
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14098) in GitLab 17.1 [with a flag](../../administration/feature_flags.md) named `analytics_visualization_designer_filtering`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/469461) in GitLab 17.2. Feature flag `analytics_visualization_designer_filtering` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14098) in GitLab 17.1 [with a flag](../../administration/feature_flags.md) named `analytics_visualization_designer_filtering`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/469461) in GitLab 17.2. Feature flag `analytics_visualization_designer_filtering` removed.
+
+{{< /history >}}
You can use measures and dimensions to filter and refine the results of a custom visualization:
@@ -251,9 +303,12 @@ You can filter by custom event names with select measures:
- `Tracked events count`
- `Tracked events unique user count`
-NOTE:
+{{< alert type="note" >}}
+
When you change or remove a measure then dependent dimensions may also be removed.
+{{< /alert >}}
+
<!--- end_remove -->
## Create a dashboard by configuration
@@ -328,12 +383,15 @@ To contribute, see [adding a new visualization render type](../../development/fe
### Define a chart visualization template
-NOTE:
+{{< alert type="note" >}}
+
We recommend using visualization templates sparingly. Visualization templates can lead to long visualization
selection lists in the dashboard editor UI if not managed, which may lead to visualizations being missed or duplicated.
Generally, visualization templates should be reserved for visualizations that will be used identically
across several dashboards.
+{{< /alert >}}
+
If you need a visualization to be used by multiple dashboards, you might store them as separate template files.
When added to a dashboard, the visualization template will be copied over to the dashboard. Visualization templates
copied to dashboards are not updated when the visualization template is updated.
diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md
index e6eb7a38d140f5b506d973d0083be1f486bdb52e..16400902c9cac1aeb8652295307e4819a9a01e96 100644
--- a/doc/user/analytics/ci_cd_analytics.md
+++ b/doc/user/analytics/ci_cd_analytics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CI/CD analytics
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the CI/CD analytics page to view pipeline success rates and duration, and the history of [DevOps Research and Assessment (DORA) metrics](dora_metrics.md) over time.
@@ -25,10 +28,17 @@ pipelines and pipelines that failed with an invalid YAML. To filter pipelines ba
## DevOps Research and Assessment (DORA) metrics charts
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
-> - Time to restore service chart [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356959) in GitLab 15.1.
+{{< history >}}
+
+- Time to restore service chart [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356959) in GitLab 15.1.
+
+{{< /history >}}
CI/CD analytics also display metrics and charts for DORA metrics.
The charts display the evolution of each DORA metric over time, for the last week, month, 90 days, or 180 days.
@@ -44,8 +54,11 @@ Prerequisites:
### For a group
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
To view CI/CD analytics for a group:
diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md
index eec146d0755f85a94f580a4a10d86dbe2ea718ff..20db9d8d419536f65bf4ff2e8322ea41e5ba2ed5 100644
--- a/doc/user/analytics/code_review_analytics.md
+++ b/doc/user/analytics/code_review_analytics.md
@@ -1,16 +1,23 @@
---
-description: "Learn how long your open merge requests have spent in code review, and what distinguishes the longest-running." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here.
stage: Plan
group: Optimize
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
+description: Learn how long your open merge requests have spent in code review, and what distinguishes the longest-running.
title: Code review analytics
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Moved to GitLab Premium in 13.9.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
Code review analytics displays a table of open merge requests that have at least one non-author comment.
The review time is the amount of time since the first comment by a non-author in a merge request.
diff --git a/doc/user/analytics/contributor_analytics.md b/doc/user/analytics/contributor_analytics.md
index 464288a373c723caa7938eba3371e508fb38d388..f06c759e85958246fb23db7d698f9f71ee4e64ac 100644
--- a/doc/user/analytics/contributor_analytics.md
+++ b/doc/user/analytics/contributor_analytics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Contributor analytics
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Contributor analytics give you an overview of the commits made by projects members to a project over time.
@@ -22,7 +25,7 @@ To view contributor analytics for a project:
1. Select **Analyze > Contributor analytics**.
1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for.
1. To view the number of commits made on a specific day, hover over the line chart.
-1. Optional. To display commits only for a specific time period, select the pause icons (**{status-paused}**) and slide them along the horizontal axis:
+1. Optional. To display commits only for a specific time period, select the pause icons ({{< icon name="status-paused" >}}) and slide them along the horizontal axis:
- To change the start date, slide the left pause icon to the left or right.
- To change the end date, slide the right pause icon to the left or right.
@@ -48,4 +51,4 @@ To view the list of commits to the project as an RSS feed in Atom format:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Analyze > Contributor analytics**.
1. Select **History**.
-1. In the upper-right corner, select the feed symbol (**{rss}**).
+1. In the upper-right corner, select the feed symbol ({{< icon name="rss" >}}).
diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md
index 12396a8ea92087837350268feff5b9034dcafddf..e1d7408c9c8b5ec8d7428f197a5102bb2b5ee1b7 100644
--- a/doc/user/analytics/dora_metrics.md
+++ b/doc/user/analytics/dora_metrics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: DevOps Research and Assessment (DORA) metrics
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The [DevOps Research and Assessment (DORA)](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance)
team has identified four metrics that measure DevOps performance.
@@ -25,7 +28,11 @@ For a video explanation, see [DORA metrics: User analytics](https://www.youtube.
## Deployment frequency
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394712) fix for the frequency calculation formula for `all` and `monthly` intervals in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394712) fix for the frequency calculation formula for `all` and `monthly` intervals in GitLab 16.0.
+
+{{< /history >}}
Deployment frequency is the frequency of successful deployments to production over the given date range (hourly, daily, weekly, monthly, or yearly).
@@ -34,10 +41,13 @@ High deployment frequency means you can get feedback sooner and iterate faster t
### Deployment frequency forecasting
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
Deployment frequency forecasting (formerly named Value stream forecasting) uses a statistical forecasting model to predict productivity metrics and identify anomalies across the software development lifecycle.
This information can help you improve planning and decision-making for your product and teams.
@@ -54,11 +64,14 @@ The calculation takes into account the production `environment tier` or the envi
You can configure DORA metrics for different environments by specifying `other` under the `environment_tiers` parameter in the [`.gitlab/insights.yml` file](../project/insights/_index.md#insights-configuration-file).
-NOTE:
+{{< alert type="note" >}}
+
Deployment frequency is calculated as the **average (mean)**, unlike the other DORA metrics that use the median, which is preferred because it provides a more accurate and reliable view of performance.
This difference is because deployment frequency was added to GitLab prior to adopting the DORA framework, and the calculation of this metric remained unchanged when it was incorporated into other reports.
[Issue 499591](https://gitlab.com/gitlab-org/gitlab/-/issues/499591) proposes offering the option to customize the calculation method for each metric, choosing between mean and median.
+{{< /alert >}}
+
### How to improve deployment frequency
The first step is to benchmark the cadence of code releases between groups and projects. Next, you should consider:
@@ -144,17 +157,27 @@ The first step is to benchmark the quality and stability, between groups and pro
## DORA custom calculation rules
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96561) in GitLab 15.4 [with a flag](../../administration/feature_flags.md) named `dora_configuration`. Disabled by default. This feature is an [experiment](../../policy/development_stages_support.md).
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96561) in GitLab 15.4 [with a flag](../../administration/feature_flags.md) named `dora_configuration`. Disabled by default. This feature is an [experiment](../../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
This feature is an [experiment](../../policy/development_stages_support.md).
To join the list of users testing this feature, [here is a suggested test flow](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96561#steps-to-check-on-localhost).
If you find a bug, [open an issue here](https://gitlab.com/groups/gitlab-org/-/epics/11490).
diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md
index e40dfeb856075a93f1206df50487d49a922441e1..219453f1c03ab6d3a64745fb920c567922426752 100644
--- a/doc/user/analytics/merge_request_analytics.md
+++ b/doc/user/analytics/merge_request_analytics.md
@@ -1,14 +1,17 @@
---
-description: "Merge request analytics help you understand the efficiency of your code review process, and the productivity of your team." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here.
stage: Plan
group: Optimize
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
+description: Merge request analytics help you understand the efficiency of your code review process, and the productivity of your team.
title: Merge request analytics
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Merge request analytics provide DevOps managers with valuable insights into their team's code review and merging workflows.
Based on the detailed metrics and trends related to merge requests, organizations can monitor and optimize their development processes.
diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md
index 000dbc1afbc7231d3321c7d2583967e7cf27747f..91aa23486cb29f9af26f852c3ffc6ee3ed3c8517 100644
--- a/doc/user/analytics/productivity_analytics.md
+++ b/doc/user/analytics/productivity_analytics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Productivity analytics
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Productivity analytics display information about merge requests for groups.
diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md
index bb8a1ab3366c80840c4fc992b4930215e1be1031..4b4fba397280b873dfa6ea1c988de8632b2bcbd2 100644
--- a/doc/user/analytics/repository_analytics.md
+++ b/doc/user/analytics/repository_analytics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Repository analytics for projects
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Repository analytics is part of [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss)
and is available to users with permission to clone the repository.
diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md
index 450e1bf7b513b41d7a30e80ee7a34e33c928f142..12b8ef5adf15c4a90fbf30048ece48c4b0519b6e 100644
--- a/doc/user/analytics/value_streams_dashboard.md
+++ b/doc/user/analytics/value_streams_dashboard.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Value Streams Dashboard
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Introduced in GitLab 15.8 as a closed [beta](../../policy/development_stages_support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Disabled by default.
-> - Released in GitLab 15.11 as an open [beta](../../policy/development_stages_support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392734) in GitLab 16.0. Feature flag `group_analytics_dashboards_page` removed.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced in GitLab 15.8 as a closed [beta](../../policy/development_stages_support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Disabled by default.
+- Released in GitLab 15.11 as an open [beta](../../policy/development_stages_support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392734) in GitLab 16.0. Feature flag `group_analytics_dashboards_page` removed.
+
+{{< /history >}}
To help us improve the Value Streams Dashboard, share feedback about your experience in this [survey](https://gitlab.fra1.qualtrics.com/jfe/form/SV_50guMGNU2HhLeT4).
For more information, see the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/).
@@ -41,19 +48,26 @@ To view the Value Streams Dashboard as an analytics dashboard for a group:
1. Select **Analyze > Analytics dashboards**.
1. From the list of available dashboards, select **Value Streams Dashboard**.
-NOTE:
+{{< alert type="note" >}}
+
Data displayed on the Value Streams Dashboard is continuously collected in the backend.
If you upgrade to the Ultimate tier, you get access to historical data, and can view metrics about past GitLab usage and performance.
+{{< /alert >}}
+
## Value Streams Dashboard panels
The Value Streams Dashboard panels have a default configuration, but you can also [customize the dashboard panels](#customize-the-dashboard-panels).
### Overview panel
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439699) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboard_dynamic_vsd`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/432185) in GitLab 17.0.
-> - Feature flag `group_analytics_dashboard_dynamic_vsd` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/441206) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439699) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboard_dynamic_vsd`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/432185) in GitLab 17.0.
+- Feature flag `group_analytics_dashboard_dynamic_vsd` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/441206) in GitLab 17.0.
+
+{{< /history >}}
The Overview panel provides a holistic view of the top-level namespace activity by visualizing key DevOps metrics.
The panel displays metrics for:
@@ -70,12 +84,19 @@ Data is aggregated monthly, around the end of the month, on a best-effort basis
For more information, see [epic 10417](https://gitlab.com/groups/gitlab-org/-/epics/10417#iterations-path).
-NOTE:
+{{< alert type="note" >}}
+
To view metrics on the Overview panel, the [background aggregation](#enable-or-disable-overview-background-aggregation) must be enabled.
+{{< /alert >}}
+
### DevSecOps metrics comparison panels
-> - Contributor count metric at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433353) to GitLab.com in GitLab 16.9.
+{{< history >}}
+
+- Contributor count metric at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433353) to GitLab.com in GitLab 16.9.
+
+{{< /history >}}
The DevSecOps metrics comparison panels display metrics for a group or project
in the month-to-date, last month, the month before, and the past 180 days.
@@ -116,14 +137,21 @@ panels:
- in_review
```
-NOTE:
+{{< alert type="note" >}}
+
Only labels that exactly match the specified filters are applied.
+{{< /alert >}}
+
### DORA Performers score panel
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386843) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `dora_performers_score_panel`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/439737) in GitLab 16.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/440694) in GitLab 16.11. Feature flag `dora_performers_score_panel` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386843) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `dora_performers_score_panel`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/439737) in GitLab 16.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/440694) in GitLab 16.11. Feature flag `dora_performers_score_panel` removed.
+
+{{< /history >}}
The [DORA](dora_metrics.md) Performers score panel is a group-level bar chart that visualizes the status of the organization's DevOps performance levels across different projects for the last full calendar month.
@@ -168,7 +196,11 @@ If multiple topics are provided, all topics must match for the project to be inc
### Projects by DORA metric
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408516) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408516) in GitLab 17.7.
+
+{{< /history >}}
The **Projects by [DORA](dora_metrics.md) metric** panel is a group-level table that lists the status of the organization's DevOps performance levels across projects.
@@ -182,13 +214,20 @@ For further investigation, you can select a project name to drill down into that
## Enable or disable overview background aggregation
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120610) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `value_stream_dashboard_on_off_setting`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130704) in GitLab 16.4.
-> - [Feature flag `value_stream_dashboard_on_off_setting` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134619) in GitLab 16.6.
+- Tier: Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120610) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `value_stream_dashboard_on_off_setting`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130704) in GitLab 16.4.
+- [Feature flag `value_stream_dashboard_on_off_setting` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134619) in GitLab 16.6.
+
+{{< /history >}}
To enable or disable the overview count aggregation for the Value Streams Dashboard:
@@ -223,8 +262,12 @@ To view the Value Streams Dashboard:
### View the Value Streams Dashboard for a project
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137483) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `project_analytics_dashboard_dynamic_vsd`. Disabled by default.
-> - Feature flag `project_analytics_dashboard_dynamic_vsd` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/441207) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137483) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `project_analytics_dashboard_dynamic_vsd`. Disabled by default.
+- Feature flag `project_analytics_dashboard_dynamic_vsd` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/441207) in GitLab 17.5.
+
+{{< /history >}}
Prerequisites:
diff --git a/doc/user/application_security/_index.md b/doc/user/application_security/_index.md
index befe4a7ee635653427508352b2ea8268efa4f760..a6d39429e317da8b9d9224cfe7f934c8362e23a2 100644
--- a/doc/user/application_security/_index.md
+++ b/doc/user/application_security/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Application security
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab can check your application for security vulnerabilities including:
@@ -54,9 +57,12 @@ Although in a major analyzer version you automatically get the latest versions o
tools, there are some [known issues](https://gitlab.com/gitlab-org/gitlab/-/issues/9725) with this
approach.
-NOTE:
+{{< alert type="note" >}}
+
To get the most updated vulnerability information on existing vulnerabilities you may need to re-run the default branch's pipeline.
+{{< /alert >}}
+
## Security scanning
For security scans that run in a CI/CD pipeline, the results are determined by:
@@ -123,8 +129,12 @@ The [security report](../../development/integrations/secure.md#report) artifact
## Security approvals in merge requests
-> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0.
-> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/397067) the License-Check feature in GitLab 16.0.
+{{< history >}}
+
+- [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357300) the Vulnerability-Check feature in GitLab 15.0.
+- [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/397067) the License-Check feature in GitLab 16.0.
+
+{{< /history >}}
You can enforce an additional approval for merge requests that would introduce one of the following
security issues:
diff --git a/doc/user/application_security/api_fuzzing/_index.md b/doc/user/application_security/api_fuzzing/_index.md
index b2882e59bf76b6770ea857e82fa6658022a269d7..dbbe9e2f31f98a4d603132676be379e43681528d 100644
--- a/doc/user/application_security/api_fuzzing/_index.md
+++ b/doc/user/application_security/api_fuzzing/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Web API Fuzz Testing
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Web API fuzzing performs fuzz testing of API operation parameters. Fuzz testing sets operation
parameters to unexpected values in an effort to cause unexpected behavior and errors in the API
@@ -66,9 +69,12 @@ When experiencing a behavior not working as expected, consider providing context
- Full job console output.
- Scanner log file available as a job artifact named `gl-api-security-scanner.log`.
-WARNING:
+{{< alert type="warning" >}}
+
**Sanitize data attached to a support issue**. Remove sensitive information, including: credentials, passwords, tokens, keys, and secrets.
+{{< /alert >}}
+
## Glossary
- Assert: Assertions are detection modules used by checks to trigger a fault. Many assertions have
diff --git a/doc/user/application_security/api_fuzzing/configuration/_index.md b/doc/user/application_security/api_fuzzing/configuration/_index.md
index 09823c6aa260e08a05c583f10b62e28f53a7c2e7..8929eb1c631cdafbc7067cec91dc264f156a029d 100644
--- a/doc/user/application_security/api_fuzzing/configuration/_index.md
+++ b/doc/user/application_security/api_fuzzing/configuration/_index.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Configuration
---
diff --git a/doc/user/application_security/api_fuzzing/configuration/customizing_analyzer_settings.md b/doc/user/application_security/api_fuzzing/configuration/customizing_analyzer_settings.md
index bc2ebd5adeb61d41f169672157504642c3e8dca8..32ab4795bd042798af386d4a71cc37c10b5f0292 100644
--- a/doc/user/application_security/api_fuzzing/configuration/customizing_analyzer_settings.md
+++ b/doc/user/application_security/api_fuzzing/configuration/customizing_analyzer_settings.md
@@ -9,11 +9,14 @@ The API fuzzing behavior can be changed through CI/CD variables.
The API fuzzing configuration files must be in your repository's `.gitlab` directory.
-WARNING:
+{{< alert type="warning" >}}
+
All customization of GitLab security scanning tools should be tested in a merge request before
merging these changes to the default branch. Failure to do so can give unexpected results,
including a large number of false positives.
+{{< /alert >}}
+
## Authentication
Authentication is handled by providing the authentication token as a header or cookie. You can
@@ -421,10 +424,13 @@ to execute. The provided command creates the overrides JSON file as defined prev
You might want to install other scripting runtimes like NodeJS or Ruby, or maybe you need to install a dependency for your overrides command. In this case, you should set the `FUZZAPI_PRE_SCRIPT` to the file path of a script that provides those prerequisites. The script provided by `FUZZAPI_PRE_SCRIPT` is executed once, before the analyzer starts.
-NOTE:
+{{< alert type="note" >}}
+
When performing actions that require elevated permissions, make use of the `sudo` command.
For example, `sudo apk add nodejs`.
+{{< /alert >}}
+
See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management)
page for information about installing Alpine Linux packages.
@@ -438,9 +444,12 @@ Optionally:
- `FUZZAPI_PRE_SCRIPT`: Script to install runtimes or dependencies before the analyzer starts.
-WARNING:
+{{< alert type="warning" >}}
+
To execute scripts in Alpine Linux you must first use the command [`chmod`](https://www.gnu.org/software/coreutils/manual/html_node/chmod-invocation.html) to set the [execution permission](https://www.gnu.org/software/coreutils/manual/html_node/Setting-Permissions.html). For example, to set the execution permission of `script.py` for everyone, use the command: `sudo chmod a+x script.py`. If needed, you can version your `script.py` with the execution permission already set.
+{{< /alert >}}
+
```yaml
stages:
- fuzz
@@ -895,9 +904,12 @@ In your job output you can check if any URLs matched any provided regular expres
2021-05-27 21:51:08 [INF] API Fuzzing: ------------------------------------------------
```
-NOTE:
+{{< alert type="note" >}}
+
Each value in `FUZZAPI_EXCLUDE_URLS` is a regular expression. Characters such as `.` , `*` and `$` among many others have special meanings in [regular expressions](https://en.wikipedia.org/wiki/Regular_expression#Standards).
+{{< /alert >}}
+
### Examples
#### Excluding a URL and child resources
diff --git a/doc/user/application_security/api_fuzzing/configuration/enabling_the_analyzer.md b/doc/user/application_security/api_fuzzing/configuration/enabling_the_analyzer.md
index a7402217f3d5e6e99ea41ca6a3229b84f8378295..ffcde4e57956557e50eaf45248c8a3f48890a102 100644
--- a/doc/user/application_security/api_fuzzing/configuration/enabling_the_analyzer.md
+++ b/doc/user/application_security/api_fuzzing/configuration/enabling_the_analyzer.md
@@ -17,11 +17,14 @@ Prerequisites:
- HTTP Archive (HAR) of API requests to test
- Postman Collection v2.0 or v2.1
- WARNING:
+ {{< alert type="warning" >}}
+
**Never** run fuzz testing against a production server. Not only can it perform *any* function that
the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting
data. Only run fuzzing against a test server.
+ {{< /alert >}}
+
To enable Web API fuzzing use the Web API fuzzing configuration form.
- For manual configuration instructions, see the respective section, depending on the API type:
@@ -153,10 +156,13 @@ uses them to perform testing.
For more details, including how to create a HAR file, see [HTTP Archive format](../create_har_files.md).
-WARNING:
+{{< alert type="warning" >}}
+
HAR files may contain sensitive information such as authentication tokens, API keys, and session
cookies. We recommend that you review the HAR file contents before adding them to a repository.
+{{< /alert >}}
+
### Configure Web API fuzzing with a HAR file
To configure API fuzzing to use a HAR file:
@@ -212,7 +218,11 @@ For details of API fuzzing configuration options, see [Available CI/CD variables
## GraphQL Schema
-> - Support for GraphQL Schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4.
+{{< history >}}
+
+- Support for GraphQL Schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4.
+
+{{< /history >}}
GraphQL is a query language for your API and an alternative to REST APIs.
API Fuzzing supports testing GraphQL endpoints multiple ways:
@@ -229,9 +239,12 @@ Introspection is enabled by default to allow tools like GraphiQL to work.
The GraphQL support in API Fuzzing is able to query a GraphQL endpoint for the schema.
-NOTE:
+{{< alert type="note" >}}
+
The GraphQL endpoint must support introspection queries for this method to work correctly.
+{{< /alert >}}
+
To configure API Fuzzing to use an GraphQL endpoint URL that provides information about the target API to test:
1. [Include](../../../../ci/yaml/_index.md#includetemplate)
@@ -336,11 +349,14 @@ When used with the GitLab API fuzzer, Postman Collections must contain definitio
test with valid data. The API fuzzer extracts all the API definitions and uses them to perform
testing.
-WARNING:
+{{< alert type="warning" >}}
+
Postman Collection files may contain sensitive information such as authentication tokens, API keys,
and session cookies. We recommend that you review the Postman Collection file contents before adding
them to a repository.
+{{< /alert >}}
+
### Configure Web API fuzzing with a Postman Collection file
To configure API fuzzing to use a Postman Collection file:
@@ -397,9 +413,13 @@ For details of API fuzzing configuration options, see [Available CI/CD variables
### Postman variables
-> - Support for Postman Environment file format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
-> - Support for multiple variable files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
-> - Support for Postman variable scopes: Global and Environment was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
+{{< history >}}
+
+- Support for Postman Environment file format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
+- Support for multiple variable files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
+- Support for Postman variable scopes: Global and Environment was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
+
+{{< /history >}}
#### Variables in Postman Client
diff --git a/doc/user/application_security/api_fuzzing/configuration/offline_configuration.md b/doc/user/application_security/api_fuzzing/configuration/offline_configuration.md
index 325103e663b41a1ed4e9779268941be737519bd2..6ee0b2e05beb9576d1956d3392558c5ad205bd67 100644
--- a/doc/user/application_security/api_fuzzing/configuration/offline_configuration.md
+++ b/doc/user/application_security/api_fuzzing/configuration/offline_configuration.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Offline configuration
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
For instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the Web API Fuzz testing job to successfully run.
@@ -24,7 +27,10 @@ For example, the below line sets a registry for the image `registry.gitlab.com/s
`SECURE_ANALYZERS_PREFIX: "registry.gitlab.com/security-products"`
-NOTE:
+{{< alert type="note" >}}
+
Setting `SECURE_ANALYZERS_PREFIX` changes the Docker image registry location for all GitLab Secure templates.
+{{< /alert >}}
+
For more information, see [Offline environments](../../offline_deployments/_index.md).
diff --git a/doc/user/application_security/api_fuzzing/configuration/overriding_analyzer_jobs.md b/doc/user/application_security/api_fuzzing/configuration/overriding_analyzer_jobs.md
index 8d5bf3e7541544c5136bb920cb3039b6b29d852d..8b0825a2bcc561407c208b9da6672c0924bf9fbd 100644
--- a/doc/user/application_security/api_fuzzing/configuration/overriding_analyzer_jobs.md
+++ b/doc/user/application_security/api_fuzzing/configuration/overriding_analyzer_jobs.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Overriding API Fuzzing jobs
---
diff --git a/doc/user/application_security/api_fuzzing/configuration/requirements.md b/doc/user/application_security/api_fuzzing/configuration/requirements.md
index 1ab1ae75b5214bb723ecf0eda675f4dd247934bf..66b3b7c5d09a5e607780e756da348aaf09fb3c58 100644
--- a/doc/user/application_security/api_fuzzing/configuration/requirements.md
+++ b/doc/user/application_security/api_fuzzing/configuration/requirements.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Requirements
---
diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md
index 570b6b41a73bf5b2f4356b23632687d80307cf13..5470a2c802967ab8df9b0a35fc78a0ef2f98de37 100644
--- a/doc/user/application_security/api_fuzzing/create_har_files.md
+++ b/doc/user/application_security/api_fuzzing/create_har_files.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Create HAR Files
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
HTTP Archive (HAR) format files are an industry standard for exchanging information about HTTP
requests and HTTP responses. A HAR file's content is JSON formatted, containing browser interactions
@@ -16,11 +19,14 @@ with a web site. The file extension `.har` is commonly used.
The HAR files can be used to perform [web API Fuzz Testing](configuration/enabling_the_analyzer.md#http-archive-har) as part of
your [GitLab CI/CD](../../../ci/_index.md) pipelines.
-WARNING:
+{{< alert type="warning" >}}
+
A HAR file stores information exchanged between web client and web server. It could also
store sensitive information such as authentication tokens, API keys, and session cookies. We
recommend that you review the HAR file contents before adding them to a repository.
+{{< /alert >}}
+
## HAR file creation
You can create HAR files manually or by using a specialized tool for recording web sessions. We
@@ -37,11 +43,14 @@ automatically record your network activity and generate the HAR file:
1. [Chrome web browser](#chrome-web-browser).
1. [Firefox web browser](#firefox-web-browser).
-WARNING:
+{{< alert type="warning" >}}
+
HAR files may contain sensitive information such as authentication tokens, API keys, and
session cookies. We recommend that you review the HAR file contents before adding them to a
repository.
+{{< /alert >}}
+
### GitLab HAR Recorder
[GitLab HAR Recorder](https://gitlab.com/gitlab-org/security-products/har-recorder) is a command
diff --git a/doc/user/application_security/api_fuzzing/performance.md b/doc/user/application_security/api_fuzzing/performance.md
index bd60b45e4712fcae099ca4a3c6da8a6d366f7c4b..8c1ff7d848e2d7f6d9bcd18e34a97c307f873ab5 100644
--- a/doc/user/application_security/api_fuzzing/performance.md
+++ b/doc/user/application_security/api_fuzzing/performance.md
@@ -106,9 +106,12 @@ apifuzzer_fuzz:
FUZZAPI_EXCLUDE_PATHS: /api/large_response_json
```
-WARNING:
+{{< alert type="warning" >}}
+
Excluding operations from testing could allow some vulnerabilities to go undetected.
+{{< /alert >}}
+
### Splitting a test into multiple jobs
Splitting a test into multiple jobs is supported by API Fuzzing through the use of [`FUZZAPI_EXCLUDE_PATHS`](configuration/customizing_analyzer_settings.md#exclude-paths) and [`FUZZAPI_EXCLUDE_URLS`](configuration/customizing_analyzer_settings.md#exclude-urls). When splitting a test up, a good pattern is to disable the `apifuzzer_fuzz` job and replace it with two jobs with identifying names. In this example we have two jobs, each job is testing a version of the API, so our names reflect that. However, this technique can be applied to any situation, not just with versions of an API.
diff --git a/doc/user/application_security/api_fuzzing/troubleshooting.md b/doc/user/application_security/api_fuzzing/troubleshooting.md
index edde4485bc7f1017ebb1715ec0b2f52445a2a815..fadc0c89c869333bf6c33e8ac5030236abbc1e50 100644
--- a/doc/user/application_security/api_fuzzing/troubleshooting.md
+++ b/doc/user/application_security/api_fuzzing/troubleshooting.md
@@ -190,8 +190,8 @@ To detect and correct elements that don't comply with the OpenAPI specifications
| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x |
|----------------------------------------------------|-------------------------------|-------------------------------|---------------|
-| [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON |
-| [Stoplight Studio](https://stoplight.io/solutions) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON |
+| [Swagger Editor](https://editor.swagger.io/) | {{< icon name="check-circle" >}} YAML, JSON | {{< icon name="check-circle" >}} YAML, JSON | {{< icon name="dotted-circle" >}} YAML, JSON |
+| [Stoplight Studio](https://stoplight.io/solutions) | {{< icon name="check-circle" >}} YAML, JSON | {{< icon name="check-circle" >}} YAML, JSON | {{< icon name="check-circle" >}} YAML, JSON |
If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using.
diff --git a/doc/user/application_security/api_security/_index.md b/doc/user/application_security/api_security/_index.md
index 610ea02376df51af3d8bbee7338865010b2bd684..e4ad9248d8e97e28ca257d9d2eae550c65138880 100644
--- a/doc/user/application_security/api_security/_index.md
+++ b/doc/user/application_security/api_security/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: API Security
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
API Security refers to the measures taken to secure and protect web Application Programming Interfaces (APIs) from unauthorized access, misuse, and attacks.
APIs are a crucial component of modern application development as they allow applications to interact with each other and exchange data.
diff --git a/doc/user/application_security/api_security/api_discovery/_index.md b/doc/user/application_security/api_security/api_discovery/_index.md
index 16b99e4266a4be86f2ceb5cd282968c8a7f80ada..c7ca3cfcec9d2f16245130f0829c24f4ee97d286 100644
--- a/doc/user/application_security/api_security/api_discovery/_index.md
+++ b/doc/user/application_security/api_security/api_discovery/_index.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: API Discovery
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9302) in GitLab 15.9. The API Discovery feature is in [beta](../../../../policy/development_stages_support.md).
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9302) in GitLab 15.9. The API Discovery feature is in [beta](../../../../policy/development_stages_support.md).
+
+{{< /history >}}
API Discovery analyzes your application and produces an OpenAPI document describing the web APIs it exposes. This schema document can then be used by the [API security testing analyzer](../../api_security_testing/_index.md) or [API Fuzzing](../../api_fuzzing/_index.md) to perform security scans of the web API.
diff --git a/doc/user/application_security/api_security_testing/_index.md b/doc/user/application_security/api_security_testing/_index.md
index 10f6a8fa0943fa6c3079d5920e94c5c7860877e9..e24ff62800f5b9e452a1757d92605efd148a8a3a 100644
--- a/doc/user/application_security/api_security_testing/_index.md
+++ b/doc/user/application_security/api_security_testing/_index.md
@@ -5,23 +5,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: API security testing analyzer
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/4254) in GitLab 15.6 to the default analyzer for on-demand API security testing scans.
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/457449) in GitLab 17.0 from "DAST API analyzer" to "API security testing analyzer".
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/4254) in GitLab 15.6 to the default analyzer for on-demand API security testing scans.
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/457449) in GitLab 17.0 from "DAST API analyzer" to "API security testing analyzer".
+
+{{< /history >}}
Perform Dynamic Application Security Testing (DAST) of web APIs to help discover bugs and potential
security issues that other QA processes may miss. Use API security testing in addition to
other [GitLab Secure](../_index.md) security scanners and your own test processes. You can run DAST
API tests either as part your CI/CD workflow, [on-demand](../dast/on-demand_scan.md), or both.
-WARNING:
+{{< alert type="warning" >}}
+
Do not run API security testing against a production server. Not only can it perform _any_ function that
the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting
data. Only run API security testing against a test server.
+{{< /alert >}}
+
API security testing can test the following web API types:
- REST API
@@ -29,10 +39,13 @@ API security testing can test the following web API types:
- GraphQL
- Form bodies, JSON, or XML
-NOTE:
+{{< alert type="note" >}}
+
DAST API has been re-branded to API Security Testing. As part of this re-branding the template
name and variable prefixes have also been updated. The old template and variable names continue to work until the next major release, 18.0 in May 2025.
+{{< /alert >}}
+
## When API security testing scans run
When run in your CI/CD pipeline, API security testing scanning runs in the `dast` stage by default. To ensure
@@ -74,9 +87,12 @@ When experiencing a behavior not working as expected, consider providing context
- Full job console output.
- Scanner log file available as a job artifact named `gl-api-security-scanner.log`.
-WARNING:
+{{< alert type="warning" >}}
+
**Sanitize data attached to a support issue**. Remove sensitive information, including: credentials, passwords, tokens, keys, and secrets.
+{{< /alert >}}
+
## Glossary
- Assert: Assertions are detection modules used by checks to trigger a vulnerability. Many assertions have
diff --git a/doc/user/application_security/api_security_testing/checks/_index.md b/doc/user/application_security/api_security_testing/checks/_index.md
index 58d6c700cf5b48e95f370f20eb00955dc96d5073..2e30d3907d358b32d331d09732dff5b18ea0b11f 100644
--- a/doc/user/application_security/api_security_testing/checks/_index.md
+++ b/doc/user/application_security/api_security_testing/checks/_index.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: API security testing vulnerability checks
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/457449) from **DAST API vulnerability checks** to **API security testing vulnerability checks** in GitLab 17.0.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/457449) from **DAST API vulnerability checks** to **API security testing vulnerability checks** in GitLab 17.0.
+
+{{< /history >}}
[API security testing](../_index.md) provides vulnerability checks that are used to
scan for vulnerabilities in the API under test.
diff --git a/doc/user/application_security/api_security_testing/configuration/_index.md b/doc/user/application_security/api_security_testing/configuration/_index.md
index 09823c6aa260e08a05c583f10b62e28f53a7c2e7..8929eb1c631cdafbc7067cec91dc264f156a029d 100644
--- a/doc/user/application_security/api_security_testing/configuration/_index.md
+++ b/doc/user/application_security/api_security_testing/configuration/_index.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Configuration
---
diff --git a/doc/user/application_security/api_security_testing/configuration/customizing_analyzer_settings.md b/doc/user/application_security/api_security_testing/configuration/customizing_analyzer_settings.md
index b256031438a542fa2f72f3de4d09aa7c465a9fa0..b764d05e0bc6a4f647b7488e92993bede49391f6 100644
--- a/doc/user/application_security/api_security_testing/configuration/customizing_analyzer_settings.md
+++ b/doc/user/application_security/api_security_testing/configuration/customizing_analyzer_settings.md
@@ -398,10 +398,13 @@ to execute. The provided command creates the overrides JSON file as defined prev
You might want to install other scripting runtimes like NodeJS or Ruby, or maybe you need to install a dependency for your overrides command. In this case, you should set the `APISEC_PRE_SCRIPT` to the file path of a script which provides those prerequisites. The script provided by `APISEC_PRE_SCRIPT` is executed once before the analyzer starts.
-NOTE:
+{{< alert type="note" >}}
+
When performing actions that require elevated permissions, make use of the `sudo` command.
For example, `sudo apk add nodejs`.
+{{< /alert >}}
+
See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) page for information about installing Alpine Linux packages.
You must provide three CI/CD variables, each set for correct operation:
@@ -414,9 +417,12 @@ Optionally:
- `APISEC_PRE_SCRIPT`: Script to install runtimes or dependencies before the scan starts.
-WARNING:
+{{< alert type="warning" >}}
+
To execute scripts in Alpine Linux you must first use the command [`chmod`](https://www.gnu.org/software/coreutils/manual/html_node/chmod-invocation.html) to set the [execution permission](https://www.gnu.org/software/coreutils/manual/html_node/Setting-Permissions.html). For example, to set the execution permission of `script.py` for everyone, use the command: `sudo chmod a+x script.py`. If needed, you can version your `script.py` with the execution permission already set.
+{{< /alert >}}
+
```yaml
stages:
- dast
@@ -602,9 +608,12 @@ The order in which the different headers are provided into the variable `APISEC_
The `APISEC_REQUEST_HEADERS_BASE64` variable accepts the same list of headers as `APISEC_REQUEST_HEADERS`, with the only difference that the entire value of the variable must be Base64-encoded. For example, to set `APISEC_REQUEST_HEADERS_BASE64` variable to `Authorization: QmVhcmVyIFRPS0VO, Cache-control: bm8tY2FjaGU=`, ensure you convert the list to its Base64 equivalent: `QXV0aG9yaXphdGlvbjogUW1WaGNtVnlJRlJQUzBWTywgQ2FjaGUtY29udHJvbDogYm04dFkyRmphR1U9`, and the Base64-encoded value must be used. This is useful when storing secret header values in a [masked variable](../../../../ci/variables/_index.md#mask-a-cicd-variable), which has character set restrictions.
-WARNING:
+{{< alert type="warning" >}}
+
Base64 is used to support the [masked variable](../../../../ci/variables/_index.md#mask-a-cicd-variable) feature. Base64 encoding is not by itself a security measure, because sensitive values can be easily decoded.
+{{< /alert >}}
+
### Example: Adding a list of headers on each request using plain text
In the following example of a `.gitlab-ci.yml`, `APISEC_REQUEST_HEADERS` configuration variable is set to provide two header values as explained in [request headers](#request-headers).
@@ -938,9 +947,12 @@ In your job output you can check if any URLs matched any provided regular expres
2021-05-27 21:51:08 [INF] API SECURITY: ------------------------------------------------
```
-NOTE:
+{{< alert type="note" >}}
+
Each value in `APISEC_EXCLUDE_URLS` is a regular expression. Characters such as `.` , `*` and `$` among many others have special meanings in [regular expressions](https://en.wikipedia.org/wiki/Regular_expression#Standards).
+{{< /alert >}}
+
#### Examples
##### Excluding a URL and child resources
diff --git a/doc/user/application_security/api_security_testing/configuration/enabling_the_analyzer.md b/doc/user/application_security/api_security_testing/configuration/enabling_the_analyzer.md
index cb9735c487bf626efba194e80dca2d485f54ef76..8b6ee63116b9d9de351909e685063559bc7d2976 100644
--- a/doc/user/application_security/api_security_testing/configuration/enabling_the_analyzer.md
+++ b/doc/user/application_security/api_security_testing/configuration/enabling_the_analyzer.md
@@ -103,10 +103,13 @@ You can use various tools to generate HAR files:
- [Fiddler](https://www.telerik.com/fiddler): Web debugging proxy
- [GitLab HAR Recorder](https://gitlab.com/gitlab-org/security-products/har-recorder): Command line
-WARNING:
+{{< alert type="warning" >}}
+
HAR files may contain sensitive information such as authentication tokens, API keys, and session
cookies. We recommend that you review the HAR file contents before adding them to a repository.
+{{< /alert >}}
+
### API security testing scanning with a HAR file
To configure API security testing to use a HAR file that provides information about the target API to test:
@@ -154,7 +157,11 @@ This example is a minimal configuration for API security testing. From here you
## GraphQL Schema
-> - Support for GraphQL Schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4.
+{{< history >}}
+
+- Support for GraphQL Schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4.
+
+{{< /history >}}
GraphQL is a query language for your API and an alternative to REST APIs.
API security testing supports testing GraphQL endpoints multiple ways:
@@ -172,9 +179,12 @@ For details on how to enable introspection, see your GraphQL framework documenta
The GraphQL support in API security testing is able to query a GraphQL endpoint for the schema.
-NOTE:
+{{< alert type="note" >}}
+
The GraphQL endpoint must support introspection queries for this method to work correctly.
+{{< /alert >}}
+
To configure API security testing to use a GraphQL endpoint URL that provides information about the target API to test:
1. [Include](../../../../ci/yaml/_index.md#includetemplate)
@@ -279,11 +289,14 @@ When used with the GitLab API security testing scanner, Postman Collections must
test with valid data. The API security testing scanner extracts all the API definitions and uses them to perform
testing.
-WARNING:
+{{< alert type="warning" >}}
+
Postman Collection files may contain sensitive information such as authentication tokens, API keys,
and session cookies. We recommend that you review the Postman Collection file contents before adding
them to a repository.
+{{< /alert >}}
+
### API security testing scanning with a Postman Collection file
To configure API security testing to use a Postman Collection file that provides information about the target
@@ -331,9 +344,13 @@ This is a minimal configuration for API security testing. From here you can:
### Postman variables
-> - Support for Postman Environment file format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
-> - Support for multiple variable files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
-> - Support for Postman variable scopes: Global and Environment was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
+{{< history >}}
+
+- Support for Postman Environment file format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
+- Support for multiple variable files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
+- Support for Postman variable scopes: Global and Environment was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1.
+
+{{< /history >}}
#### Variables in Postman Client
diff --git a/doc/user/application_security/api_security_testing/configuration/offline_configuration.md b/doc/user/application_security/api_security_testing/configuration/offline_configuration.md
index 1994821c95a8faddfb46fc70b3dfcae54f0c18a0..6a2b23685eafb2ef4135898ad3264f3e229aef77 100644
--- a/doc/user/application_security/api_security_testing/configuration/offline_configuration.md
+++ b/doc/user/application_security/api_security_testing/configuration/offline_configuration.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Offline configuration
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
For instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the API security testing job to successfully run.
@@ -20,14 +23,20 @@ The Docker image for API security testing must be pulled (downloaded) from the p
Once the Docker image is hosted locally, the `SECURE_ANALYZERS_PREFIX` variable is set with the location of the local registry. The variable must be set such that concatenating `/api-security:2` results in a valid image location.
-NOTE:
+{{< alert type="note" >}}
+
API security testing and API Fuzzing both use the same underlying Docker image `api-security:2`.
+{{< /alert >}}
+
For example, the below line sets a registry for the image `registry.gitlab.com/security-products/api-security:2`:
`SECURE_ANALYZERS_PREFIX: "registry.gitlab.com/security-products"`
-NOTE:
+{{< alert type="note" >}}
+
Setting `SECURE_ANALYZERS_PREFIX` changes the Docker image registry location for all GitLab Secure templates.
+{{< /alert >}}
+
For more information, see [Offline environments](../../offline_deployments/_index.md).
diff --git a/doc/user/application_security/api_security_testing/configuration/overriding_analyzer_jobs.md b/doc/user/application_security/api_security_testing/configuration/overriding_analyzer_jobs.md
index 7260880b15947ecc0603ef393fe03ffd9817bef9..8433eacc7bf52dee2cc5b9cc85c72aa656e0a19c 100644
--- a/doc/user/application_security/api_security_testing/configuration/overriding_analyzer_jobs.md
+++ b/doc/user/application_security/api_security_testing/configuration/overriding_analyzer_jobs.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Overriding API security testing jobs
---
diff --git a/doc/user/application_security/api_security_testing/configuration/requirements.md b/doc/user/application_security/api_security_testing/configuration/requirements.md
index 640aef018ad07abd8e501d4b204e7fd130e8f76e..6fcf57b03d57bfe1cf5c1f17ced8a5bd646d58ca 100644
--- a/doc/user/application_security/api_security_testing/configuration/requirements.md
+++ b/doc/user/application_security/api_security_testing/configuration/requirements.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Requirements
---
diff --git a/doc/user/application_security/api_security_testing/configuration/variables.md b/doc/user/application_security/api_security_testing/configuration/variables.md
index 319f79f03950ded926e118311bd62d4cf3820151..b1b922aa136fedcf8d5d1bbee03f0c4bb67276d1 100644
--- a/doc/user/application_security/api_security_testing/configuration/variables.md
+++ b/doc/user/application_security/api_security_testing/configuration/variables.md
@@ -5,7 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Available CI/CD variables and configuration files
---
-> - [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/450445) Changed template name from `DAST-API.gitlab-ci.yml` to `API-Security.gitlab-ci.yml` and variable prefixed from `DAST_API_` to `APISEC_` in GitLab 17.1.
+{{< history >}}
+
+- [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/450445) Changed template name from `DAST-API.gitlab-ci.yml` to `API-Security.gitlab-ci.yml` and variable prefixed from `DAST_API_` to `APISEC_` in GitLab 17.1.
+
+{{< /history >}}
## Available CI/CD variables
diff --git a/doc/user/application_security/api_security_testing/performance.md b/doc/user/application_security/api_security_testing/performance.md
index bc3ed943c2599bf0a97e1cf9562f42fa8102530e..189aab5dad3bd99590a65d571236fa023d011162 100644
--- a/doc/user/application_security/api_security_testing/performance.md
+++ b/doc/user/application_security/api_security_testing/performance.md
@@ -105,9 +105,12 @@ api_security:
APISEC_EXCLUDE_PATHS: /api/large_response_json
```
-WARNING:
+{{< alert type="warning" >}}
+
Excluding operations from testing could allow some vulnerabilities to go undetected.
+{{< /alert >}}
+
### Splitting a test into multiple jobs
Splitting a test into multiple jobs is supported by API security testing through the use of [`APISEC_EXCLUDE_PATHS`](configuration/customizing_analyzer_settings.md#exclude-paths) and [`APISEC_EXCLUDE_URLS`](configuration/customizing_analyzer_settings.md#exclude-urls). When splitting a test up, a good pattern is to disable the `dast_api` job and replace it with two jobs with identifying names. In this example we have two jobs, each job is testing a version of the API, so our names reflect that. However, this technique can be applied to any situation, not just with versions of an API.
diff --git a/doc/user/application_security/api_security_testing/troubleshooting.md b/doc/user/application_security/api_security_testing/troubleshooting.md
index 68aa74ec7ef3eaf78a4878f3a92370a3ab2d6668..5f2359acb6c654424421c06a93623f191a1b75ec 100644
--- a/doc/user/application_security/api_security_testing/troubleshooting.md
+++ b/doc/user/application_security/api_security_testing/troubleshooting.md
@@ -160,8 +160,8 @@ To detect and correct elements that don't comply with the OpenAPI specifications
| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x |
| -- | -- | -- | -- |
-| [Stoplight Studio](https://stoplight.io/solutions) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON |
-| [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON |
+| [Stoplight Studio](https://stoplight.io/solutions) | {{< icon name="check-circle" >}} YAML, JSON | {{< icon name="check-circle" >}} YAML, JSON | {{< icon name="check-circle" >}} YAML, JSON |
+| [Swagger Editor](https://editor.swagger.io/) | {{< icon name="check-circle" >}} YAML, JSON | {{< icon name="check-circle" >}} YAML, JSON | {{< icon name="dotted-circle" >}} YAML, JSON |
If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using.
diff --git a/doc/user/application_security/comparison_dependency_and_container_scanning.md b/doc/user/application_security/comparison_dependency_and_container_scanning.md
index b8dac32924adda5ca8775d0a4f28ea8539b7993d..a77536a7ce87e189dbb47d32dc949182be3578af 100644
--- a/doc/user/application_security/comparison_dependency_and_container_scanning.md
+++ b/doc/user/application_security/comparison_dependency_and_container_scanning.md
@@ -20,13 +20,13 @@ The following table summarizes which types of dependencies each scanning tool ca
| Feature | Dependency Scanning | Container Scanning |
|----------------------------------------------------------------------------------------------|---------------------|---------------------------------|
-| Identify the manifest, lock file, or static file that introduced the dependency | **{check-circle}** | **{dotted-circle}** |
-| Development dependencies | **{check-circle}** | **{dotted-circle}** |
-| Dependencies in a lock file committed to your repository | **{check-circle}** | **{check-circle}** <sup>1</sup> |
-| Binaries built by Go | **{dotted-circle}** | **{check-circle}** <sup>2</sup> |
-| Dynamically-linked language-specific dependencies installed by the Operating System | **{dotted-circle}** | **{check-circle}** |
-| Operating system dependencies | **{dotted-circle}** | **{check-circle}** |
-| Language-specific dependencies installed on the operating system (not built by your project) | **{dotted-circle}** | **{check-circle}** |
+| Identify the manifest, lock file, or static file that introduced the dependency | {{< icon name="check-circle" >}} | {{< icon name="dotted-circle" >}} |
+| Development dependencies | {{< icon name="check-circle" >}} | {{< icon name="dotted-circle" >}} |
+| Dependencies in a lock file committed to your repository | {{< icon name="check-circle" >}} | {{< icon name="check-circle" >}} <sup>1</sup> |
+| Binaries built by Go | {{< icon name="dotted-circle" >}} | {{< icon name="check-circle" >}} <sup>2</sup> |
+| Dynamically-linked language-specific dependencies installed by the Operating System | {{< icon name="dotted-circle" >}} | {{< icon name="check-circle" >}} |
+| Operating system dependencies | {{< icon name="dotted-circle" >}} | {{< icon name="check-circle" >}} |
+| Language-specific dependencies installed on the operating system (not built by your project) | {{< icon name="dotted-circle" >}} | {{< icon name="check-circle" >}} |
1. Lock file must be present in the image to be detected.
1. [Report language-specific findings](container_scanning/_index.md#report-language-specific-findings) must be enabled, and binaries must be present in the image to be detected.
diff --git a/doc/user/application_security/configuration/_index.md b/doc/user/application_security/configuration/_index.md
index 2938aa4fd76e75626133d4fab8177a278bcb8138..997f89a6d54367cdf636ca5016736ff656b4aa53 100644
--- a/doc/user/application_security/configuration/_index.md
+++ b/doc/user/application_security/configuration/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Security configuration
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The **Security configuration** page lists the following for the security testing and compliance tools:
@@ -73,9 +76,12 @@ You can configure the following security controls:
## Compliance
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can configure the following security controls:
diff --git a/doc/user/application_security/container_scanning/_index.md b/doc/user/application_security/container_scanning/_index.md
index 8cc7c50722329aed500cdd7d26845319c0ce62a5..71613e1e5894a8db6426415b34cbac8b7fc1f929 100644
--- a/doc/user/application_security/container_scanning/_index.md
+++ b/doc/user/application_security/container_scanning/_index.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Container Scanning
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86092) the major analyzer version from `4` to `5` in GitLab 15.0.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86783) from GitLab Ultimate to GitLab Free in 15.0.
-> - Container Scanning variables that reference Docker [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/357264) in GitLab 15.4.
-> - Container Scanning template [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/381665) from `Security/Container-Scanning.gitlab-ci.yml` to `Jobs/Container-Scanning.gitlab-ci.yml` in GitLab 15.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86092) the major analyzer version from `4` to `5` in GitLab 15.0.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86783) from GitLab Ultimate to GitLab Free in 15.0.
+- Container Scanning variables that reference Docker [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/357264) in GitLab 15.4.
+- Container Scanning template [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/381665) from `Security/Container-Scanning.gitlab-ci.yml` to `Jobs/Container-Scanning.gitlab-ci.yml` in GitLab 15.6.
+
+{{< /history >}}
Your application's Docker image may itself be based on Docker images that contain known
vulnerabilities. By including an extra Container Scanning job in your pipeline that scans for those
@@ -36,13 +43,16 @@ possible, we encourage you to use all the security scanners. For a comparison of
GitLab integrates with the [Trivy](https://github.com/aquasecurity/trivy) security scanner to perform vulnerability static analysis in containers.
-WARNING:
+{{< alert type="warning" >}}
+
The Grype analyzer is no longer maintained, except for limited fixes as explained in our
[statement of support](https://about.gitlab.com/support/statement-of-support/#version-support).
The existing current major version for the Grype analyzer image will continue to be updated with the
latest advisory database, and operating system packages until GitLab 19.0, at which point the analyzer
will stop working.
+{{< /alert >}}
+
GitLab compares the found vulnerabilities between the source and target branches, then:
- Displays the results in the merge request widget.
@@ -58,17 +68,17 @@ GitLab compares the found vulnerabilities between the source and target branches
| Features | In Free and Premium | In Ultimate |
| --- | ------ | ------ |
-| Customize Settings ([Variables](#available-cicd-variables), [Overriding](#overriding-the-container-scanning-template), [offline environment support](#running-container-scanning-in-an-offline-environment), etc) | **{check-circle}** Yes | **{check-circle}** Yes |
-| [View JSON Report](#reports-json-format) as a CI job artifact | **{check-circle}** Yes | **{check-circle}** Yes |
-| Generate a [CycloneDX SBOM JSON report](#cyclonedx-software-bill-of-materials) as a CI job artifact | **{check-circle}** Yes | **{check-circle}** Yes |
-| Ability to enable container scanning via an MR in the GitLab UI | **{check-circle}** Yes | **{check-circle}** Yes |
-| [UBI Image Support](#fips-enabled-images) | **{check-circle}** Yes | **{check-circle}** Yes |
-| Support for Trivy | **{check-circle}** Yes | **{check-circle}** Yes |
+| Customize Settings ([Variables](#available-cicd-variables), [Overriding](#overriding-the-container-scanning-template), [offline environment support](#running-container-scanning-in-an-offline-environment), etc) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [View JSON Report](#reports-json-format) as a CI job artifact | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Generate a [CycloneDX SBOM JSON report](#cyclonedx-software-bill-of-materials) as a CI job artifact | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Ability to enable container scanning via an MR in the GitLab UI | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [UBI Image Support](#fips-enabled-images) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Support for Trivy | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
| Inclusion of GitLab Advisory Database | Limited to the time-delayed content from GitLab [advisories-communities](https://gitlab.com/gitlab-org/advisories-community/) project | Yes - all the latest content from [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) |
-| Presentation of Report data in Merge Request and Security tab of the CI pipeline job | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Solutions for vulnerabilities (auto-remediation)](#solutions-for-vulnerabilities-auto-remediation) | **{dotted-circle}** No | **{check-circle}** Yes |
-| Support for the [vulnerability allow list](#vulnerability-allowlisting) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Access to Dependency List page](../dependency_list/_index.md) | **{dotted-circle}** No | **{check-circle}** Yes |
+| Presentation of Report data in Merge Request and Security tab of the CI pipeline job | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Solutions for vulnerabilities (auto-remediation)](#solutions-for-vulnerabilities-auto-remediation) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Support for the [vulnerability allow list](#vulnerability-allowlisting) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Access to Dependency List page](../dependency_list/_index.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
## Configuration
@@ -103,11 +113,14 @@ To enable the analyzer, either:
This method automatically prepares a merge request that includes the container scanning template
in the `.gitlab-ci.yml` file. You then merge the merge request to enable dependency scanning.
-NOTE:
+{{< alert type="note" >}}
+
This method works best with no existing `.gitlab-ci.yml` file, or with a minimal configuration file.
If you have a complex GitLab configuration file it might not be parsed successfully, and an error
might occur. In that case, use the [manual](#edit-the-gitlab-ciyml-file-manually) method instead.
+{{< /alert >}}
+
To enable Container Scanning:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -243,11 +256,14 @@ See [Use security scanning tools with merge request pipelines](../detect/roll_ou
To customize Container Scanning, use CI/CD variables. The following table lists CI/CD variables
specific to Container Scanning. You can also use any of the [predefined CI/CD variables](../../../ci/variables/predefined_variables.md).
-WARNING:
+{{< alert type="warning" >}}
+
Test customization of GitLab analyzers in a merge request before merging these changes to the
default branch. Failure to do so can give unexpected results, including a large number of false
positives.
+{{< /alert >}}
+
| CI/CD Variable | Default | Description |
| ------------------------------ | ------------- | ----------- |
| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. |
@@ -255,7 +271,7 @@ positives.
| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. |
| `CS_ANALYZER_IMAGE` | `registry.gitlab.com/security-products/container-scanning:7` | Docker image of the analyzer. Do not use the `:latest` tag with analyzer images provided by GitLab. |
| `CS_DEFAULT_BRANCH_IMAGE` | `""` | The name of the `CS_IMAGE` on the default branch. See [Setting the default branch image](#setting-the-default-branch-image) for more details. |
-| `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/439782)** in GitLab 17.0. |
+| `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | {{< icon name="warning" >}} **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/439782)** in GitLab 17.0. |
| `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. |
| `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. |
| `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. |
@@ -267,7 +283,7 @@ positives.
| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. |
| `CS_REGISTRY_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_gitlab.md#enable-fips-mode) is enabled. |
| `CS_REGISTRY_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_gitlab.md#enable-fips-mode) is enabled. |
-| `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, and `CRITICAL`. **{warning}** **[Default value changed to `MEDIUM`](https://gitlab.com/gitlab-org/gitlab/-/issues/439782)** in GitLab 17.8. |
+| `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, and `CRITICAL`. {{< icon name="warning" >}} **[Default value changed to `MEDIUM`](https://gitlab.com/gitlab-org/gitlab/-/issues/439782)** in GitLab 17.8. |
| `CS_TRIVY_JAVA_DB` | `"registry.gitlab.com/gitlab-org/security-products/dependencies/trivy-java-db"` | Specify an alternate location for the [trivy-java-db](https://github.com/aquasecurity/trivy-java-db) vulnerability database. |
| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. |
| `TRIVY_TIMEOUT` | `5m0s` | Set the timeout for the scan. |
@@ -305,9 +321,12 @@ versions of the container-scanning images. You can therefore replace standard im
images. To configure the images, set the `CS_IMAGE_SUFFIX` to `-fips` or modify the `CS_ANALYZER_IMAGE` variable to the
standard tag plus the `-fips` extension.
-NOTE:
+{{< alert type="note" >}}
+
The `-fips` flag is automatically added to `CS_ANALYZER_IMAGE` when FIPS mode is enabled in the GitLab instance.
+{{< /alert >}}
+
Container scanning of images in authenticated registries is not supported when [FIPS mode](../../../development/fips_gitlab.md#enable-fips-mode)
is enabled. When `CI_GITLAB_FIPS_MODE` is `"true"`, and `CS_REGISTRY_USER` or `CS_REGISTRY_PASSWORD` is set,
the analyzer exits with an error and does not perform the scan.
@@ -391,9 +410,12 @@ The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variab
### Vulnerability allowlisting
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To allowlist specific vulnerabilities, follow these steps:
@@ -445,9 +467,12 @@ This example excludes from `gl-container-scanning-report.json`:
- as full image name with registry hostname (such as `your.private.registry:5000/centos`).
- as full image name with registry hostname and sha256 label (such as `registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256`).
-NOTE:
+{{< alert type="note" >}}
+
The string after CVE ID (`cups` and `libxml2` in the previous example) is an optional comment format. It has **no impact** on the handling of vulnerabilities. You can include comments to describe the vulnerability.
+{{< /alert >}}
+
##### Container scanning job log format
You can verify the results of your scan and the correctness of your `vulnerability-allowlist.yml` file by looking
@@ -482,9 +507,12 @@ Vulnerabilities in the log are marked as `Approved` when the corresponding CVE I
### Running container scanning in an offline environment
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
For instances in an environment with limited, restricted, or intermittent access
to external resources through the internet, some adjustments are required for the container scanning job to
@@ -687,7 +715,11 @@ For more information, see [Security scanner integration](../../../development/in
### CycloneDX Software Bill of Materials
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396381) in GitLab 15.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396381) in GitLab 15.11.
+
+{{< /history >}}
In addition to the [JSON report file](#reports-json-format), the [Container Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) tool outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) for the scanned image. This CycloneDX SBOM is named `gl-sbom-report.cdx.json` and is saved in the same directory as the `JSON report file`. This feature is only supported when the `Trivy` analyzer is used.
@@ -697,13 +729,20 @@ You can download CycloneDX SBOMs [the same way as other job artifacts](../../../
## Container Scanning for Registry
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2340) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `enable_container_scanning_for_registry`. Disabled by default.
-> - [Enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/443827) in GitLab 17.2.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/443827) in GitLab 17.2. Feature flag `enable_container_scanning_for_registry` removed.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2340) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `enable_container_scanning_for_registry`. Disabled by default.
+- [Enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/443827) in GitLab 17.2.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/443827) in GitLab 17.2. Feature flag `enable_container_scanning_for_registry` removed.
+
+{{< /history >}}
When a container image is pushed with the `latest` tag, a container scanning job is automatically triggered by the security policy bot in a new pipeline against the default branch.
@@ -711,9 +750,12 @@ Unlike regular container scanning, the scan results do not include a security re
When security findings are identified, GitLab populates the [Vulnerability Report](../vulnerability_report/_index.md) with these findings. Vulnerabilities can be viewed under the **Container registry vulnerabilities** tab of the Vulnerability Report page.
-NOTE:
+{{< alert type="note" >}}
+
Container Scanning for Registry populates the Vulnerability Report only when a new advisory is published to the [GitLab Advisory Database](../gitlab_advisory_database/_index.md). Support for populating the Vulnerability Report with all present advisory data, instead of only newly-detected data, is proposed in [epic 8026](https://gitlab.com/groups/gitlab-org/-/epics/8026).
+{{< /alert >}}
+
### Prerequisites
- You must have at least the Maintainer role in a project to enable Container Scanning for Registry.
@@ -764,9 +806,12 @@ Database update information for other analyzers is available in the
## Solutions for vulnerabilities (auto-remediation)
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Some vulnerabilities can be fixed by applying the solution that GitLab
automatically generates.
diff --git a/doc/user/application_security/continuous_vulnerability_scanning/_index.md b/doc/user/application_security/continuous_vulnerability_scanning/_index.md
index 834127e055bfb74adb262d06820d48030f93018b..739fe2611820fbcfb643eae6f033d263f4ad3773 100644
--- a/doc/user/application_security/continuous_vulnerability_scanning/_index.md
+++ b/doc/user/application_security/continuous_vulnerability_scanning/_index.md
@@ -5,18 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Continuous Vulnerability Scanning
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-
-> - Continuous dependency scanning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371063) with [feature flags](../../../administration/feature_flags.md) `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_scans` enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/425753) in GitLab 16.10. Feature flags `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_scans` removed.
-> - Continuous container scanning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435435) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `container_scanning_continuous_vulnerability_scans`. Disabled by default.
-> - Continuous container scanning [enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/437162) in GitLab 16.10.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/443712) in GitLab 17.0. Feature flag `container_scanning_continuous_vulnerability_scans` removed.
-> - CVS triggering on new components, for container scanning and dependency scanning, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464575) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `dependency_scanning_using_sbom_reports`. Disabled by default.
-> - CVS triggering on new components, for container scanning, [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165368) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `cvs_for_container_scanning`. Disabled by default.
-> - CVS triggering on new components, for dependency scanning only, [enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/395692) in 17.5.
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Continuous dependency scanning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371063) with [feature flags](../../../administration/feature_flags.md) `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_scans` enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/425753) in GitLab 16.10. Feature flags `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_scans` removed.
+- Continuous container scanning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435435) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `container_scanning_continuous_vulnerability_scans`. Disabled by default.
+- Continuous container scanning [enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/437162) in GitLab 16.10.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/443712) in GitLab 17.0. Feature flag `container_scanning_continuous_vulnerability_scans` removed.
+- CVS triggering on new components, for container scanning and dependency scanning, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464575) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `dependency_scanning_using_sbom_reports`. Disabled by default.
+- CVS triggering on new components, for container scanning, [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165368) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `cvs_for_container_scanning`. Disabled by default.
+- CVS triggering on new components, for dependency scanning only, [enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/395692) in 17.5.
+
+{{< /history >}}
Continuous Vulnerability Scanning looks for security vulnerabilities in your project's dependencies by comparing their component names and versions against information in the latest [security advisories](#security-advisories).
diff --git a/doc/user/application_security/coverage_fuzzing/_index.md b/doc/user/application_security/coverage_fuzzing/_index.md
index 5c05d04ee8fbb54e7a2292a811900f4f31af78c3..c070d891826d9df2acdbe209a3da7955b6e57534 100644
--- a/doc/user/application_security/coverage_fuzzing/_index.md
+++ b/doc/user/application_security/coverage_fuzzing/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Coverage-guided fuzz testing
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Coverage-guided fuzz testing sends random inputs to an instrumented version of your application in
an effort to cause unexpected behavior. Such behavior indicates a bug that you should address.
@@ -121,11 +124,14 @@ job. If you include these keys in your own job, you must copy their original con
Use the following variables to configure coverage-guided fuzz testing in your CI/CD pipeline.
-WARNING:
+{{< alert type="warning" >}}
+
All customization of GitLab security scanning tools should be tested in a merge request before
merging these changes to the default branch. Failure to do so can give unexpected results, including
a large number of false positives.
+{{< /alert >}}
+
| CI/CD variable | Description |
|---------------------------|---------------------------------------------------------------------------------|
| `COVFUZZ_ADDITIONAL_ARGS` | Arguments passed to `gitlab-cov-fuzz`. Used to customize the behavior of the underlying fuzzing engine. Read the fuzzing engine's documentation for a complete list of arguments. |
diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md
index c67a0517f0650ee838ddcd22e73b7eff859b61f5..2ccb1e31ff3740d95379f5f24a55c848465a81ef 100644
--- a/doc/user/application_security/cve_id_request.md
+++ b/doc/user/application_security/cve_id_request.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: CVE ID request
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
For any public project, you can request a CVE identifier (ID).
diff --git a/doc/user/application_security/dast/_index.md b/doc/user/application_security/dast/_index.md
index b8c56f795a1bcf71bb6113d26eba853a71b24c7e..18fb89a8bcd5951079d50faa1391792a8cb0d506 100644
--- a/doc/user/application_security/dast/_index.md
+++ b/doc/user/application_security/dast/_index.md
@@ -5,11 +5,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dynamic Application Security Testing (DAST)
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The DAST proxy-based analyzer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966)
in GitLab 16.9 and [removed](https://gitlab.com/groups/gitlab-org/-/epics/11986) in GitLab 17.3.
This change is a breaking change. For instructions on how to migrate from the DAST proxy-based
@@ -18,6 +22,8 @@ analyzer to DAST version 5, see the
how to migrate from the DAST version 4 browser-based analyzer to DAST version 5, see the
[browser-based migration guide](browser_based_4_to_5_migration_guide.md).
+{{< /alert >}}
+
Dynamic Application Security Testing (DAST) runs automated penetration tests to find vulnerabilities
in your web applications and APIs as they are running. DAST automates a hacker's approach and
simulates real-world attacks for critical threats such as cross-site scripting (XSS), SQL injection
@@ -58,13 +64,16 @@ target branches.
Detected vulnerabilities appear in [merge requests](../detect/security_scan_results.md#merge-request), the [pipeline security tab](../vulnerability_report/pipeline.md),
and the [vulnerability report](../vulnerability_report/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job
fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For
example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST
results. On failure, the analyzer outputs an
[exit code](../../../development/integrations/secure.md#exit-code).
+{{< /alert >}}
+
### List URLs scanned
When DAST completes scanning, the merge request page states the number of URLs scanned.
diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md
index cbb96ca5904a0357e52c5ddb6eb74e19309e0305..d641aed01f7202542b4f23156f0f148b02faf686 100644
--- a/doc/user/application_security/dast/authentication.md
+++ b/doc/user/application_security/dast/authentication.md
@@ -1,15 +1,18 @@
---
+redirect_to: proxy_based_to_browser_based_migration_guide.md
+remove_date: "2025-02-15"
stage: Application Security Testing
group: Dynamic Analysis
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
-remove_date: '2025-02-15'
-redirect_to: 'proxy_based_to_browser_based_migration_guide.md'
title: DAST authentication (removed)
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966) in GitLab 16.9
and [removed](https://gitlab.com/groups/gitlab-org/-/epics/11986) in 17.3.
diff --git a/doc/user/application_security/dast/authentication_troubleshooting.md b/doc/user/application_security/dast/authentication_troubleshooting.md
index 16761a07f36423ddd6d861f76add8e0d6c507eee..3553fe88a54deb7a452253544925afe75d97dc38 100644
--- a/doc/user/application_security/dast/authentication_troubleshooting.md
+++ b/doc/user/application_security/dast/authentication_troubleshooting.md
@@ -1,15 +1,18 @@
---
+redirect_to: proxy_based_to_browser_based_migration_guide.md
+remove_date: "2025-02-15"
stage: Application Security Testing
group: Dynamic Analysis
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
-remove_date: '2025-02-15'
-redirect_to: 'proxy_based_to_browser_based_migration_guide.md'
title: Troubleshooting (removed)
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966) in GitLab 16.9
and [removed](https://gitlab.com/groups/gitlab-org/-/epics/11986) in 17.3.
diff --git a/doc/user/application_security/dast/browser/_index.md b/doc/user/application_security/dast/browser/_index.md
index 76b994aa90f89dda65ee2c07103fe6dcc33eafe2..71b71831b50eb29ce7983ada1fda8b47f48fddd9 100644
--- a/doc/user/application_security/dast/browser/_index.md
+++ b/doc/user/application_security/dast/browser/_index.md
@@ -1,21 +1,27 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: DAST browser-based analyzer
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/9023) in GitLab 15.7 (GitLab DAST v3.0.50).
-WARNING:
+{{< alert type="warning" >}}
+
The DAST version 4 browser-based analyzer is replaced by DAST version 5 in GitLab 17.0.
For instructions on how to migrate to DAST version 5, see the [migration guide](../browser_based_4_to_5_migration_guide.md).
+{{< /alert >}}
+
Browser-based DAST helps you identify security weaknesses (CWEs) in your web applications. After you
deploy your web application, it becomes exposed to new types of attacks, many of which cannot be
detected prior to deployment. For example, misconfigurations of your application server or incorrect
@@ -28,11 +34,14 @@ deployed environments.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Dynamic Application Security Testing (DAST)](https://www.youtube.com/watch?v=nbeDUoLZJTo).
-WARNING:
+{{< alert type="warning" >}}
+
Do not run DAST scans against a production server. Not only can it perform *any* function that a
user can, such as clicking buttons or submitting forms, but it may also trigger bugs, leading to
modification or loss of production data. Only run DAST scans against a test server.
+{{< /alert >}}
+
The DAST browser-based analyzer was built by GitLab to scan modern-day web applications for
vulnerabilities. Scans run in a browser to optimize testing applications heavily dependent on
JavaScript, such as single-page applications. See
diff --git a/doc/user/application_security/dast/browser/checks/1004.1.md b/doc/user/application_security/dast/browser/checks/1004.1.md
index aee164de984f3928432b2e1714058580eaa6b375..efdfbff48fe37d9666c0ecd66284c6c5d5d5823b 100644
--- a/doc/user/application_security/dast/browser/checks/1004.1.md
+++ b/doc/user/application_security/dast/browser/checks/1004.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Sensitive cookie without HttpOnly attribute'
+title: Sensitive cookie without HttpOnly attribute
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/113.1.md b/doc/user/application_security/dast/browser/checks/113.1.md
index 6c2c21463d0d1a6ff1ba4a1c06cd8f47c8596748..903f5c9210e6daf6af2917ca85f44a0e07c39f37 100644
--- a/doc/user/application_security/dast/browser/checks/113.1.md
+++ b/doc/user/application_security/dast/browser/checks/113.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Improper Neutralization of CRLF Sequences in HTTP Headers'
+title: Improper Neutralization of CRLF Sequences in HTTP Headers
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/1336.1.md b/doc/user/application_security/dast/browser/checks/1336.1.md
index 43bc2d4b76977d3d680031dca0268cd799659aa8..b453666069e4b343c2e8f7873ceff7cd2412e87c 100644
--- a/doc/user/application_security/dast/browser/checks/1336.1.md
+++ b/doc/user/application_security/dast/browser/checks/1336.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Server-Side Template Injection'
+title: Server-Side Template Injection
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.1.md b/doc/user/application_security/dast/browser/checks/16.1.md
index 148610ae235c733ebcbdf61769ed2970538a14ab..1e523ddc953abda1828313aa9e91d238d81741ac 100644
--- a/doc/user/application_security/dast/browser/checks/16.1.md
+++ b/doc/user/application_security/dast/browser/checks/16.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Missing Content-Type header'
+title: Missing Content-Type header
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.10.md b/doc/user/application_security/dast/browser/checks/16.10.md
index db4fde582a526615bfea0f2894688bc7af77a528..2bfd419246ad5b52b56194478943e9ec2a76cebc 100644
--- a/doc/user/application_security/dast/browser/checks/16.10.md
+++ b/doc/user/application_security/dast/browser/checks/16.10.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Content-Security-Policy violations'
+title: Content-Security-Policy violations
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.11.md b/doc/user/application_security/dast/browser/checks/16.11.md
index 310c14cdb7153471291914bf141fbf9304ebb94b..f135284759ce9c1fe0853edeca4d324b6655e0a8 100644
--- a/doc/user/application_security/dast/browser/checks/16.11.md
+++ b/doc/user/application_security/dast/browser/checks/16.11.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'TRACE HTTP method enabled'
+title: TRACE HTTP method enabled
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.2.md b/doc/user/application_security/dast/browser/checks/16.2.md
index abd11e2d1b088660b527b31a9923548cb2ba8096..f3ceff6b7e8e42eb1d7a5fa36e8fcf735d53fce9 100644
--- a/doc/user/application_security/dast/browser/checks/16.2.md
+++ b/doc/user/application_security/dast/browser/checks/16.2.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Server header exposes version information'
+title: Server header exposes version information
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.3.md b/doc/user/application_security/dast/browser/checks/16.3.md
index d0603ff1c2b16a6bc7c55d966bda19682c0d9457..e7e186bd27d44411dcb5bdbababdac5c27ae39b2 100644
--- a/doc/user/application_security/dast/browser/checks/16.3.md
+++ b/doc/user/application_security/dast/browser/checks/16.3.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'X-Powered-By header exposes version information'
+title: X-Powered-By header exposes version information
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.4.md b/doc/user/application_security/dast/browser/checks/16.4.md
index b6e26ed0058da6ef5ece94d92bc5701b4c1d86bd..94ac33fa5594bf9ac81ecd4ade275e0ff526f438 100644
--- a/doc/user/application_security/dast/browser/checks/16.4.md
+++ b/doc/user/application_security/dast/browser/checks/16.4.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'X-Backend-Server header exposes server information'
+title: X-Backend-Server header exposes server information
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.5.md b/doc/user/application_security/dast/browser/checks/16.5.md
index 2d81b39a2ddf2300e58c68d56dd6a337aa9fe7b2..ab94085f0a1b32357df2f58dc12621bafb75acca 100644
--- a/doc/user/application_security/dast/browser/checks/16.5.md
+++ b/doc/user/application_security/dast/browser/checks/16.5.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'AspNet header exposes version information'
+title: AspNet header exposes version information
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.6.md b/doc/user/application_security/dast/browser/checks/16.6.md
index 2815e3d998b7e9aace74604d1537504edef30921..d29457367e4f4a118cf6c03a5d64ff9b6eb9eb61 100644
--- a/doc/user/application_security/dast/browser/checks/16.6.md
+++ b/doc/user/application_security/dast/browser/checks/16.6.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'AspNetMvc header exposes version information'
+title: AspNetMvc header exposes version information
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.7.md b/doc/user/application_security/dast/browser/checks/16.7.md
index 253e965314250d5bb536aba75547d11d865c4dd5..a6caeb2f03389e79655c0575d5d69fae7e420a4e 100644
--- a/doc/user/application_security/dast/browser/checks/16.7.md
+++ b/doc/user/application_security/dast/browser/checks/16.7.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Strict-Transport-Security header missing or invalid'
+title: Strict-Transport-Security header missing or invalid
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.8.md b/doc/user/application_security/dast/browser/checks/16.8.md
index 0507d63a0c4b0f7e071e164efc76d4e7dda2e5eb..b696e588fd1f249449374cb5073fb766bd9d304f 100644
--- a/doc/user/application_security/dast/browser/checks/16.8.md
+++ b/doc/user/application_security/dast/browser/checks/16.8.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Content-Security-Policy analysis'
+title: Content-Security-Policy analysis
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/16.9.md b/doc/user/application_security/dast/browser/checks/16.9.md
index 418753057cc7d9a0139ad5719f2c2baeee5f6a71..944c4d139b7a677e17268a5239df850abc8d12ff 100644
--- a/doc/user/application_security/dast/browser/checks/16.9.md
+++ b/doc/user/application_security/dast/browser/checks/16.9.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Content-Security-Policy-Report-Only analysis'
+title: Content-Security-Policy-Report-Only analysis
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/200.1.md b/doc/user/application_security/dast/browser/checks/200.1.md
index 698d915c4b7928ba50ef67dba52d3b3690515c6f..841474312a418adf7e83b24d65c6c5a3ddc9f201 100644
--- a/doc/user/application_security/dast/browser/checks/200.1.md
+++ b/doc/user/application_security/dast/browser/checks/200.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of sensitive information to an unauthorized actor (private IP address)'
+title: Exposure of sensitive information to an unauthorized actor (private IP address)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/209.1.md b/doc/user/application_security/dast/browser/checks/209.1.md
index 4808b6553a4bb7f9ef2a0b834dd0d7be50b98062..8eb6143fff0eba1d360a84201449e69076e0d09b 100644
--- a/doc/user/application_security/dast/browser/checks/209.1.md
+++ b/doc/user/application_security/dast/browser/checks/209.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Generation of error message containing sensitive information'
+title: Generation of error message containing sensitive information
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/209.2.md b/doc/user/application_security/dast/browser/checks/209.2.md
index 1d7f5bb8342d1e7c319f9b2b69f7b21e357684bd..916d1fc6ff4671a89ebad806219a1a69b7fbc2a8 100644
--- a/doc/user/application_security/dast/browser/checks/209.2.md
+++ b/doc/user/application_security/dast/browser/checks/209.2.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Generation of database error message containing sensitive information'
+title: Generation of database error message containing sensitive information
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/22.1.md b/doc/user/application_security/dast/browser/checks/22.1.md
index 3e9997ec5e450ff65494bdc3159f68655e61bae2..4a9ca65c6cc05b0b8ecc02d43bde70ec6c0c964c 100644
--- a/doc/user/application_security/dast/browser/checks/22.1.md
+++ b/doc/user/application_security/dast/browser/checks/22.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Improper limitation of a pathname to a restricted directory (Path traversal)'
+title: Improper limitation of a pathname to a restricted directory (Path traversal)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/287.1.md b/doc/user/application_security/dast/browser/checks/287.1.md
index 73523731f146ee0bc1b5153151cde9775f94c46d..28c268bbf7c939099099f360e8e59232738aba04 100644
--- a/doc/user/application_security/dast/browser/checks/287.1.md
+++ b/doc/user/application_security/dast/browser/checks/287.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Insecure authentication over HTTP (Basic Authentication)'
+title: Insecure authentication over HTTP (Basic Authentication)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/287.2.md b/doc/user/application_security/dast/browser/checks/287.2.md
index 36e8157bca6ed4632543065716e17daa9d09e123..9bbd4a1601a4589e032420a9d09ef168cbcb12be 100644
--- a/doc/user/application_security/dast/browser/checks/287.2.md
+++ b/doc/user/application_security/dast/browser/checks/287.2.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Insecure authentication over HTTP (Digest Authentication)'
+title: Insecure authentication over HTTP (Digest Authentication)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/319.1.md b/doc/user/application_security/dast/browser/checks/319.1.md
index a8c644ccd8eab967be241966280cb3c68964664a..646f1bbb7fdf5a21367c4ed06cdb320abf7e17af 100644
--- a/doc/user/application_security/dast/browser/checks/319.1.md
+++ b/doc/user/application_security/dast/browser/checks/319.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Mixed Content'
+title: Mixed Content
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/352.1.md b/doc/user/application_security/dast/browser/checks/352.1.md
index 5dd5049e93a364b8edfa95d555f45906f9a64d5a..e435f3ae673cd54be4fc5a0bfe04c6e043ffc0db 100644
--- a/doc/user/application_security/dast/browser/checks/352.1.md
+++ b/doc/user/application_security/dast/browser/checks/352.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Absence of anti-CSRF tokens'
+title: Absence of anti-CSRF tokens
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/359.1.md b/doc/user/application_security/dast/browser/checks/359.1.md
index b0e492ad16dc77eae6014b79ea438bc51fcc600c..27205f1f911b82f4aa8ff784c1af0614e8a8fe6d 100644
--- a/doc/user/application_security/dast/browser/checks/359.1.md
+++ b/doc/user/application_security/dast/browser/checks/359.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of Private Personal Information (PII) to an unauthorized actor (credit card)'
+title: Exposure of Private Personal Information (PII) to an unauthorized actor (credit card)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/359.2.md b/doc/user/application_security/dast/browser/checks/359.2.md
index 919ff18b7052df01a33eade4b7183127c4c58b44..ffb38aa2bc1a3f38709ba5b76abfab5dfcf38f64 100644
--- a/doc/user/application_security/dast/browser/checks/359.2.md
+++ b/doc/user/application_security/dast/browser/checks/359.2.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of Private Personal Information (PII) to an unauthorized actor (United States social security number)'
+title: Exposure of Private Personal Information (PII) to an unauthorized actor (United States social security number)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/548.1.md b/doc/user/application_security/dast/browser/checks/548.1.md
index a14e5b259298adabdb57c40a6751862781e8c7ff..0ce360d09e1ef8289e3b46f4a9f4b821d1d95f6d 100644
--- a/doc/user/application_security/dast/browser/checks/548.1.md
+++ b/doc/user/application_security/dast/browser/checks/548.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of information through directory listing'
+title: Exposure of information through directory listing
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/598.1.md b/doc/user/application_security/dast/browser/checks/598.1.md
index f3b759f330c4052f647da9261586f55bf55d063c..d65f74938fa2e2056b1ab1d813364e2f9b0b59bd 100644
--- a/doc/user/application_security/dast/browser/checks/598.1.md
+++ b/doc/user/application_security/dast/browser/checks/598.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Use of GET request method with sensitive query strings (session ID)'
+title: Use of GET request method with sensitive query strings (session ID)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/598.2.md b/doc/user/application_security/dast/browser/checks/598.2.md
index e6d484eaa23804f65a8a4e6afd8f8a718bd1c80d..f5c2402e74e78c26ea45369efc26dcacba6df170 100644
--- a/doc/user/application_security/dast/browser/checks/598.2.md
+++ b/doc/user/application_security/dast/browser/checks/598.2.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Use of GET request method with sensitive query strings (password)'
+title: Use of GET request method with sensitive query strings (password)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/598.3.md b/doc/user/application_security/dast/browser/checks/598.3.md
index 4d85b73e6f857eec96c7b78440f74f52e52dca93..5abc976fbfc178ed69349b4aa08fb612d27939fc 100644
--- a/doc/user/application_security/dast/browser/checks/598.3.md
+++ b/doc/user/application_security/dast/browser/checks/598.3.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Use of GET request method with sensitive query strings (Authorization header details)'
+title: Use of GET request method with sensitive query strings (Authorization header details)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/601.1.md b/doc/user/application_security/dast/browser/checks/601.1.md
index 91b54b80d2e5b52d99e12c20b3ea3cbb33c3f134..c4baf329958ef16ab64c062dc602efd4975081c9 100644
--- a/doc/user/application_security/dast/browser/checks/601.1.md
+++ b/doc/user/application_security/dast/browser/checks/601.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'URL redirection to untrusted site (open redirect)'
+title: URL redirection to untrusted site (open redirect)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/611.1.md b/doc/user/application_security/dast/browser/checks/611.1.md
index 68d8b053039eb42e6b0742dec65626f5dc7f8559..7447a0d052f5ac09e5253f19b7bc78859b97ade1 100644
--- a/doc/user/application_security/dast/browser/checks/611.1.md
+++ b/doc/user/application_security/dast/browser/checks/611.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'External XML Entity Injection (XXE)'
+title: External XML Entity Injection (XXE)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/614.1.md b/doc/user/application_security/dast/browser/checks/614.1.md
index 14a6a47b1290e725822b2b343372f59b88734a46..1013893bff1543d075b91d165ac3e937b73ab2ed 100644
--- a/doc/user/application_security/dast/browser/checks/614.1.md
+++ b/doc/user/application_security/dast/browser/checks/614.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Sensitive cookie without Secure attribute'
+title: Sensitive cookie without Secure attribute
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/74.1.md b/doc/user/application_security/dast/browser/checks/74.1.md
index 39fc55e9787922dcb3e3ac059f4cdba955e3de96..ca9c24e91d7e69fbbd0f98bc1a0de6df5aa1bb40 100644
--- a/doc/user/application_security/dast/browser/checks/74.1.md
+++ b/doc/user/application_security/dast/browser/checks/74.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'XSLT Injection'
+title: XSLT Injection
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/78.1.md b/doc/user/application_security/dast/browser/checks/78.1.md
index 5973897532686aa5a4f0c0360c968d348f57301d..198acdda34785d64928fc58f64e2b103e029e9f3 100644
--- a/doc/user/application_security/dast/browser/checks/78.1.md
+++ b/doc/user/application_security/dast/browser/checks/78.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'OS Command Injection'
+title: OS Command Injection
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.1.md b/doc/user/application_security/dast/browser/checks/798.1.md
index 1b9880bbf5884db328a6429c6a12be662f82e636..78e7cce9f69508e749aaa54ff0d1f343e956423f 100644
--- a/doc/user/application_security/dast/browser/checks/798.1.md
+++ b/doc/user/application_security/dast/browser/checks/798.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Adafruit API Key'
+title: Exposure of confidential secret or token Adafruit API Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.10.md b/doc/user/application_security/dast/browser/checks/798.10.md
index 17dfa24fcef26b14c29692a8b00185af3b9ff6c6..24740b92650c0e2cab2ea6827ffd70400bb47768 100644
--- a/doc/user/application_security/dast/browser/checks/798.10.md
+++ b/doc/user/application_security/dast/browser/checks/798.10.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Asana Client Secret'
+title: Exposure of confidential secret or token Asana Client Secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.100.md b/doc/user/application_security/dast/browser/checks/798.100.md
index e70135027d500d3695f4a2a08704f489abecab6f..60bd142d18d40e988b2d7d7bd093d406416e9490 100644
--- a/doc/user/application_security/dast/browser/checks/798.100.md
+++ b/doc/user/application_security/dast/browser/checks/798.100.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Sendbird Access Token'
+title: Exposure of confidential secret or token Sendbird Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.101.md b/doc/user/application_security/dast/browser/checks/798.101.md
index aa9f37d7a6bf91025615ed01b49379b6e29cd2cc..1bb36b264c89641db6f0b6b0d761fe3fdf3065fb 100644
--- a/doc/user/application_security/dast/browser/checks/798.101.md
+++ b/doc/user/application_security/dast/browser/checks/798.101.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token SendGrid API token'
+title: Exposure of confidential secret or token SendGrid API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.102.md b/doc/user/application_security/dast/browser/checks/798.102.md
index 13f65ce1e404d9b949ba92fb4bae32712f24b4b4..3fbb8ef3ebd1c077854ef181a774c28f2c6b47ca 100644
--- a/doc/user/application_security/dast/browser/checks/798.102.md
+++ b/doc/user/application_security/dast/browser/checks/798.102.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Sendinblue API token'
+title: Exposure of confidential secret or token Sendinblue API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.103.md b/doc/user/application_security/dast/browser/checks/798.103.md
index 2b1c1d0defb88daf17921036cb4830f51b1ce2f3..f959b6958919f8d0aafcdbcf72b6d872657d8ac3 100644
--- a/doc/user/application_security/dast/browser/checks/798.103.md
+++ b/doc/user/application_security/dast/browser/checks/798.103.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Sentry Access Token'
+title: Exposure of confidential secret or token Sentry Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.104.md b/doc/user/application_security/dast/browser/checks/798.104.md
index f0832d87cf27d0112ba7ac71c3ae3a7277cd87f2..e194473db58eb1efc03fd76698e0670758d94e8b 100644
--- a/doc/user/application_security/dast/browser/checks/798.104.md
+++ b/doc/user/application_security/dast/browser/checks/798.104.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Shippo API token'
+title: Exposure of confidential secret or token Shippo API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.105.md b/doc/user/application_security/dast/browser/checks/798.105.md
index de76e0dd0fbfa3278332e8529db982acf96ba7ae..e5cfd406820d78968f11aa9d666385c34ec9a526 100644
--- a/doc/user/application_security/dast/browser/checks/798.105.md
+++ b/doc/user/application_security/dast/browser/checks/798.105.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Shopify access token'
+title: Exposure of confidential secret or token Shopify access token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.106.md b/doc/user/application_security/dast/browser/checks/798.106.md
index 28d1777382915971f37994c1591f34d6a19deda4..d499c2bf426109791bf98393cbe75ec484b3ac4e 100644
--- a/doc/user/application_security/dast/browser/checks/798.106.md
+++ b/doc/user/application_security/dast/browser/checks/798.106.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Shopify custom access token'
+title: Exposure of confidential secret or token Shopify custom access token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.107.md b/doc/user/application_security/dast/browser/checks/798.107.md
index 37ce9ac51e3a269bca9375f82f40fcd73e29304b..97281351aeb06d20d1ef0af8f08d684f3456f3c7 100644
--- a/doc/user/application_security/dast/browser/checks/798.107.md
+++ b/doc/user/application_security/dast/browser/checks/798.107.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Shopify private app access token'
+title: Exposure of confidential secret or token Shopify private app access token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.108.md b/doc/user/application_security/dast/browser/checks/798.108.md
index 486f27d844ff74762adb6c1d0218df1c53a5eb3c..0133b44fb8a0f2a6f144aaf9db1af8b7c1b3c0a8 100644
--- a/doc/user/application_security/dast/browser/checks/798.108.md
+++ b/doc/user/application_security/dast/browser/checks/798.108.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Shopify shared secret'
+title: Exposure of confidential secret or token Shopify shared secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.109.md b/doc/user/application_security/dast/browser/checks/798.109.md
index bc184f1a7626c6a0fa1846fde8bda15ab946f5b1..b8d8dc30f50be18d6c13d2bcdfe0a30198e00a85 100644
--- a/doc/user/application_security/dast/browser/checks/798.109.md
+++ b/doc/user/application_security/dast/browser/checks/798.109.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Slack token'
+title: Exposure of confidential secret or token Slack token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.11.md b/doc/user/application_security/dast/browser/checks/798.11.md
index 08bf4d3c17357af65e2f6e0b1e1c5556cb062f4d..e41ececd16032e09b2932b3cf32f7ac3282d337f 100644
--- a/doc/user/application_security/dast/browser/checks/798.11.md
+++ b/doc/user/application_security/dast/browser/checks/798.11.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Atlassian API token'
+title: Exposure of confidential secret or token Atlassian API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.110.md b/doc/user/application_security/dast/browser/checks/798.110.md
index 53719b54a287b58204ecb3e82a1f2ce2c112e69b..c5dd050aaee21cdb3686c05a3c1b736399442203 100644
--- a/doc/user/application_security/dast/browser/checks/798.110.md
+++ b/doc/user/application_security/dast/browser/checks/798.110.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Slack Webhook'
+title: Exposure of confidential secret or token Slack Webhook
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.111.md b/doc/user/application_security/dast/browser/checks/798.111.md
index 83bc5ae56524eb65089bb207d15bec0b18c363d0..16453ef26af67dc6de6b0c3f9b2eab3a562e6cca 100644
--- a/doc/user/application_security/dast/browser/checks/798.111.md
+++ b/doc/user/application_security/dast/browser/checks/798.111.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Stripe'
+title: Exposure of confidential secret or token Stripe
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.112.md b/doc/user/application_security/dast/browser/checks/798.112.md
index 29c30bc41d623f62bfbc845f0c7832cb6d69bd50..00498f2d1fc74dcf92f34ad6ffa2f4bf084abf65 100644
--- a/doc/user/application_security/dast/browser/checks/798.112.md
+++ b/doc/user/application_security/dast/browser/checks/798.112.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Square Access Token'
+title: Exposure of confidential secret or token Square Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.113.md b/doc/user/application_security/dast/browser/checks/798.113.md
index dacf59c3785774555d64925aa33648f9e418cd20..3c67655891a1cbab53a7bb976ef0dfe7c781d929 100644
--- a/doc/user/application_security/dast/browser/checks/798.113.md
+++ b/doc/user/application_security/dast/browser/checks/798.113.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Squarespace Access Token'
+title: Exposure of confidential secret or token Squarespace Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.114.md b/doc/user/application_security/dast/browser/checks/798.114.md
index c15770a192a61defd3d96c3da13cdfec15a4df43..87eddcce4919325e0bf6e9aabe1b8256f2d2b432 100644
--- a/doc/user/application_security/dast/browser/checks/798.114.md
+++ b/doc/user/application_security/dast/browser/checks/798.114.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token SumoLogic Access ID'
+title: Exposure of confidential secret or token SumoLogic Access ID
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.115.md b/doc/user/application_security/dast/browser/checks/798.115.md
index 33c2359789341de0088419656c4ef526db2d6696..8a824207693ea2855890384d43cde13fedfbb98f 100644
--- a/doc/user/application_security/dast/browser/checks/798.115.md
+++ b/doc/user/application_security/dast/browser/checks/798.115.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token SumoLogic Access Token'
+title: Exposure of confidential secret or token SumoLogic Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.116.md b/doc/user/application_security/dast/browser/checks/798.116.md
index 6145939a488a34067e6ebace4da759bde870fcd8..7be10b9eefb54cbfbcba7e45d7f704a2d35ad7bf 100644
--- a/doc/user/application_security/dast/browser/checks/798.116.md
+++ b/doc/user/application_security/dast/browser/checks/798.116.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Travis CI Access Token'
+title: Exposure of confidential secret or token Travis CI Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.117.md b/doc/user/application_security/dast/browser/checks/798.117.md
index 4287bcacf9cab910966b83235b4c0cd1685827d4..715c38ab0668e8d8ec2864827a20e5e7a2c39373 100644
--- a/doc/user/application_security/dast/browser/checks/798.117.md
+++ b/doc/user/application_security/dast/browser/checks/798.117.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Twilio API Key'
+title: Exposure of confidential secret or token Twilio API Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.118.md b/doc/user/application_security/dast/browser/checks/798.118.md
index 8abddeeddb9f3b5274aa4a945a2ef79a04175ecc..4b4a0f393dab2b14a63dc7233e777cda45a85caf 100644
--- a/doc/user/application_security/dast/browser/checks/798.118.md
+++ b/doc/user/application_security/dast/browser/checks/798.118.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Twitch API token'
+title: Exposure of confidential secret or token Twitch API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.119.md b/doc/user/application_security/dast/browser/checks/798.119.md
index f0714bbb7ff404200bc5e5371ac73fea130475d7..e4e814999f7a42f72b09d43d5e291da76989851c 100644
--- a/doc/user/application_security/dast/browser/checks/798.119.md
+++ b/doc/user/application_security/dast/browser/checks/798.119.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Twitter API Key'
+title: Exposure of confidential secret or token Twitter API Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.12.md b/doc/user/application_security/dast/browser/checks/798.12.md
index ecf02412bf2960b9c098256327543097f4e68df6..f62bfb3b285586850cf7e22550b975a4d9c20369 100644
--- a/doc/user/application_security/dast/browser/checks/798.12.md
+++ b/doc/user/application_security/dast/browser/checks/798.12.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token AWS'
+title: Exposure of confidential secret or token AWS
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.120.md b/doc/user/application_security/dast/browser/checks/798.120.md
index b48bcfbe92dbe46c43236a136c035280002c3a82..95dbd2a765ed003573092c686510d33eaedbbf11 100644
--- a/doc/user/application_security/dast/browser/checks/798.120.md
+++ b/doc/user/application_security/dast/browser/checks/798.120.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Twitter API Secret'
+title: Exposure of confidential secret or token Twitter API Secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.121.md b/doc/user/application_security/dast/browser/checks/798.121.md
index 4a91d41b7085d91ea32290596bf46fbe406719c4..fbb2cf019440a42abed0da1868a4a44af4e1dd8e 100644
--- a/doc/user/application_security/dast/browser/checks/798.121.md
+++ b/doc/user/application_security/dast/browser/checks/798.121.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Twitter Access Token'
+title: Exposure of confidential secret or token Twitter Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.122.md b/doc/user/application_security/dast/browser/checks/798.122.md
index b7ff78c8268ea16dc59963f9fb3dc981865f18ee..c0ebacdc504410bcfc4261ba8ca8dc45bfb3edab 100644
--- a/doc/user/application_security/dast/browser/checks/798.122.md
+++ b/doc/user/application_security/dast/browser/checks/798.122.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Twitter Access Secret'
+title: Exposure of confidential secret or token Twitter Access Secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.123.md b/doc/user/application_security/dast/browser/checks/798.123.md
index d0f8634c8928fefa6b82e8fb1d042457adc04638..469b5cfb6163553b2f843a23f7d624a366e7b433 100644
--- a/doc/user/application_security/dast/browser/checks/798.123.md
+++ b/doc/user/application_security/dast/browser/checks/798.123.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Twitter Bearer Token'
+title: Exposure of confidential secret or token Twitter Bearer Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.124.md b/doc/user/application_security/dast/browser/checks/798.124.md
index a20e20531202587662c2f06528aadd53624e03c5..7e60bf1375c579d7ffbb1126618f05a87299812e 100644
--- a/doc/user/application_security/dast/browser/checks/798.124.md
+++ b/doc/user/application_security/dast/browser/checks/798.124.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Typeform API token'
+title: Exposure of confidential secret or token Typeform API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.125.md b/doc/user/application_security/dast/browser/checks/798.125.md
index 28cc9a8d571c997c8a8a56e787e09dea6938229a..54f738cbc82c4e4790134fb8cd2e37ebf8aa1f41 100644
--- a/doc/user/application_security/dast/browser/checks/798.125.md
+++ b/doc/user/application_security/dast/browser/checks/798.125.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Yandex API Key'
+title: Exposure of confidential secret or token Yandex API Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.126.md b/doc/user/application_security/dast/browser/checks/798.126.md
index 4359be95a6adabeeb353d4ac0fcc14b2c9184f0c..3e494e83969c6cc976956ef81fa832fd3d34529b 100644
--- a/doc/user/application_security/dast/browser/checks/798.126.md
+++ b/doc/user/application_security/dast/browser/checks/798.126.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Yandex AWS Access Token'
+title: Exposure of confidential secret or token Yandex AWS Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.127.md b/doc/user/application_security/dast/browser/checks/798.127.md
index d7086e3c343ed33c7ba0045d2892c2f9d72f73a2..b85c6794a456d2d4a74eff2f082c4f51ab4337b6 100644
--- a/doc/user/application_security/dast/browser/checks/798.127.md
+++ b/doc/user/application_security/dast/browser/checks/798.127.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Yandex Access Token'
+title: Exposure of confidential secret or token Yandex Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.128.md b/doc/user/application_security/dast/browser/checks/798.128.md
index f45d49e486e0b9d8b37d13a7e469837274883c4c..6256b140ae500aa20ab02bde6e31e52f7de0ee4c 100644
--- a/doc/user/application_security/dast/browser/checks/798.128.md
+++ b/doc/user/application_security/dast/browser/checks/798.128.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Zendesk Secret Key'
+title: Exposure of confidential secret or token Zendesk Secret Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.13.md b/doc/user/application_security/dast/browser/checks/798.13.md
index 74908117da7f11f853a6ea35c7d4e25c3644dfc7..cad2e05ba1217e93f0d9ef8265ea0cea3085d297 100644
--- a/doc/user/application_security/dast/browser/checks/798.13.md
+++ b/doc/user/application_security/dast/browser/checks/798.13.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Bitbucket Client ID'
+title: Exposure of confidential secret or token Bitbucket Client ID
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.14.md b/doc/user/application_security/dast/browser/checks/798.14.md
index 87e042a50c5a61f4b7b8095c8af16e3ed642aabe..b10db5033120f3f7bc34ba0a924276207cba4442 100644
--- a/doc/user/application_security/dast/browser/checks/798.14.md
+++ b/doc/user/application_security/dast/browser/checks/798.14.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Bitbucket Client Secret'
+title: Exposure of confidential secret or token Bitbucket Client Secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.15.md b/doc/user/application_security/dast/browser/checks/798.15.md
index 624bb179c70d372c382843db708f2a46d2c0a13d..db5af75128e0021ece50aa6e93592f34a8ab36c3 100644
--- a/doc/user/application_security/dast/browser/checks/798.15.md
+++ b/doc/user/application_security/dast/browser/checks/798.15.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Bittrex Access Key'
+title: Exposure of confidential secret or token Bittrex Access Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.16.md b/doc/user/application_security/dast/browser/checks/798.16.md
index 18f59ffe20f29dc3aea241ecc1574309be22541d..0c992419c311ae2ab2236cffadbe78102122ebea 100644
--- a/doc/user/application_security/dast/browser/checks/798.16.md
+++ b/doc/user/application_security/dast/browser/checks/798.16.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Bittrex Secret Key'
+title: Exposure of confidential secret or token Bittrex Secret Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.17.md b/doc/user/application_security/dast/browser/checks/798.17.md
index 468f3173ecd6ddfd4ea316fa0ad566edc6705e4d..a63576f34afd9ed4de9ad7ff03efc4399dd0190b 100644
--- a/doc/user/application_security/dast/browser/checks/798.17.md
+++ b/doc/user/application_security/dast/browser/checks/798.17.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Beamer API token'
+title: Exposure of confidential secret or token Beamer API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.18.md b/doc/user/application_security/dast/browser/checks/798.18.md
index be48088ac4b54d7178281edba8e6fe7681ed8591..ed0402a4ad56ae986fa436488f6751ab9dabf473 100644
--- a/doc/user/application_security/dast/browser/checks/798.18.md
+++ b/doc/user/application_security/dast/browser/checks/798.18.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Codecov Access Token'
+title: Exposure of confidential secret or token Codecov Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.19.md b/doc/user/application_security/dast/browser/checks/798.19.md
index 93a29789066e7f7a5f07ad9b7a66945e8a98b2b9..c7de945aeaeb8c776d22a370f6a82a5d4f4b040c 100644
--- a/doc/user/application_security/dast/browser/checks/798.19.md
+++ b/doc/user/application_security/dast/browser/checks/798.19.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Coinbase Access Token'
+title: Exposure of confidential secret or token Coinbase Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.2.md b/doc/user/application_security/dast/browser/checks/798.2.md
index 7bedd74bf352bb470db79da8e35c839ffaf11991..a4745e7b852395fd9d315cd84793499528d88081 100644
--- a/doc/user/application_security/dast/browser/checks/798.2.md
+++ b/doc/user/application_security/dast/browser/checks/798.2.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Adobe Client ID (OAuth Web)'
+title: Exposure of confidential secret or token Adobe Client ID (OAuth Web)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.20.md b/doc/user/application_security/dast/browser/checks/798.20.md
index 92ffa5744fb738a527f6d98ea8761a996a491213..b46f76080a10761e45540449d10c298c5c51e7f6 100644
--- a/doc/user/application_security/dast/browser/checks/798.20.md
+++ b/doc/user/application_security/dast/browser/checks/798.20.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Clojars API token'
+title: Exposure of confidential secret or token Clojars API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.21.md b/doc/user/application_security/dast/browser/checks/798.21.md
index c1fd3a7828636feb1dd65a3fc344f7e2ecfa850b..5914b1a32eb23ca7613d6e81bed56cfacde5421d 100644
--- a/doc/user/application_security/dast/browser/checks/798.21.md
+++ b/doc/user/application_security/dast/browser/checks/798.21.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Confluent Access Token'
+title: Exposure of confidential secret or token Confluent Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.22.md b/doc/user/application_security/dast/browser/checks/798.22.md
index 23c308bac726e7f24e82af040f8de6e7a60dab76..0a4e5ed056006c0a8fdd1179aaf03535acedc3a5 100644
--- a/doc/user/application_security/dast/browser/checks/798.22.md
+++ b/doc/user/application_security/dast/browser/checks/798.22.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Confluent Secret Key'
+title: Exposure of confidential secret or token Confluent Secret Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.23.md b/doc/user/application_security/dast/browser/checks/798.23.md
index 71ab8ca57cc4e9e229dd09a559803ca50b8f5eb2..cdb8319f0d1a788fe5ad5f63830784248e22befd 100644
--- a/doc/user/application_security/dast/browser/checks/798.23.md
+++ b/doc/user/application_security/dast/browser/checks/798.23.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Contentful delivery API token'
+title: Exposure of confidential secret or token Contentful delivery API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.24.md b/doc/user/application_security/dast/browser/checks/798.24.md
index 393383a018d409fe7ef0d60c1bded1a9e9c5a90b..bac9205d1d75725824573f7cbf5385b8aba9645c 100644
--- a/doc/user/application_security/dast/browser/checks/798.24.md
+++ b/doc/user/application_security/dast/browser/checks/798.24.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Databricks API token'
+title: Exposure of confidential secret or token Databricks API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.25.md b/doc/user/application_security/dast/browser/checks/798.25.md
index dcb14af94e0af9bf88abe7333bcd16a2537c86a1..00a470c5764ee1cd86e4b61d6939e76ae3c0cb1d 100644
--- a/doc/user/application_security/dast/browser/checks/798.25.md
+++ b/doc/user/application_security/dast/browser/checks/798.25.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Datadog Access Token'
+title: Exposure of confidential secret or token Datadog Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.26.md b/doc/user/application_security/dast/browser/checks/798.26.md
index bf53110218b2ef73560ddcec5c1269b03e954315..dda6977f6b0e062472a72f18940ebca8622df2ee 100644
--- a/doc/user/application_security/dast/browser/checks/798.26.md
+++ b/doc/user/application_security/dast/browser/checks/798.26.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Discord API key'
+title: Exposure of confidential secret or token Discord API key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.27.md b/doc/user/application_security/dast/browser/checks/798.27.md
index 211e8a6b68622e130c910ca28b8ae3dd6b200100..31c580970238f338b975a5bcbb36a401dbbcaf1c 100644
--- a/doc/user/application_security/dast/browser/checks/798.27.md
+++ b/doc/user/application_security/dast/browser/checks/798.27.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Discord client ID'
+title: Exposure of confidential secret or token Discord client ID
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.28.md b/doc/user/application_security/dast/browser/checks/798.28.md
index ea6a344a0e596bd95b5304cff7cfbc5a1fd47a74..8799a30abce3748b18811f2834c8124cfe94c1c1 100644
--- a/doc/user/application_security/dast/browser/checks/798.28.md
+++ b/doc/user/application_security/dast/browser/checks/798.28.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Discord client secret'
+title: Exposure of confidential secret or token Discord client secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.29.md b/doc/user/application_security/dast/browser/checks/798.29.md
index c07dd3432c4bffa2456427325b1a60708763400d..5a83a6a8c55efb7b14f0cd257d138b4afa3ffaa6 100644
--- a/doc/user/application_security/dast/browser/checks/798.29.md
+++ b/doc/user/application_security/dast/browser/checks/798.29.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Doppler API token'
+title: Exposure of confidential secret or token Doppler API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.3.md b/doc/user/application_security/dast/browser/checks/798.3.md
index a41c07c61a27301704c6de49701e75fb3b0a6faf..01b4c53f0a11ceb9edbee8db81152cb5a64f2610 100644
--- a/doc/user/application_security/dast/browser/checks/798.3.md
+++ b/doc/user/application_security/dast/browser/checks/798.3.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Adobe Client Secret'
+title: Exposure of confidential secret or token Adobe Client Secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.30.md b/doc/user/application_security/dast/browser/checks/798.30.md
index 3df4d2aae0b16862a19509b3f1131c298673c92f..767421c2b5639e7a5e30b1d60778a02aa30f091d 100644
--- a/doc/user/application_security/dast/browser/checks/798.30.md
+++ b/doc/user/application_security/dast/browser/checks/798.30.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Dropbox API secret'
+title: Exposure of confidential secret or token Dropbox API secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.31.md b/doc/user/application_security/dast/browser/checks/798.31.md
index 4a35e494e5f5ad0ce1c920b902d5e501a94be16d..1054526f8d2ccfc2f61395dcc8a20da85bc76348 100644
--- a/doc/user/application_security/dast/browser/checks/798.31.md
+++ b/doc/user/application_security/dast/browser/checks/798.31.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Dropbox long lived API token'
+title: Exposure of confidential secret or token Dropbox long lived API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.32.md b/doc/user/application_security/dast/browser/checks/798.32.md
index b6364dca16a933c7cd7609c2e23da1a2fb9a39cb..6b5d2674cf6c8489ffd6502ebcb06b0f320a470c 100644
--- a/doc/user/application_security/dast/browser/checks/798.32.md
+++ b/doc/user/application_security/dast/browser/checks/798.32.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Dropbox short lived API token'
+title: Exposure of confidential secret or token Dropbox short lived API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.33.md b/doc/user/application_security/dast/browser/checks/798.33.md
index 4c2eb4c8b537169ffdb499a964ca8780fac8725c..ee4c006ca9803a66ed8c3fd6a7be59bead50b239 100644
--- a/doc/user/application_security/dast/browser/checks/798.33.md
+++ b/doc/user/application_security/dast/browser/checks/798.33.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Drone CI Access Token'
+title: Exposure of confidential secret or token Drone CI Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.34.md b/doc/user/application_security/dast/browser/checks/798.34.md
index d2557f3066c58bf5e7edebd58dbc1c70ca746f95..9eb60056e3297b56c8fe5735c31e29ec765545fa 100644
--- a/doc/user/application_security/dast/browser/checks/798.34.md
+++ b/doc/user/application_security/dast/browser/checks/798.34.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Duffel API token'
+title: Exposure of confidential secret or token Duffel API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.35.md b/doc/user/application_security/dast/browser/checks/798.35.md
index f9739fdcc36755bea7f49a365c103ae964141941..431bd3ab37d2bbe44c8b4f6a1a215ef241262cb6 100644
--- a/doc/user/application_security/dast/browser/checks/798.35.md
+++ b/doc/user/application_security/dast/browser/checks/798.35.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Dynatrace API token'
+title: Exposure of confidential secret or token Dynatrace API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.36.md b/doc/user/application_security/dast/browser/checks/798.36.md
index cdd04db0a8e0c6a478a43216960f554cd72b18aa..056cdfa1c45bbd6b3c9b170c0f798a15aab871ff 100644
--- a/doc/user/application_security/dast/browser/checks/798.36.md
+++ b/doc/user/application_security/dast/browser/checks/798.36.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token EasyPost API token'
+title: Exposure of confidential secret or token EasyPost API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.37.md b/doc/user/application_security/dast/browser/checks/798.37.md
index a3ea9ae05f210065c408c1ce37febb19816d1702..80bf824c36cecfc96200c56c0d638e016ab40ab4 100644
--- a/doc/user/application_security/dast/browser/checks/798.37.md
+++ b/doc/user/application_security/dast/browser/checks/798.37.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token EasyPost test API token'
+title: Exposure of confidential secret or token EasyPost test API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.38.md b/doc/user/application_security/dast/browser/checks/798.38.md
index 50227bccd12853b89f7c16a4207a4a3a6f9b40e2..f0798ddfebe5cae934d42726aaea2a81eaefdbd6 100644
--- a/doc/user/application_security/dast/browser/checks/798.38.md
+++ b/doc/user/application_security/dast/browser/checks/798.38.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Etsy Access Token'
+title: Exposure of confidential secret or token Etsy Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.39.md b/doc/user/application_security/dast/browser/checks/798.39.md
index fe94d8c347996bd63349da1923cda00a10558c0b..f37639c6d09115dc5c91e3dd2a2729ac86c59510 100644
--- a/doc/user/application_security/dast/browser/checks/798.39.md
+++ b/doc/user/application_security/dast/browser/checks/798.39.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Facebook'
+title: Exposure of confidential secret or token Facebook
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.4.md b/doc/user/application_security/dast/browser/checks/798.4.md
index ed50e01c7803644bcf2be51bb86830bcd0f29652..4215f91b9b9f9f5d251ef43a0e1c8d73ea416d39 100644
--- a/doc/user/application_security/dast/browser/checks/798.4.md
+++ b/doc/user/application_security/dast/browser/checks/798.4.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Age secret key'
+title: Exposure of confidential secret or token Age secret key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.40.md b/doc/user/application_security/dast/browser/checks/798.40.md
index b1ec0ce5b496f234218d240882cc6f8a7b62a2ec..c3925e794d995f79b9e6c599acf0abbec2df36bc 100644
--- a/doc/user/application_security/dast/browser/checks/798.40.md
+++ b/doc/user/application_security/dast/browser/checks/798.40.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Fastly API key'
+title: Exposure of confidential secret or token Fastly API key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.41.md b/doc/user/application_security/dast/browser/checks/798.41.md
index 10947988e9a333c544a6e4d1ffce0b2129264ea3..5b5d0ad95a29fe40eabee580d5662d956a5e7c26 100644
--- a/doc/user/application_security/dast/browser/checks/798.41.md
+++ b/doc/user/application_security/dast/browser/checks/798.41.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Finicity Client Secret'
+title: Exposure of confidential secret or token Finicity Client Secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.42.md b/doc/user/application_security/dast/browser/checks/798.42.md
index fc209d3d4131225f7af9b9a0d1cd65c22d5aad9b..3c7ada749f832073e88d6376851071586e535f8e 100644
--- a/doc/user/application_security/dast/browser/checks/798.42.md
+++ b/doc/user/application_security/dast/browser/checks/798.42.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Finicity API token'
+title: Exposure of confidential secret or token Finicity API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.43.md b/doc/user/application_security/dast/browser/checks/798.43.md
index 02e635a0c31b7f64fae63a6f483c61e75c616756..b6f4ecf26c694513428863591efa7bf6ba88be43 100644
--- a/doc/user/application_security/dast/browser/checks/798.43.md
+++ b/doc/user/application_security/dast/browser/checks/798.43.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Flickr Access Token'
+title: Exposure of confidential secret or token Flickr Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.44.md b/doc/user/application_security/dast/browser/checks/798.44.md
index 1b2e3ee4ad59b3e1c8e4dfe334e25dbc0510f394..eae3d42152508d2a4b03bdce24a37092d9232f4e 100644
--- a/doc/user/application_security/dast/browser/checks/798.44.md
+++ b/doc/user/application_security/dast/browser/checks/798.44.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Finnhub Access Token'
+title: Exposure of confidential secret or token Finnhub Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.46.md b/doc/user/application_security/dast/browser/checks/798.46.md
index 51fd5d33666681a3f00def77c68789eb3a1b32b2..8980b05ae85263d0709a8a94acae676d343ac76c 100644
--- a/doc/user/application_security/dast/browser/checks/798.46.md
+++ b/doc/user/application_security/dast/browser/checks/798.46.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Flutterwave Secret Key'
+title: Exposure of confidential secret or token Flutterwave Secret Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.47.md b/doc/user/application_security/dast/browser/checks/798.47.md
index c8e996ca04ab3f343c0e0eb008883c11a00519ba..12faab66e5d53ebb5c154fa953a24040a0bc2dc7 100644
--- a/doc/user/application_security/dast/browser/checks/798.47.md
+++ b/doc/user/application_security/dast/browser/checks/798.47.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Flutterwave Encryption Key'
+title: Exposure of confidential secret or token Flutterwave Encryption Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.48.md b/doc/user/application_security/dast/browser/checks/798.48.md
index a284b2e2f479a8c6504f41f76813f5fbc729316c..70e07c4c88b6bab3558553922769e56243860cbf 100644
--- a/doc/user/application_security/dast/browser/checks/798.48.md
+++ b/doc/user/application_security/dast/browser/checks/798.48.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Frame.io API token'
+title: Exposure of confidential secret or token Frame.io API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.49.md b/doc/user/application_security/dast/browser/checks/798.49.md
index a4ddd62d083f3abea0dc8bcadacb3dba4220463e..4b1abee8e221f58586075a7d9b48743e11cc5f03 100644
--- a/doc/user/application_security/dast/browser/checks/798.49.md
+++ b/doc/user/application_security/dast/browser/checks/798.49.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token FreshBooks Access Token'
+title: Exposure of confidential secret or token FreshBooks Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.5.md b/doc/user/application_security/dast/browser/checks/798.5.md
index b96def674e67de611950b3c56b870b61cea18e62..e9e49516bfe495a84ef4de623d4d5d25828dc115 100644
--- a/doc/user/application_security/dast/browser/checks/798.5.md
+++ b/doc/user/application_security/dast/browser/checks/798.5.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Airtable API Key'
+title: Exposure of confidential secret or token Airtable API Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.50.md b/doc/user/application_security/dast/browser/checks/798.50.md
index bc0e61208f5a9e0d0a1ffac8ab008383f1ceeed1..1511d68cd8b14aff2ae74d69083ad492cfe727b3 100644
--- a/doc/user/application_security/dast/browser/checks/798.50.md
+++ b/doc/user/application_security/dast/browser/checks/798.50.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token GoCardless API token'
+title: Exposure of confidential secret or token GoCardless API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.52.md b/doc/user/application_security/dast/browser/checks/798.52.md
index c681f17c63057c286022bc344f63dee937fe8771..cd3f61b9160268055839530c759461d1bfbae81e 100644
--- a/doc/user/application_security/dast/browser/checks/798.52.md
+++ b/doc/user/application_security/dast/browser/checks/798.52.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token GitHub Personal Access Token'
+title: Exposure of confidential secret or token GitHub Personal Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.53.md b/doc/user/application_security/dast/browser/checks/798.53.md
index 8c24c547b2f00936f908bbb4eb817c54f21f3149..ddf1321b460e2648240388edc7f0d71b9b779044 100644
--- a/doc/user/application_security/dast/browser/checks/798.53.md
+++ b/doc/user/application_security/dast/browser/checks/798.53.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token GitHub OAuth Access Token'
+title: Exposure of confidential secret or token GitHub OAuth Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.54.md b/doc/user/application_security/dast/browser/checks/798.54.md
index 06adad2314da7398a603393c4937a6ed6f3f1964..236ce5d90572baadeff6d4968e8e8c3c6c022ad5 100644
--- a/doc/user/application_security/dast/browser/checks/798.54.md
+++ b/doc/user/application_security/dast/browser/checks/798.54.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token GitHub App Token'
+title: Exposure of confidential secret or token GitHub App Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.55.md b/doc/user/application_security/dast/browser/checks/798.55.md
index 22c010eb693bf65892fcae52561ce08e3b84d3bd..30efe35ad464e0bb4d8a1aa7b73191bed02b4d0c 100644
--- a/doc/user/application_security/dast/browser/checks/798.55.md
+++ b/doc/user/application_security/dast/browser/checks/798.55.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token GitHub Refresh Token'
+title: Exposure of confidential secret or token GitHub Refresh Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.56.md b/doc/user/application_security/dast/browser/checks/798.56.md
index 4ee0bfaa1e668a54f6881d629016972da01e14c4..4fed3be241f895b1935139c5b4690eec449b3b29 100644
--- a/doc/user/application_security/dast/browser/checks/798.56.md
+++ b/doc/user/application_security/dast/browser/checks/798.56.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token GitLab Personal Access Token'
+title: Exposure of confidential secret or token GitLab Personal Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.57.md b/doc/user/application_security/dast/browser/checks/798.57.md
index aba938510f6cb761d9afd1bdfc1d541b58ed310a..c518d25d4edb3bc46bd99278022f2fff8bf9d47f 100644
--- a/doc/user/application_security/dast/browser/checks/798.57.md
+++ b/doc/user/application_security/dast/browser/checks/798.57.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Gitter Access Token'
+title: Exposure of confidential secret or token Gitter Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.58.md b/doc/user/application_security/dast/browser/checks/798.58.md
index e87577df6d1740d4a80b529b701c1b80c1675023..8698f3ee38fc9d977b25d1d922e53acfc20424f6 100644
--- a/doc/user/application_security/dast/browser/checks/798.58.md
+++ b/doc/user/application_security/dast/browser/checks/798.58.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token HashiCorp Terraform user/org API token'
+title: Exposure of confidential secret or token HashiCorp Terraform user/org API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.59.md b/doc/user/application_security/dast/browser/checks/798.59.md
index 1f9aae57f32fe0c4743f12035dae154ed10ce937..14537cf6edc0c4c17e3ff754b856d33e81111595 100644
--- a/doc/user/application_security/dast/browser/checks/798.59.md
+++ b/doc/user/application_security/dast/browser/checks/798.59.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Heroku API Key'
+title: Exposure of confidential secret or token Heroku API Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.6.md b/doc/user/application_security/dast/browser/checks/798.6.md
index 8c3ab6f226a45301483d0a50058c8e5a728e369e..1b2845687b87bc0bfb7b44178845cea7bb9bc16e 100644
--- a/doc/user/application_security/dast/browser/checks/798.6.md
+++ b/doc/user/application_security/dast/browser/checks/798.6.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Algolia API Key'
+title: Exposure of confidential secret or token Algolia API Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.60.md b/doc/user/application_security/dast/browser/checks/798.60.md
index ccd44b0f51349c6197412170476f558af6b138cd..1aafbcd6b01c5d35750af65bd5ce12a72dca5d0b 100644
--- a/doc/user/application_security/dast/browser/checks/798.60.md
+++ b/doc/user/application_security/dast/browser/checks/798.60.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token HubSpot API Token'
+title: Exposure of confidential secret or token HubSpot API Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.61.md b/doc/user/application_security/dast/browser/checks/798.61.md
index 6acdaf0046c26a5e880c3dfceb9fe6415560cadf..3eb413b12323f370075ee628a76d68368930c575 100644
--- a/doc/user/application_security/dast/browser/checks/798.61.md
+++ b/doc/user/application_security/dast/browser/checks/798.61.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Intercom API Token'
+title: Exposure of confidential secret or token Intercom API Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.62.md b/doc/user/application_security/dast/browser/checks/798.62.md
index c9963b9dbbad5e7349eed822efcb041df3ac740f..4cf622a9564819ce3d346a9e67ef6ecfdc912134 100644
--- a/doc/user/application_security/dast/browser/checks/798.62.md
+++ b/doc/user/application_security/dast/browser/checks/798.62.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Kraken Access Token'
+title: Exposure of confidential secret or token Kraken Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.63.md b/doc/user/application_security/dast/browser/checks/798.63.md
index 0ba097caa823e25593a64aa2194d41fdc6b0fd29..ad0b903823358354ca7856d0411532c36c0778ae 100644
--- a/doc/user/application_security/dast/browser/checks/798.63.md
+++ b/doc/user/application_security/dast/browser/checks/798.63.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Kucoin Access Token'
+title: Exposure of confidential secret or token Kucoin Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.64.md b/doc/user/application_security/dast/browser/checks/798.64.md
index 0e1e453957d352f8f624b7d6e3cb8400492cc05f..da0e5a60659c2065189b69b534b45d8d4d49c88d 100644
--- a/doc/user/application_security/dast/browser/checks/798.64.md
+++ b/doc/user/application_security/dast/browser/checks/798.64.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Kucoin Secret Key'
+title: Exposure of confidential secret or token Kucoin Secret Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.65.md b/doc/user/application_security/dast/browser/checks/798.65.md
index 02388586474c5fa73e2a91659117edea0978474a..2fd758ca73c73587ac83ad61176b7f6c5e4de95f 100644
--- a/doc/user/application_security/dast/browser/checks/798.65.md
+++ b/doc/user/application_security/dast/browser/checks/798.65.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token LaunchDarkly Access Token'
+title: Exposure of confidential secret or token LaunchDarkly Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.66.md b/doc/user/application_security/dast/browser/checks/798.66.md
index 3baf56fce80172d6624903b7cbbb3ea7ee991bea..2e73c1d20dc8c9a2c597be3e651dbd228d43c6cb 100644
--- a/doc/user/application_security/dast/browser/checks/798.66.md
+++ b/doc/user/application_security/dast/browser/checks/798.66.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Linear API Token'
+title: Exposure of confidential secret or token Linear API Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.67.md b/doc/user/application_security/dast/browser/checks/798.67.md
index 710994f3da883a1cf4806af7d0f2c5330ed13d4f..00bba177d6c62ed7dded7b7325107b55d5b16654 100644
--- a/doc/user/application_security/dast/browser/checks/798.67.md
+++ b/doc/user/application_security/dast/browser/checks/798.67.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Linear Client Secret'
+title: Exposure of confidential secret or token Linear Client Secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.68.md b/doc/user/application_security/dast/browser/checks/798.68.md
index aeadbce2f1b58b19a8e69b7b531a2359fe13cb23..a50476c272e8c167a73a88c00181f75d43df1a7b 100644
--- a/doc/user/application_security/dast/browser/checks/798.68.md
+++ b/doc/user/application_security/dast/browser/checks/798.68.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token LinkedIn Client ID'
+title: Exposure of confidential secret or token LinkedIn Client ID
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.69.md b/doc/user/application_security/dast/browser/checks/798.69.md
index 9dce82065543d359353dcc1ed368f539e6177d3a..b1ad133302047d00294be22de355753efd0db3e2 100644
--- a/doc/user/application_security/dast/browser/checks/798.69.md
+++ b/doc/user/application_security/dast/browser/checks/798.69.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token LinkedIn Client secret'
+title: Exposure of confidential secret or token LinkedIn Client secret
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.7.md b/doc/user/application_security/dast/browser/checks/798.7.md
index 738b4f0a5d783346efda9b5a34c0c5fd1332751b..e0c7664eea2e58b229b6eab9f14fcaac64b2c0b2 100644
--- a/doc/user/application_security/dast/browser/checks/798.7.md
+++ b/doc/user/application_security/dast/browser/checks/798.7.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Alibaba AccessKey ID'
+title: Exposure of confidential secret or token Alibaba AccessKey ID
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.70.md b/doc/user/application_security/dast/browser/checks/798.70.md
index e3217963b7006233e9fb1d7b1b5b583f1ce4f47d..8ed35f68aad76a450ab14c2d9e710e9104ab5af4 100644
--- a/doc/user/application_security/dast/browser/checks/798.70.md
+++ b/doc/user/application_security/dast/browser/checks/798.70.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Lob API Key'
+title: Exposure of confidential secret or token Lob API Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.72.md b/doc/user/application_security/dast/browser/checks/798.72.md
index ec73393eaea8ade9b4875f81fec6fa9363c1c11f..32a16271ce4db47fea32c66bde52f01feafec6e3 100644
--- a/doc/user/application_security/dast/browser/checks/798.72.md
+++ b/doc/user/application_security/dast/browser/checks/798.72.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Mailchimp API key'
+title: Exposure of confidential secret or token Mailchimp API key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.74.md b/doc/user/application_security/dast/browser/checks/798.74.md
index 84e020b314f40a76b38139d7ec0dfa67cdd7bf5c..d4e6e426541383393b6c4ec45a30c9e767c3c6ac 100644
--- a/doc/user/application_security/dast/browser/checks/798.74.md
+++ b/doc/user/application_security/dast/browser/checks/798.74.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Mailgun private API token'
+title: Exposure of confidential secret or token Mailgun private API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.75.md b/doc/user/application_security/dast/browser/checks/798.75.md
index 489cebea458b46f08d5f3cc548f922e1d1bb7601..1dc528ddf5c7c06a169ca1f9e810b592a1e87ab7 100644
--- a/doc/user/application_security/dast/browser/checks/798.75.md
+++ b/doc/user/application_security/dast/browser/checks/798.75.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Mailgun webhook signing key'
+title: Exposure of confidential secret or token Mailgun webhook signing key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.77.md b/doc/user/application_security/dast/browser/checks/798.77.md
index bb5551d1b19b421dae3796445a33664136018104..fb71be6f1a74ffb62cbdd366a9d76685fc96c196 100644
--- a/doc/user/application_security/dast/browser/checks/798.77.md
+++ b/doc/user/application_security/dast/browser/checks/798.77.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Mattermost Access Token'
+title: Exposure of confidential secret or token Mattermost Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.78.md b/doc/user/application_security/dast/browser/checks/798.78.md
index c361c622a7a601615d501c0dd0ab5e72700108dd..8bbe59a6f1c0331ad7fcb308b45eedf2e5181658 100644
--- a/doc/user/application_security/dast/browser/checks/798.78.md
+++ b/doc/user/application_security/dast/browser/checks/798.78.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token MessageBird API token'
+title: Exposure of confidential secret or token MessageBird API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.8.md b/doc/user/application_security/dast/browser/checks/798.8.md
index 972d589e91d3786fe52ec0f368f4d11c2c376c42..8fca37c191a9d5162dd4306d42d1b976a566907d 100644
--- a/doc/user/application_security/dast/browser/checks/798.8.md
+++ b/doc/user/application_security/dast/browser/checks/798.8.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Alibaba Secret Key'
+title: Exposure of confidential secret or token Alibaba Secret Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.80.md b/doc/user/application_security/dast/browser/checks/798.80.md
index 7ef99f5ab0cde95c7c8d6c650e4155fb5ef7641f..79522534cacd0ebfd4d9540dfd521076398040d3 100644
--- a/doc/user/application_security/dast/browser/checks/798.80.md
+++ b/doc/user/application_security/dast/browser/checks/798.80.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Netlify Access Token'
+title: Exposure of confidential secret or token Netlify Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.81.md b/doc/user/application_security/dast/browser/checks/798.81.md
index 3e2dd360eebbf2df00c1e2d63258b7b36c646b94..06f9305abd09df58d6a0f687aaa48bb241dc8365 100644
--- a/doc/user/application_security/dast/browser/checks/798.81.md
+++ b/doc/user/application_security/dast/browser/checks/798.81.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token New Relic user API Key'
+title: Exposure of confidential secret or token New Relic user API Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.82.md b/doc/user/application_security/dast/browser/checks/798.82.md
index ae76432961b3d3dce16411187081b043f56a262d..6e41d527c2a2b9e75bf202b8f8909e1e5b68c171 100644
--- a/doc/user/application_security/dast/browser/checks/798.82.md
+++ b/doc/user/application_security/dast/browser/checks/798.82.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token New Relic user API ID'
+title: Exposure of confidential secret or token New Relic user API ID
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.83.md b/doc/user/application_security/dast/browser/checks/798.83.md
index aba4ce1aa6dc40e33f7f2d15f81056fcd91beef9..69e37585317b9910359c7adb9ffa3a30c6e051fd 100644
--- a/doc/user/application_security/dast/browser/checks/798.83.md
+++ b/doc/user/application_security/dast/browser/checks/798.83.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token New Relic ingest browser API token'
+title: Exposure of confidential secret or token New Relic ingest browser API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.84.md b/doc/user/application_security/dast/browser/checks/798.84.md
index 91a8b79e1f401de7f95244b0332d56eb31228488..b1aa8afdd1bffd38db6379cba66189cdf2e2f0fd 100644
--- a/doc/user/application_security/dast/browser/checks/798.84.md
+++ b/doc/user/application_security/dast/browser/checks/798.84.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token npm access token'
+title: Exposure of confidential secret or token npm access token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.86.md b/doc/user/application_security/dast/browser/checks/798.86.md
index 5b3f885f91998bacd18871e643adcddca16d3296..f0d0f2b577212839083e11443aea5c504cc0f0bc 100644
--- a/doc/user/application_security/dast/browser/checks/798.86.md
+++ b/doc/user/application_security/dast/browser/checks/798.86.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Okta Access Token'
+title: Exposure of confidential secret or token Okta Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.87.md b/doc/user/application_security/dast/browser/checks/798.87.md
index f91020fdcc1418a8bcbf7709a15219277cac0171..5fbb70e905146112aaf4a91dc931d28e653e5ab5 100644
--- a/doc/user/application_security/dast/browser/checks/798.87.md
+++ b/doc/user/application_security/dast/browser/checks/798.87.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Plaid Client ID'
+title: Exposure of confidential secret or token Plaid Client ID
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.88.md b/doc/user/application_security/dast/browser/checks/798.88.md
index b05d23ded8fdae316697f544a686431ed853a933..066f76fb1249a8c0612fb95af0404f49d95fae49 100644
--- a/doc/user/application_security/dast/browser/checks/798.88.md
+++ b/doc/user/application_security/dast/browser/checks/798.88.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Plaid Secret key'
+title: Exposure of confidential secret or token Plaid Secret key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.89.md b/doc/user/application_security/dast/browser/checks/798.89.md
index 5a319d1e66daca46bf121382c744ffcec4921d86..e17d092cd3c31630dc4db1540b29ae273679ee13 100644
--- a/doc/user/application_security/dast/browser/checks/798.89.md
+++ b/doc/user/application_security/dast/browser/checks/798.89.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Plaid API Token'
+title: Exposure of confidential secret or token Plaid API Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.9.md b/doc/user/application_security/dast/browser/checks/798.9.md
index ea18d0795671bb59ca9490478cea5f77fa483912..ded223f32324836d11cb085dadfffe6af9c6b0ee 100644
--- a/doc/user/application_security/dast/browser/checks/798.9.md
+++ b/doc/user/application_security/dast/browser/checks/798.9.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Asana Client ID'
+title: Exposure of confidential secret or token Asana Client ID
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.90.md b/doc/user/application_security/dast/browser/checks/798.90.md
index 86612847a5e7ebf65c857fefff6f19806496a3f7..5eea5c706493b8a3163f1a00b0c30e7639ce6595 100644
--- a/doc/user/application_security/dast/browser/checks/798.90.md
+++ b/doc/user/application_security/dast/browser/checks/798.90.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token PlanetScale password'
+title: Exposure of confidential secret or token PlanetScale password
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.91.md b/doc/user/application_security/dast/browser/checks/798.91.md
index a732754b653427d9005ca54234119da3c57389c6..53a2fb6d57fd331fc6af2616d7fc3dba4ce107ef 100644
--- a/doc/user/application_security/dast/browser/checks/798.91.md
+++ b/doc/user/application_security/dast/browser/checks/798.91.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token PlanetScale API token'
+title: Exposure of confidential secret or token PlanetScale API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.92.md b/doc/user/application_security/dast/browser/checks/798.92.md
index e5e8f864a80d2ee03526017898d676157ab4c2b3..b61c152d616ca6323ce1bf15a2918baf4ab70d71 100644
--- a/doc/user/application_security/dast/browser/checks/798.92.md
+++ b/doc/user/application_security/dast/browser/checks/798.92.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token PlanetScale OAuth token'
+title: Exposure of confidential secret or token PlanetScale OAuth token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.93.md b/doc/user/application_security/dast/browser/checks/798.93.md
index 60a23fc69826c106bda8bee3842680d6ee2c99a6..c017016fd11618029ac204eef4e16405b89876c4 100644
--- a/doc/user/application_security/dast/browser/checks/798.93.md
+++ b/doc/user/application_security/dast/browser/checks/798.93.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Postman API token'
+title: Exposure of confidential secret or token Postman API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.94.md b/doc/user/application_security/dast/browser/checks/798.94.md
index d7fdbcd409e1463bb8443e40fb7daaddee616b79..583b26ef4830b073bd02dbf0368d8cecc7032e92 100644
--- a/doc/user/application_security/dast/browser/checks/798.94.md
+++ b/doc/user/application_security/dast/browser/checks/798.94.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Private Key'
+title: Exposure of confidential secret or token Private Key
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.95.md b/doc/user/application_security/dast/browser/checks/798.95.md
index 06c2840d9c1b87aa7d5887c2b96b5cbef5759c1b..2def598c36b8cb203920590117aa08d776b0df89 100644
--- a/doc/user/application_security/dast/browser/checks/798.95.md
+++ b/doc/user/application_security/dast/browser/checks/798.95.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Pulumi API token'
+title: Exposure of confidential secret or token Pulumi API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.96.md b/doc/user/application_security/dast/browser/checks/798.96.md
index 443ae28242e9ffc0660f1cc78df7c0e710fbfcfb..d6693b9edcb04e164d71f846acaf8886d58c934f 100644
--- a/doc/user/application_security/dast/browser/checks/798.96.md
+++ b/doc/user/application_security/dast/browser/checks/798.96.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token PyPI upload token'
+title: Exposure of confidential secret or token PyPI upload token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.97.md b/doc/user/application_security/dast/browser/checks/798.97.md
index b480e2e1dcd04fb4893ba0ca0950f29704b8c0cc..b12259128ac724a59e3595a6c656574cca1644be 100644
--- a/doc/user/application_security/dast/browser/checks/798.97.md
+++ b/doc/user/application_security/dast/browser/checks/798.97.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token RubyGems API token'
+title: Exposure of confidential secret or token RubyGems API token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.98.md b/doc/user/application_security/dast/browser/checks/798.98.md
index 47776f03eac9e08aabc0cf4044857bc2e1d0670a..cba5d7d2a3e8bb793eaed15dd19760f43bb477dc 100644
--- a/doc/user/application_security/dast/browser/checks/798.98.md
+++ b/doc/user/application_security/dast/browser/checks/798.98.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token RapidAPI Access Token'
+title: Exposure of confidential secret or token RapidAPI Access Token
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/798.99.md b/doc/user/application_security/dast/browser/checks/798.99.md
index 3fb2c58767351f972e39a3d8afe8830da4571abd..063df5bc4ca3a9eb8efa36bc669a3e0a7b1fb900 100644
--- a/doc/user/application_security/dast/browser/checks/798.99.md
+++ b/doc/user/application_security/dast/browser/checks/798.99.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Exposure of confidential secret or token Sendbird Access ID'
+title: Exposure of confidential secret or token Sendbird Access ID
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/829.1.md b/doc/user/application_security/dast/browser/checks/829.1.md
index a498777e676af68054ed445e93a024479b0b9c59..6f0187708720b1b5dd178ed7f7de5f6affed785d 100644
--- a/doc/user/application_security/dast/browser/checks/829.1.md
+++ b/doc/user/application_security/dast/browser/checks/829.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Inclusion of Functionality from Untrusted Control Sphere'
+title: Inclusion of Functionality from Untrusted Control Sphere
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/829.2.md b/doc/user/application_security/dast/browser/checks/829.2.md
index 02a4ad99791130dc8f393b8ae31fc87a0b776825..a308320ce88fb2c15a6225c0232cb84f95972846 100644
--- a/doc/user/application_security/dast/browser/checks/829.2.md
+++ b/doc/user/application_security/dast/browser/checks/829.2.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Invalid Sub-Resource Integrity values detected'
+title: Invalid Sub-Resource Integrity values detected
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/89.1.md b/doc/user/application_security/dast/browser/checks/89.1.md
index 25a021d8045f82455e4a15538f933c5d17e4929c..549a4acde0382e877bcbf10b2534e15a628c22c5 100644
--- a/doc/user/application_security/dast/browser/checks/89.1.md
+++ b/doc/user/application_security/dast/browser/checks/89.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'SQL Injection'
+title: SQL Injection
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/917.1.md b/doc/user/application_security/dast/browser/checks/917.1.md
index dc084a32350569f8f3cccede5ac347cbd42336f6..00195566ac8f3a656622c9bb43173a8060b0086b 100644
--- a/doc/user/application_security/dast/browser/checks/917.1.md
+++ b/doc/user/application_security/dast/browser/checks/917.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Expression Language Injection'
+title: Expression Language Injection
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/918.1.md b/doc/user/application_security/dast/browser/checks/918.1.md
index 55aeb2d7adaed991d193af9ccc450838fc418eb9..8bca2f83a322427078f8977a03cc4e6b5702ff39 100644
--- a/doc/user/application_security/dast/browser/checks/918.1.md
+++ b/doc/user/application_security/dast/browser/checks/918.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Server-Side Request Forgery'
+title: Server-Side Request Forgery
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/94.1.md b/doc/user/application_security/dast/browser/checks/94.1.md
index 569de9c7ceb0b9cabbbf07f070551adee1508ad8..18ab592e84de1cc109b8c0d7c41d2b252f7e19e2 100644
--- a/doc/user/application_security/dast/browser/checks/94.1.md
+++ b/doc/user/application_security/dast/browser/checks/94.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Server-side code injection (PHP)'
+title: Server-side code injection (PHP)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/94.2.md b/doc/user/application_security/dast/browser/checks/94.2.md
index 3f6218b2d5a1c7d7aa883e00dcb5f4ad66122d96..a0da2a2249f2daa518b4ef6bd9e9a34652771b9d 100644
--- a/doc/user/application_security/dast/browser/checks/94.2.md
+++ b/doc/user/application_security/dast/browser/checks/94.2.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Server-side code injection (Ruby)'
+title: Server-side code injection (Ruby)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/94.3.md b/doc/user/application_security/dast/browser/checks/94.3.md
index ce410807be041985033b0b24e60088f183c1c0ba..b5dc52bf3bb1b898dc24498fc4587adac4d2d677 100644
--- a/doc/user/application_security/dast/browser/checks/94.3.md
+++ b/doc/user/application_security/dast/browser/checks/94.3.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Server-side code injection (Python)'
+title: Server-side code injection (Python)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/94.4.md b/doc/user/application_security/dast/browser/checks/94.4.md
index a96e51d6bb32265f081b4b73f3a8fe0d5b00b35c..389ae76b76b692627241ab26a374eb998ca8a959 100644
--- a/doc/user/application_security/dast/browser/checks/94.4.md
+++ b/doc/user/application_security/dast/browser/checks/94.4.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Server-side code injection (NodeJS)'
+title: Server-side code injection (NodeJS)
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/943.1.md b/doc/user/application_security/dast/browser/checks/943.1.md
index 1cce7072149d34b371b07bd06f3e52fc0f7c2672..9afe468acbf55627d21eb7adf94c40fdf914fa5a 100644
--- a/doc/user/application_security/dast/browser/checks/943.1.md
+++ b/doc/user/application_security/dast/browser/checks/943.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'Improper neutralization of special elements in data query logic'
+title: Improper neutralization of special elements in data query logic
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/98.1.md b/doc/user/application_security/dast/browser/checks/98.1.md
index ee2cfcef2a3c18308ffc27a9cafb3285c6e90bac..ac7f4c0bc59d865a47623efa120c5cbe8c844454 100644
--- a/doc/user/application_security/dast/browser/checks/98.1.md
+++ b/doc/user/application_security/dast/browser/checks/98.1.md
@@ -2,7 +2,7 @@
stage: Application Security Testing
group: Dynamic Analysis
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
-title: 'PHP Remote File Inclusion'
+title: PHP Remote File Inclusion
---
## Description
diff --git a/doc/user/application_security/dast/browser/checks/_index.md b/doc/user/application_security/dast/browser/checks/_index.md
index 19400965bd3d816d8db0b48b4d5264508aa35e96..a1a5cda9fb6fdad3c387d380c01899bdd05a32cf 100644
--- a/doc/user/application_security/dast/browser/checks/_index.md
+++ b/doc/user/application_security/dast/browser/checks/_index.md
@@ -10,9 +10,12 @@ This file is autogenerated. Do not edit directly.
See: https://gitlab.com/gitlab-org/security-products/dast-cwe-checks/-/blob/main/doc/how-to-generate-the-markdown-documentation.md
-->
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The [DAST browser-based crawler](../_index.md) provides vulnerability checks that are used to
scan for vulnerabilities in the site under test.
diff --git a/doc/user/application_security/dast/browser/configuration/_index.md b/doc/user/application_security/dast/browser/configuration/_index.md
index e429f5f79b4a3225cf096cf4f55756c4bed258f1..b02b8e39cbb72c7c00ba16462278868b2b91cbfc 100644
--- a/doc/user/application_security/dast/browser/configuration/_index.md
+++ b/doc/user/application_security/dast/browser/configuration/_index.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Configuration
---
diff --git a/doc/user/application_security/dast/browser/configuration/authentication.md b/doc/user/application_security/dast/browser/configuration/authentication.md
index 603240c9e3031534cca0b88b52e0bfe846b0b228..a441fc983df62bcc45ccc41b2ecba7ead94a365e 100644
--- a/doc/user/application_security/dast/browser/configuration/authentication.md
+++ b/doc/user/application_security/dast/browser/configuration/authentication.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Authentication
---
@@ -39,10 +39,13 @@ When choosing authentication credentials:
## Getting started
-NOTE:
+{{< alert type="note" >}}
+
You should periodically confirming that the analyzer's authentication is still working, as this tends to break over
time due to changes to the application.
+{{< /alert >}}
+
To run a DAST authenticated scan:
- Read the [prerequisite](#prerequisites) conditions for authentication.
@@ -542,9 +545,12 @@ Authentication failed because a home page should be displayed after login. Inste
### Configure the authentication report
-WARNING:
+{{< alert type="warning" >}}
+
The authentication report can contain sensitive information such as the credentials used to perform the login.
+{{< /alert >}}
+
An authentication report can be saved as a CI/CD job artifact to assist with understanding the cause of an authentication failure.
The report contains steps performed during the login process, HTTP requests and responses, the Document Object Model (DOM) and screenshots.
diff --git a/doc/user/application_security/dast/browser/configuration/customize_settings.md b/doc/user/application_security/dast/browser/configuration/customize_settings.md
index cc9fca61ae0a7aa27903164b015e4e86efed677e..cc645eb742d3b655c82fcf1a421905d1629d6664 100644
--- a/doc/user/application_security/dast/browser/configuration/customize_settings.md
+++ b/doc/user/application_security/dast/browser/configuration/customize_settings.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Customize analyzer settings
---
@@ -142,5 +142,8 @@ dast:
DAST_PAGE_DOM_READY_TIMEOUT: "15s"
```
-NOTE:
+{{< alert type="note" >}}
+
Adjusting these values may impact scan time because they adjust how long each browser waits for various activities to complete.
+
+{{< /alert >}}
diff --git a/doc/user/application_security/dast/browser/configuration/enabling_the_analyzer.md b/doc/user/application_security/dast/browser/configuration/enabling_the_analyzer.md
index f7db1282bd7995af6b7978204cb7dc5ab5d93feb..0a8197670a02087f0e5ebc0a5060ec9c2d702009 100644
--- a/doc/user/application_security/dast/browser/configuration/enabling_the_analyzer.md
+++ b/doc/user/application_security/dast/browser/configuration/enabling_the_analyzer.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Enabling the analyzer
---
@@ -35,10 +35,13 @@ To create the CI/CD job:
- [`DAST.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml):
Latest version of the DAST template.
- WARNING:
+ {{< alert type="warning" >}}
+
The latest version of the template may include breaking changes. Use the
stable template unless you need a feature provided only in the latest template.
+ {{< /alert >}}
+
For more information about template versioning, see the
[CI/CD documentation](../../../../../development/cicd/templates.md#latest-version).
diff --git a/doc/user/application_security/dast/browser/configuration/offline_configuration.md b/doc/user/application_security/dast/browser/configuration/offline_configuration.md
index c4b4c7d995dfbba35f2107715daffefd059f1c80..c254ca7e36c6f53cefca3f82b7c7871c567f1b03 100644
--- a/doc/user/application_security/dast/browser/configuration/offline_configuration.md
+++ b/doc/user/application_security/dast/browser/configuration/offline_configuration.md
@@ -1,14 +1,17 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Offline configuration
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
For instances in an environment with limited, restricted, or intermittent access
to external resources through the internet, some adjustments are required for the DAST job to
diff --git a/doc/user/application_security/dast/browser/configuration/overriding_analyzer_jobs.md b/doc/user/application_security/dast/browser/configuration/overriding_analyzer_jobs.md
index 9e6d6fe563f846feedcc3bf6dc1d07baac85c142..2b118310d6f2789c95ae64729f1b8629df3e9015 100644
--- a/doc/user/application_security/dast/browser/configuration/overriding_analyzer_jobs.md
+++ b/doc/user/application_security/dast/browser/configuration/overriding_analyzer_jobs.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Overriding DAST jobs
---
diff --git a/doc/user/application_security/dast/browser/configuration/requirements.md b/doc/user/application_security/dast/browser/configuration/requirements.md
index 09236395c3b09f6032e48ef4eeda0d9e3f590026..23a5c43211da90e4cfd5223a68fcf5be5fb84c6e 100644
--- a/doc/user/application_security/dast/browser/configuration/requirements.md
+++ b/doc/user/application_security/dast/browser/configuration/requirements.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Requirements
---
diff --git a/doc/user/application_security/dast/browser/configuration/variables.md b/doc/user/application_security/dast/browser/configuration/variables.md
index 7e4981b9f75a0ce77e591499cb110430fa1374e5..3850bc9e240ee2482c2014f9b6ce48a549870889 100644
--- a/doc/user/application_security/dast/browser/configuration/variables.md
+++ b/doc/user/application_security/dast/browser/configuration/variables.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Available CI/CD variables
---
diff --git a/doc/user/application_security/dast/browser/troubleshooting.md b/doc/user/application_security/dast/browser/troubleshooting.md
index c921593a9b5b1cf046a0905b2abcc9d505fdf8a0..aed739b23e6bc1ef2e26136220122df72891b3c3 100644
--- a/doc/user/application_security/dast/browser/troubleshooting.md
+++ b/doc/user/application_security/dast/browser/troubleshooting.md
@@ -1,8 +1,8 @@
---
+type: reference, howto
stage: Application Security Testing
group: Dynamic Analysis
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
-type: reference, howto
title: Troubleshooting
---
@@ -185,10 +185,13 @@ For example, the following output shows that four anchor links we discovered dur
## Chromium DevTools logging
-WARNING:
+{{< alert type="warning" >}}
+
Logging DevTools messages is a security risk. The output contains secrets such as usernames, passwords and authentication tokens.
The output is uploaded to the GitLab server and may be visible in job logs.
+{{< /alert >}}
+
The DAST Browser-based scanner orchestrates a Chromium browser using the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
Logging DevTools messages helps provide transparency into what the browser is doing. For example, if selecting a button does not work, a DevTools message might show that the cause is a CORS error in a browser console log.
Logs that contain DevTools messages can be very large in size. For this reason, it should only be enabled on jobs with a short duration.
diff --git a/doc/user/application_security/dast/browser_based_4_to_5_migration_guide.md b/doc/user/application_security/dast/browser_based_4_to_5_migration_guide.md
index 66e1ea1682a4e28a426165655ad92c94f9878890..a281e2eac1dd1f0fb8de0db7df5b1fd3582ba256 100644
--- a/doc/user/application_security/dast/browser_based_4_to_5_migration_guide.md
+++ b/doc/user/application_security/dast/browser_based_4_to_5_migration_guide.md
@@ -5,7 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from the DAST version 4 browser-based analyzer to DAST version 5
---
-> - The [DAST proxy-based analyzer](proxy-based.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966) in GitLab 16.6 and removed in 17.0.
+{{< history >}}
+
+- The [DAST proxy-based analyzer](proxy-based.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966) in GitLab 16.6 and removed in 17.0.
+
+{{< /history >}}
[DAST version 5](browser/_index.md) replaces DAST version 4. This document serves as a guide to
migrate from the DAST version 4 browser-based analyzer to DAST version 5.
diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md
index 20b37143429898a2b67f3a24a95d3d2e553be718..9da12447b9a0960d6bab77ec100b947317accfc1 100644
--- a/doc/user/application_security/dast/dast_troubleshooting.md
+++ b/doc/user/application_security/dast/dast_troubleshooting.md
@@ -1,15 +1,18 @@
---
+redirect_to: proxy_based_to_browser_based_migration_guide.md
+remove_date: "2025-02-15"
stage: Application Security Testing
group: Dynamic Analysis
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
-remove_date: '2025-02-15'
-redirect_to: 'proxy_based_to_browser_based_migration_guide.md'
title: Troubleshooting DAST proxy-based analyzer (removed)
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966) in GitLab 16.9
and [removed](https://gitlab.com/groups/gitlab-org/-/epics/11986) in 17.3.
diff --git a/doc/user/application_security/dast/on-demand_scan.md b/doc/user/application_security/dast/on-demand_scan.md
index bcb5eeb0a652f32665974c8cd6d9906d47b4dffc..d6e5fb62d9e9f777f53909f1e1c1fc3d560112b4 100644
--- a/doc/user/application_security/dast/on-demand_scan.md
+++ b/doc/user/application_security/dast/on-demand_scan.md
@@ -5,19 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: DAST on-demand scan
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
Do not run DAST scans against a production server. Not only can it perform *any* function that a user can, such
as clicking buttons or submitting forms, but it may also trigger bugs, leading to modification or loss of production data.
Only run DAST scans against a test server.
+{{< /alert >}}
+
## On-demand scans
-> - Runner tags selection [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111499) in GitLab 16.3.
-> - Browser based on-demand DAST scans available in GitLab 17.0 and later because [proxy-based DAST was removed in the same version](../../../update/deprecations.md#proxy-based-dast-deprecated).
+{{< history >}}
+
+- Runner tags selection [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111499) in GitLab 16.3.
+- Browser based on-demand DAST scans available in GitLab 17.0 and later because [proxy-based DAST was removed in the same version](../../../update/deprecations.md#proxy-based-dast-deprecated).
+
+{{< /history >}}
An on-demand DAST scan runs outside the DevOps lifecycle. Changes in your repository don't trigger
the scan. You must either start it manually, or schedule it to run. For on-demand DAST scans,
@@ -109,7 +119,7 @@ To view details of an on-demand scan:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > On-demand scans**.
1. Select the **Scan library** tab.
-1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**.
+1. In the saved scan's row select **More actions** ({{< icon name="ellipsis_v" >}}), then select **Edit**.
### Edit an on-demand scan
@@ -122,7 +132,7 @@ To edit an on-demand scan:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > On-demand scans**.
1. Select the **Scan library** tab.
-1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**.
+1. In the saved scan's row select **More actions** ({{< icon name="ellipsis_v" >}}), then select **Edit**.
1. Edit the saved scan's details.
1. Select **Save scan**.
@@ -137,14 +147,18 @@ To delete an on-demand scan:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > On-demand scans**.
1. Select the **Scan library** tab.
-1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**.
+1. In the saved scan's row select **More actions** ({{< icon name="ellipsis_v" >}}), then select **Delete**.
1. On the confirmation dialog, select **Delete**.
## Site profile
-> - Site profile features, scan method and file URL, were [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/345837) in GitLab 15.6.
-> - GraphQL endpoint path feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378692) in GitLab 15.7.
-> - Additional variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/177703) in GitLab 17.9.
+{{< history >}}
+
+- Site profile features, scan method and file URL, were [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/345837) in GitLab 15.6.
+- GraphQL endpoint path feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378692) in GitLab 15.7.
+- Additional variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/177703) in GitLab 17.9.
+
+{{< /history >}}
A site profile defines the attributes and configuration details of the deployed application,
website, or API to be scanned by DAST.
@@ -225,12 +239,17 @@ Prerequisites:
- If a DAST scan uses the profile, you must be able to push to the branch associated with the scan.
-NOTE:
+{{< alert type="note" >}}
+
If a site profile is linked to a security policy, you cannot edit the profile from this page. See
[Scan execution policies](../policies/scan_execution_policies.md) for more information.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
If a site profile's Target URL or Authenticated URL is updated, the request headers and password fields associated with that profile are cleared.
+{{< /alert >}}
When a validated site profile's file, header, or meta tag is edited, the site's
[validation status](#site-profile-validation) is revoked.
@@ -241,7 +260,7 @@ To edit a site profile:
1. Select **Secure > Security configuration**.
1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**.
1. Select the **Site Profiles** tab.
-1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**.
+1. In the profile's row select the **More actions** ({{< icon name="ellipsis_v" >}}) menu, then select **Edit**.
1. Edit the fields then select **Save profile**.
### Delete a site profile
@@ -250,17 +269,20 @@ Prerequisites:
- If a DAST scan uses the profile, you must be able to push to the branch associated with the scan.
-NOTE:
+{{< alert type="note" >}}
+
If a site profile is linked to a security policy, a user cannot delete the profile from this page.
See [Scan execution policies](../policies/scan_execution_policies.md) for more information.
+{{< /alert >}}
+
To delete a site profile:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > Security configuration**.
1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**.
1. Select the **Site Profiles** tab.
-1. In the profile's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**.
+1. In the profile's row, select the **More actions** ({{< icon name="ellipsis_v" >}}) menu, then select **Delete**.
1. Select **Delete** to confirm the deletion.
### Validate a site profile
@@ -315,10 +337,13 @@ To retry a site profile's failed validation:
### Revoke a site profile's validation status
-WARNING:
+{{< alert type="warning" >}}
+
When a site profile's validation status is revoked, all site profiles that share the same URL also
have their validation status revoked.
+{{< /alert >}}
+
To revoke a site profile's validation status:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -374,8 +399,12 @@ app.get('/dast-website-target', function(req, res) {
## Scanner profile
-> - Deprecated AJAX Spider option with the introduction of Browser based on-demand DAST scans in GitLab 17.0.
-> - Renamed spider timeout to crawl timeout with the introduction of Browser based on-demand DAST scans in GitLab 17.0.
+{{< history >}}
+
+- Deprecated AJAX Spider option with the introduction of Browser based on-demand DAST scans in GitLab 17.0.
+- Renamed spider timeout to crawl timeout with the introduction of Browser based on-demand DAST scans in GitLab 17.0.
+
+{{< /history >}}
A scanner profile defines the configuration details of a security scanner.
@@ -422,17 +451,20 @@ Prerequisites:
- If a DAST scan uses the profile, you must be able to push to the branch associated with the scan.
-NOTE:
+{{< alert type="note" >}}
+
If a scanner profile is linked to a security policy, you cannot edit the profile from this page.
For more information, see [Scan execution policies](../policies/scan_execution_policies.md).
+{{< /alert >}}
+
To edit a scanner profile:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > Security configuration**.
1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**.
1. Select the **Scanner profiles** tab.
-1. In the scanner's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**.
+1. In the scanner's row, select the **More actions** ({{< icon name="ellipsis_v" >}}) menu, then select **Edit**.
1. Edit the form.
1. Select **Save profile**.
@@ -442,17 +474,20 @@ Prerequisites:
- If a DAST scan uses the profile, you must be able to push to the branch associated with the scan.
-NOTE:
+{{< alert type="note" >}}
+
If a scanner profile is linked to a security policy, a user cannot delete the profile from this
page. For more information, see [Scan execution policies](../policies/scan_execution_policies.md).
+{{< /alert >}}
+
To delete a scanner profile:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > Security configuration**.
1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**.
1. Select the **Scanner profiles** tab.
-1. In the scanner's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**.
+1. In the scanner's row, select the **More actions** ({{< icon name="ellipsis_v" >}}) menu, then select **Delete**.
1. Select **Delete**.
## Auditing
diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md
index 3341af99e33c668866179765e82ab89968ebda54..150eba2d5bc28dd1455c9022b9f27e91cf6dd6f3 100644
--- a/doc/user/application_security/dast/proxy-based.md
+++ b/doc/user/application_security/dast/proxy-based.md
@@ -1,15 +1,18 @@
---
+redirect_to: proxy_based_to_browser_based_migration_guide.md
+remove_date: "2025-02-15"
stage: Application Security Testing
group: Dynamic Analysis
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
-remove_date: '2025-02-15'
-redirect_to: 'proxy_based_to_browser_based_migration_guide.md'
title: DAST proxy-based analyzer (removed)
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966) in GitLab 16.9
and removed in 17.3. Use [DAST version 5](proxy_based_to_browser_based_migration_guide.md) instead.
diff --git a/doc/user/application_security/dast/proxy_based_to_browser_based_migration_guide.md b/doc/user/application_security/dast/proxy_based_to_browser_based_migration_guide.md
index a4e7147212fc34503308f40347177593278d00ce..8c85566ec0ba1cdef7bb4258ba54cc9e8b88324c 100644
--- a/doc/user/application_security/dast/proxy_based_to_browser_based_migration_guide.md
+++ b/doc/user/application_security/dast/proxy_based_to_browser_based_migration_guide.md
@@ -5,7 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from the DAST proxy-based analyzer to DAST version 5
---
-> - The [DAST proxy-based analyzer](proxy-based.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966) in GitLab 16.6 and removed in 17.0.
+{{< history >}}
+
+- The [DAST proxy-based analyzer](proxy-based.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966) in GitLab 16.6 and removed in 17.0.
+
+{{< /history >}}
[DAST version 5](browser/_index.md) replaces the proxy-based analyzer with a browser-based analyzer. This document serves as a guide to
migrate from the proxy-based analyzer to DAST version 5.
diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md
index 07dd1643b76b7f4975c5a63c64541742ba2d67c2..cabc06164dff68b1401b14801c2e6dee073ebf15 100644
--- a/doc/user/application_security/dast/run_dast_offline.md
+++ b/doc/user/application_security/dast/run_dast_offline.md
@@ -1,15 +1,18 @@
---
+redirect_to: proxy_based_to_browser_based_migration_guide.md
+remove_date: "2025-02-15"
stage: Application Security Testing
group: Dynamic Analysis
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
-remove_date: '2025-02-15'
-redirect_to: 'proxy_based_to_browser_based_migration_guide.md'
title: Run DAST in an offline environment (removed)
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966) in GitLab 16.9
and [removed](https://gitlab.com/groups/gitlab-org/-/epics/11986) in 17.3.
diff --git a/doc/user/application_security/dependency_list/_index.md b/doc/user/application_security/dependency_list/_index.md
index c9e6e473076d2ba0bfacbc8fab8f233b8af640b6..e15d84d609ed0ba05c7c1036be85195188775ef9 100644
--- a/doc/user/application_security/dependency_list/_index.md
+++ b/doc/user/application_security/dependency_list/_index.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dependency list
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Group-level dependency list [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8090) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies`. Disabled by default.
-> - Group-level dependency list [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/411257) in GitLab 16.4.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132015) in GitLab 16.5. Feature flag `group_level_dependencies` removed.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Group-level dependency list [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8090) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies`. Disabled by default.
+- Group-level dependency list [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/411257) in GitLab 16.4.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132015) in GitLab 16.5. Feature flag `group_level_dependencies` removed.
+
+{{< /history >}}
Use the dependency list to review your project or group's dependencies and key details about those
dependencies, including their known vulnerabilities. This list is a collection of dependencies in your
@@ -28,10 +35,13 @@ To list your project's dependencies the SBOM document must:
- Comply with [the CycloneDX specification](https://github.com/CycloneDX/specification) version `1.4`, `1.5`, or `1.6`. Online validator available on [CycloneDX Web Tool](https://cyclonedx.github.io/cyclonedx-web-tool/validate).
- Be uploaded as [a CI/CD artifact report](../../../ci/yaml/artifacts_reports.md#artifactsreportscyclonedx) from a successful pipeline on the default branch.
-NOTE:
+{{< alert type="note" >}}
+
Although this is not mandatory for populating the dependency list, the SBOM document must include and comply with the
[GitLab CycloneDX property taxonomy](../../../development/sec/cyclonedx_property_taxonomy.md) to provide some properties and to enable some security features.
+{{< /alert >}}
+
GitLab already generates this document when the following requirements are met:
- The [Dependency Scanning](../dependency_scanning/_index.md)
@@ -46,8 +56,12 @@ GitLab already generates this document when the following requirements are met:
## View project dependencies
-> - In GitLab 17.2, the `location` field no longer links to the commit where the dependency was last detected when the feature flag `skip_sbom_occurrences_update_on_pipeline_id_change` is enabled. The flag is disabled by default.
-> - In GitLab 17.3 the `location` field always links to the commit where the dependency was first detected. Feature flag `skip_sbom_occurrences_update_on_pipeline_id_change` removed.
+{{< history >}}
+
+- In GitLab 17.2, the `location` field no longer links to the commit where the dependency was last detected when the feature flag `skip_sbom_occurrences_update_on_pipeline_id_change` is enabled. The flag is disabled by default.
+- In GitLab 17.3 the `location` field always links to the commit where the dependency was first detected. Feature flag `skip_sbom_occurrences_update_on_pipeline_id_change` removed.
+
+{{< /history >}}
To view the dependencies of a project or all projects in a group:
@@ -68,9 +82,13 @@ Details of each dependency are listed, sorted by decreasing severity of vulnerab
## Filter dependency list
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422356) dependency filtering for groups in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies_filtering`. Disabled by default.
-> - Dependency filtering for group [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/422356) in GitLab 16.10. Feature flag `group_level_dependencies_filtering` removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/513320) dependency filtering for projects in GitLab 17.9 with a flag named [`project_component_filter`](../../../administration/feature_flags.md). Enabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422356) dependency filtering for groups in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies_filtering`. Disabled by default.
+- Dependency filtering for group [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/422356) in GitLab 16.10. Feature flag `group_level_dependencies_filtering` removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/513320) dependency filtering for projects in GitLab 17.9 with a flag named [`project_component_filter`](../../../administration/feature_flags.md). Enabled by default.
+
+{{< /history >}}
You can filter the dependency list to focus on only a subset of dependencies. The dependency
list is available for groups and projects.
@@ -87,7 +105,7 @@ For projects, you can filter by:
To filter the dependency list:
-1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group or project.
+1. On the left sidebar, at the top, select **Search GitLab** ({{< icon name="search" >}}) to find your group or project.
1. Select **Secure > Dependency list**.
1. Select the filter bar.
1. Select a filter, then from the dropdown list select one or more criteria.
@@ -98,12 +116,19 @@ The dependency list shows only dependencies that match your filters.
## Vulnerabilities
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/500551) in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `update_sbom_occurrences_vulnerabilities_on_cvs`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/500551) in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `update_sbom_occurrences_vulnerabilities_on_cvs`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of support for vulnerabilities associated with [SBOM-based dependency scanning](../dependency_scanning/dependency_scanning_sbom/_index.md) is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
If a dependency has known vulnerabilities, view them by selecting the arrow next to the
dependency's name or the badge that indicates how many known vulnerabilities exist. For each
vulnerability, its severity and description appears below it. To view more details of a vulnerability,
@@ -111,15 +136,22 @@ select the vulnerability's description. The [vulnerability's details](../vulnera
## Dependency paths
-> - Dependency path information from CycloneDX SBOM was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393061) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `project_level_sbom_occurrences`. Disabled by default.
-> - Dependency path information from CycloneDX SBOM was [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/434371) in GitLab 17.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/457633) in GitLab 17.4. Feature flag `project_level_sbom_occurrences` removed.
+{{< history >}}
+
+- Dependency path information from CycloneDX SBOM was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393061) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `project_level_sbom_occurrences`. Disabled by default.
+- Dependency path information from CycloneDX SBOM was [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/434371) in GitLab 17.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/457633) in GitLab 17.4. Feature flag `project_level_sbom_occurrences` removed.
+
+{{< /history >}}
The dependency list shows the direct dependents of a listed component if the component is transient and belongs to any supported package manager.
-NOTE:
+{{< alert type="note" >}}
+
The dependency path is only displayed for dependencies that have vulnerabilities.
+{{< /alert >}}
+
Dependency paths are supported for the following package managers:
diff --git a/doc/user/application_security/dependency_scanning/_index.md b/doc/user/application_security/dependency_scanning/_index.md
index 3c278f4e2b32026150e1de5768f289a83486496a..910a6522d2cd237e0e4c79bcbf65e8600ae3186a 100644
--- a/doc/user/application_security/dependency_scanning/_index.md
+++ b/doc/user/application_security/dependency_scanning/_index.md
@@ -42,16 +42,22 @@ table.no-vertical-table-lines tr {
}
</style>
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Dependency Scanning feature based on the Gemnasium analyzer is deprecated in GitLab 17.9 and reaches
end of support in GitLab 18.0. It is replaced with [Dependency Scanning using SBOM](dependency_scanning_sbom/_index.md)
and the [new Dependency Scanning analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning).
For more information, see [issue 501038](https://gitlab.com/gitlab-org/gitlab/-/issues/501308).
+{{< /alert >}}
+
Dependency Scanning analyzes your application's dependencies for known vulnerabilities. All
dependencies are scanned, including transitive dependencies, also known as nested dependencies.
@@ -74,9 +80,12 @@ we encourage you to use all of our security scanners. For a comparison of these
-WARNING:
+{{< alert type="warning" >}}
+
Dependency Scanning does not support runtime installation of compilers and interpreters.
+{{< /alert >}}
+
- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Dependency Scanning](https://www.youtube.com/watch?v=TBnfbGk4c4o)
- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
@@ -643,10 +652,13 @@ A maximum of two directory levels from the repository's root is searched. For ex
### How multiple files are processed
-NOTE:
+{{< alert type="note" >}}
+
If you've run into problems while scanning multiple files, contribute a comment to
[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337056).
+{{< /alert >}}
+
#### Python
We only execute one installation in the directory where either a requirements file or a lock file has been detected. Dependencies are only analyzed by `gemnasium-python` for the first file that is detected. Files are searched for in the following order:
@@ -735,11 +747,14 @@ To enable the analyzer, either:
This method automatically prepares a merge request that includes the Dependency Scanning template
in the `.gitlab-ci.yml` file. You then merge the merge request to enable Dependency Scanning.
-NOTE:
+{{< alert type="note" >}}
+
This method works best with no existing `.gitlab-ci.yml` file, or with a minimal configuration file.
If you have a complex GitLab configuration file it might not be parsed successfully, and an error
might occur. In that case, use the [manual](#edit-the-gitlab-ciyml-file-manually) method instead.
+{{< /alert >}}
+
To enable Dependency Scanning:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -784,8 +799,12 @@ Pipelines now include a Dependency Scanning job.
#### Use CI/CD components
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/454143) in GitLab 17.0. This feature is an [experiment](../../../policy/development_stages_support.md).
-> - The dependency scanning CI/CD component only supports Android projects.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/454143) in GitLab 17.0. This feature is an [experiment](../../../policy/development_stages_support.md).
+- The dependency scanning CI/CD component only supports Android projects.
+
+{{< /history >}}
Use [CI/CD components](../../../ci/components/_index.md) to perform Dependency Scanning of your
application. For instructions, see the respective component's README file.
@@ -802,11 +821,14 @@ See [Use security scanning tools with merge request pipelines](../detect/roll_ou
To customize Dependency Scanning, use [CI/CD variables](#available-cicd-variables).
-WARNING:
+{{< alert type="warning" >}}
+
Test all customization of GitLab analyzers in a merge request before merging these changes to the
default branch. Failure to do so can give unexpected results, including a large number of false
positives.
+{{< /alert >}}
+
### Overriding dependency scanning jobs
To override a job definition (for example, to change properties like `variables` or `dependencies`),
@@ -894,9 +916,12 @@ variables:
HTTPS_PROXY: "https://squid-proxy:3128"
```
-NOTE:
+{{< alert type="note" >}}
+
Gradle projects require [an additional variable](#using-a-proxy-with-gradle-projects) setup to use a proxy.
+{{< /alert >}}
+
Alternatively we may use it in specific jobs, like Dependency Scanning:
```yaml
@@ -980,7 +1005,11 @@ To authenticate with a private Maven repository:
### FIPS-enabled images
-> - Introduced in GitLab 15.0 - Gemnasium uses FIPS-enabled images when FIPS mode is enabled.
+{{< history >}}
+
+- Introduced in GitLab 15.0 - Gemnasium uses FIPS-enabled images when FIPS mode is enabled.
+
+{{< /history >}}
GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image)
versions of the Gemnasium images. When FIPS mode is enabled in the GitLab instance, Gemnasium
@@ -1097,9 +1126,12 @@ You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security
## Offline environment
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
For instances in an environment with limited, restricted, or intermittent access
to external resources through the internet, some adjustments are required for dependency scanning
diff --git a/doc/user/application_security/dependency_scanning/dependency_scanning_sbom/_index.md b/doc/user/application_security/dependency_scanning/dependency_scanning_sbom/_index.md
index 56b22d6d38a7739d77041c1e3d48e2c095d8891f..07ecc1b1c4f48c9ad7679a031d3009b753e92e8d 100644
--- a/doc/user/application_security/dependency_scanning/dependency_scanning_sbom/_index.md
+++ b/doc/user/application_security/dependency_scanning/dependency_scanning_sbom/_index.md
@@ -5,22 +5,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dependency scanning by using SBOM
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/395692) in GitLab 17.1 and officially released in GitLab 17.3 with a flag named `dependency_scanning_using_sbom_reports`.
-> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/395692) in GitLab 17.5.
-> - Released [lockfile-based Dependency Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning/-/blob/main/README.md?ref_type=heads#supported-files) analyzer as an [Experiment](../../../../policy/development_stages_support.md#experiment-features) in GitLab 17.4.
-> - Released [Dependency Scanning CI/CD Component](https://gitlab.com/explore/catalog/components/dependency-scanning) version [`0.4.0`](https://gitlab.com/components/dependency-scanning/-/tags/0.4.0) in GitLab 17.5 with support for the [lockfile-based Dependency Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning/-/blob/main/README.md?ref_type=heads#supported-files) analyzer.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/395692) in GitLab 17.1 and officially released in GitLab 17.3 with a flag named `dependency_scanning_using_sbom_reports`.
+- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/395692) in GitLab 17.5.
+- Released [lockfile-based Dependency Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning/-/blob/main/README.md?ref_type=heads#supported-files) analyzer as an [Experiment](../../../../policy/development_stages_support.md#experiment-features) in GitLab 17.4.
+- Released [Dependency Scanning CI/CD Component](https://gitlab.com/explore/catalog/components/dependency-scanning) version [`0.4.0`](https://gitlab.com/components/dependency-scanning/-/tags/0.4.0) in GitLab 17.5 with support for the [lockfile-based Dependency Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning/-/blob/main/README.md?ref_type=heads#supported-files) analyzer.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature uses an experimental scanner.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Dependency scanning using CycloneDX SBOM analyzes your application's dependencies for known
vulnerabilities. All dependencies are scanned, [including transitive dependencies](../_index.md).
@@ -406,12 +416,15 @@ The following CycloneDX SBOMs are created as job artifacts:
You can use a CI/CD job to merge the multiple CycloneDX SBOMs into a single SBOM.
-NOTE:
+{{< alert type="note" >}}
+
GitLab uses [CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store)
to store implementation-specific details in the metadata of each CycloneDX SBOM, such as the
location of dependency graph exports and lock files. If multiple CycloneDX SBOMs are merged together,
this information is removed from the resulting merged file.
+{{< /alert >}}
+
For example, the following `.gitlab-ci.yml` extract demonstrates how the Cyclone SBOM files can be
merged, and the resulting file validated.
diff --git a/doc/user/application_security/dependency_scanning/experiment_libbehave_dependency.md b/doc/user/application_security/dependency_scanning/experiment_libbehave_dependency.md
index f635688139bbc5f83f5786817262714134c14cca..fe1327f872668e66a62db91dab47f53d51ca07dc 100644
--- a/doc/user/application_security/dependency_scanning/experiment_libbehave_dependency.md
+++ b/doc/user/application_security/dependency_scanning/experiment_libbehave_dependency.md
@@ -5,10 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Analyze dependency for behaviors
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
Libbehave is an experimental feature that scans your dependencies during merge request pipelines to
identify newly added libraries and their potentially risky behaviors. While traditional dependency
diff --git a/doc/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.md b/doc/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.md
index 679eae909b4878b1ea8d381acb90e37474c79b40..1d86ec8eb7f44a42182618211f4b035d83fe099e 100644
--- a/doc/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.md
+++ b/doc/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.md
@@ -2,11 +2,14 @@
stage: Application Security Testing
group: Composition Analysis
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
+title: Migrating to Dependency Scanning using SBOM
---
-# Migrating to Dependency Scanning using SBOM
+{{< history >}}
-> - The legacy [Dependency Scanning feature based on the Gemnasium analyzer](_index.md) was [deprecated](../../../update/deprecations.md#dependency-scanning-upgrades-to-the-gitlab-sbom-vulnerability-scanner) in GitLab 17.9 and planned for removal in 18.0.
+- The legacy [Dependency Scanning feature based on the Gemnasium analyzer](_index.md) was [deprecated](../../../update/deprecations.md#dependency-scanning-upgrades-to-the-gitlab-sbom-vulnerability-scanner) in GitLab 17.9 and planned for removal in 18.0.
+
+{{< /history >}}
The Dependency Scanning feature is upgrading to the GitLab SBOM Vulnerability Scanner.
As part of this change, the [Dependency Scanning using SBOM](dependency_scanning_sbom/_index.md) feature and the [new Dependency Scanning analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning)
@@ -89,9 +92,12 @@ To migrate to the Dependency Scanning using SBOM method, perform the following s
For multi-language projects, complete all relevant language-specific migration steps.
-NOTE:
+{{< alert type="note" >}}
+
If you decide to migrate from the CI/CD template to the CI/CD component, please review the [current limitations](../../../ci/components/_index.md#use-a-gitlabcom-component-on-gitlab-self-managed) for GitLab Self-Managed.
+{{< /alert >}}
+
## Language-specific instructions
As you migrate to the new Dependency Scanning analyzer, you'll need to make specific adjustments based on your project's programming languages and package managers. These instructions apply whenever you use the new Dependency Scanning analyzer,
@@ -485,9 +491,12 @@ Keep the following CI/CD variables as they are applicable to the new Dependency
- `DS_MAX_DEPTH`
- `SECURE_ANALYZERS_PREFIX`
-NOTE:
+{{< alert type="note" >}}
+
The `PIP_REQUIREMENTS_FILE` is replaced with `DS_PIPCOMPILE_REQUIREMENTS_FILE_NAME_PATTERN` in the new Dependency Scanning analyzer.
+{{< /alert >}}
+
## Continue with the Gemnasium analyzer
While GitLab strongly encourages you to migrate to the new Dependency Scanning analyzer, you might need more time to plan and execute your migration.
diff --git a/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md b/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md
index 4993268f7327847934b00b07de9d05d8227ab084..487ebe1deebed0b315ca12560aa69481df8203e5 100644
--- a/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md
+++ b/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting Dependency Scanning
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with dependency scanning, you might encounter the following issues.
diff --git a/doc/user/application_security/detect/roll_out_security_scanning.md b/doc/user/application_security/detect/roll_out_security_scanning.md
index 96f4b32083473e0f3436298d6b53b9df5a8b2ea8..4c38fdfd27ace568a00d81fd92792ff04ad959b3 100644
--- a/doc/user/application_security/detect/roll_out_security_scanning.md
+++ b/doc/user/application_security/detect/roll_out_security_scanning.md
@@ -44,11 +44,14 @@ The behavior of each security scanner can be customized by using the
[predefined CD/CD variables](../../../ci/variables/predefined_variables.md) and each scanner's own
CI/CD variables. See each scanner's documentation for details of the CI/CD variables available.
-WARNING:
+{{< alert type="warning" >}}
+
All customization of security scanning tools should be tested in a merge request before merging
these changes to the default branch. Failure to do so can give unexpected results, including a large
number of false positives.
+{{< /alert >}}
+
### Template editions
Most of the GitLab application security tools have two template editions:
@@ -61,10 +64,13 @@ Most of the GitLab application security tools have two template editions:
include breaking changes that are planned for the next major release. This template allows you to
try new features and updates before they become part of the stable release.
-NOTE:
+{{< alert type="note" >}}
+
Mixing different security template editions can cause both merge request and branch pipelines to
run. You should use **either** the stable or latest edition templates in a project.
+{{< /alert >}}
+
### Override the default registry base address
By default, GitLab security scanners use `registry.gitlab.com/security-products` as the
diff --git a/doc/user/application_security/detect/security_scan_results.md b/doc/user/application_security/detect/security_scan_results.md
index 7781bf8d063ac52db072716e669216305036f6b5..51d1b8e2a837a47f7bb1390e07fc881269dd2191 100644
--- a/doc/user/application_security/detect/security_scan_results.md
+++ b/doc/user/application_security/detect/security_scan_results.md
@@ -19,9 +19,12 @@ efficient triaging, analysis, and remediation.
## Merge request
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Output of all enabled application security tools is shown in a merge request widget. You can use
this information to manage the risk of any issues identified in the source branch.
diff --git a/doc/user/application_security/gitlab_advisory_database/_index.md b/doc/user/application_security/gitlab_advisory_database/_index.md
index b83cb195d27b0efb9d5ce68c5528e13d888ab1c1..942d6d94a8701f2b5ab7d7d6a37a00173d37460a 100644
--- a/doc/user/application_security/gitlab_advisory_database/_index.md
+++ b/doc/user/application_security/gitlab_advisory_database/_index.md
@@ -51,9 +51,12 @@ The open-source version is a time-delayed clone of the GitLab Advisory Database,
- [Container Scanning](../container_scanning/_index.md)
- Third-party tools
-NOTE:
+{{< alert type="note" >}}
+
GitLab Advisory Database Terms prohibit the use of data contained in the GitLab Advisory Database by third-party tools. Third-party integrators can use the MIT-licensed, time-delayed [repository clone](https://gitlab.com/gitlab-org/advisories-community) instead.
+{{< /alert >}}
+
### How the database can be used
As an example, we highlight the use of the database as a source for an Advisory Ingestion process as part of Continuous Vulnerability Scans.
diff --git a/doc/user/application_security/iac_scanning/_index.md b/doc/user/application_security/iac_scanning/_index.md
index 1eb392b7bfdf0d8455cb2a2c540417f922f465c7..00876966348a8c295c1ecbb471bb7faccef12532 100644
--- a/doc/user/application_security/iac_scanning/_index.md
+++ b/doc/user/application_security/iac_scanning/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Infrastructure as Code scanning
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Infrastructure as Code (IaC) scanning runs in your CI/CD pipeline, checking your infrastructure
definition files for known vulnerabilities. Identify vulnerabilities before they're committed to
@@ -65,27 +68,36 @@ Supported configuration formats:
- AWS CloudFormation
- Azure Resource Manager
- NOTE:
- IaC scanning can analyze Azure Resource Manager templates in JSON format.
+ {{< alert type="note" >}}
+
+IaC scanning can analyze Azure Resource Manager templates in JSON format.
If you write templates in [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview),
you must use the [Bicep CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-cli) to
convert your Bicep files into JSON before IaC scanning can analyze them.
+ {{< /alert >}}
+
- Dockerfile
- Google Deployment Manager
- Kubernetes
- OpenAPI
- Terraform
- NOTE:
- Terraform modules in a custom registry are not scanned for vulnerabilities.
+ {{< alert type="note" >}}
+
+Terraform modules in a custom registry are not scanned for vulnerabilities.
For more information about the proposed feature, see [issue 357004](https://gitlab.com/gitlab-org/gitlab/-/issues/357004).
+ {{< /alert >}}
+
## Customize rules
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can customize the default IaC scanning rules provided with GitLab.
@@ -145,9 +157,12 @@ You can use [KICS annotations](https://docs.kics.io/latest/running-kics/#using_c
- To skip scanning an entire file, you can add `# kics-scan ignore` as a comment at the top of the file.
- To disable a specific rule in an entire file, you can add `# kics-scan disable=<kics_id>` as a comment at the top of the file.
-NOTE:
+{{< alert type="note" >}}
+
This feature is only available for some types of IaC files. See the [KICS documentation](https://docs.kics.io/latest/running-kics/#using_commands_on_scanned_files_as_comments) for a list of supported file types.
+{{< /alert >}}
+
### Override rules
You can override specific IaC scanning rules to customize them. For example, assign a rule a lower
@@ -184,9 +199,12 @@ In the following example `sast-ruleset.toml` file, rules are matched by the `typ
### Offline configuration
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
An offline environment has limited, restricted, or intermittent access to external resources through
the internet. For instances in such an environment, IaC requires
@@ -250,10 +268,13 @@ To use a specific analyzer version:
1. Add the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable, after the line that includes the
`SAST-IaC.gitlab-ci.yml` template.
- NOTE:
+ {{< alert type="note" >}}
+
Only set this variable in a specific job. If you set it at the top level, the version you set is
used for other SAST analyzers.
+ {{< /alert >}}
+
Set the tag to:
- A major version, like `3`. Your pipelines use any minor or patch updates that are released in this major version.
@@ -295,8 +316,12 @@ include:
## Automatic vulnerability resolution
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/375128) in GitLab 16.2. Feature flag `sec_mark_dropped_findings_as_resolved` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/375128) in GitLab 16.2. Feature flag `sec_mark_dropped_findings_as_resolved` removed.
+
+{{< /history >}}
To help you focus on the vulnerabilities that are still relevant, IaC scanning automatically
[resolves](../vulnerabilities/_index.md#vulnerability-status-values) vulnerabilities when:
diff --git a/doc/user/application_security/offline_deployments/_index.md b/doc/user/application_security/offline_deployments/_index.md
index 4b7913ba786267927abdcee442ec2e992fe3e46e..88c69c293110422d62bcabbeacc43add1b040f41 100644
--- a/doc/user/application_security/offline_deployments/_index.md
+++ b/doc/user/application_security/offline_deployments/_index.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Offline environments
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
To set up an offline environment, you must receive an [opt-out exemption of cloud licensing](https://about.gitlab.com/pricing/licensing-faq/cloud-licensing/#offline-cloud-licensing) prior to purchase. For more details, contact your GitLab sales representative.
+{{< /alert >}}
+
It's possible to run most of the GitLab security scanners when not connected to the internet.
This document describes how to operate Secure Categories (that is, scanner types) in an offline
@@ -135,10 +141,13 @@ This method requires a runner with access to both `gitlab.com` (including
to be able to use the `docker` command inside the jobs. This runner can be installed in a DMZ or on
a bastion, and used only for this specific project.
-WARNING:
+{{< alert type="warning" >}}
+
This template does not include updates for the container scanning analyzer. See
[Container scanning offline directions](../container_scanning/_index.md#running-container-scanning-in-an-offline-environment).
+{{< /alert >}}
+
#### Scheduling the updates
By default, this project's pipeline runs only once, when the `.gitlab-ci.yml` is added to the
diff --git a/doc/user/application_security/policies/_index.md b/doc/user/application_security/policies/_index.md
index 2fc3e411b732a8bf3eaaa25e003a02b0396e9401..5024c33502df6d5cd7af9059b37e70f39d650659 100644
--- a/doc/user/application_security/policies/_index.md
+++ b/doc/user/application_security/policies/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Policies
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Policies provide security and compliance teams with a way to enforce controls globally in
their organization.
@@ -52,13 +55,20 @@ may require up to 10 minutes before the policy changes take effect.
## Deleting security policy projects
-> - The deletion protection for security policy projects was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/482967) in GitLab 17.8 [with a flag](../../../administration/feature_flags.md) named `reject_security_policy_project_deletion`. Disabled by default.
-> - The deletion protection for groups that contain security policy projects was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/512043) in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `reject_security_policy_project_deletion_groups`. Disabled by default.
+{{< history >}}
+
+- The deletion protection for security policy projects was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/482967) in GitLab 17.8 [with a flag](../../../administration/feature_flags.md) named `reject_security_policy_project_deletion`. Disabled by default.
+- The deletion protection for groups that contain security policy projects was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/512043) in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `reject_security_policy_project_deletion_groups`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
To delete a security policy project or one of its parent groups, you must remove the link to it
from all other projects or groups. Otherwise, an error message is displayed when you attempt
to delete a linked security policy project or a parent group.
@@ -96,11 +106,14 @@ Policies enforced on an existing group or subgroup are automatically enforced in
- The new subgroups and projects are included in the scope definition of the policy (for example, the scope includes all projects in this group).
- The existing group or subgroup is already linked to the security policy project.
-NOTE:
+{{< alert type="note" >}}
+
GitLab.com users can enforce policies against their top-level group or across subgroups, but cannot
enforce policies across GitLab.com top-level groups. GitLab Self-Managed administrators can enforce policies
across multiple top-level groups in their instance.
+{{< /alert >}}
+
The following example illustrates two groups and their structure:
- Alpha group contains two subgroups, each of which contains multiple projects.
@@ -138,9 +151,13 @@ Assuming no policies are enforced, consider the following examples:
#### Scope
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135398) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_policy_scope`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/443594) in GitLab 16.11. Feature flag `security_policies_policy_scope` removed.
-> - Scoping by group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468384) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135398) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_policy_scope`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/443594) in GitLab 16.11. Feature flag `security_policies_policy_scope` removed.
+- Scoping by group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468384) in GitLab 17.4.
+
+{{< /history >}}
You can refine a policy's scope by:
@@ -239,9 +256,9 @@ The Owner role and custom roles with the `manage_security_policy_link` permissio
| Organization unit | Group owner or group `manage_security_policy_link` permission | Subgroup owner or subgroup `manage_security_policy_link` permission | Project owner or project `manage_security_policy_link` permission |
|-------------------|---------------------------------------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
-| Group | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Subgroup | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| Project | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
+| Group | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Subgroup | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| Project | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
#### Required permissions
@@ -252,9 +269,12 @@ To create and manage security policies:
- You must be the project owner.
- You must be a group member with permissions to create projects in the group.
-NOTE:
+{{< alert type="note" >}}
+
If you're not a group member, you may face limitations in adding or editing policies for your project. The ability to create and manage policies requires permissions to create projects in the group. Make sure you have the required permissions in the group, even when working with project-level policies.
+{{< /alert >}}
+
## Policy implementation
Implementation options for security policy projects differ slightly between GitLab.com, GitLab
@@ -263,9 +283,12 @@ create subgroups. Ensuring separation of duties requires more granular permissio
### Enforce policies globally in your GitLab.com namespace
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Prerequisites:
@@ -309,9 +332,12 @@ The high-level workflow for enforcing policies globally across all subgroups and
### Enforce policies globally in GitLab Dedicated or GitLab Self-Managed
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
diff --git a/doc/user/application_security/policies/merge_request_approval_policies.md b/doc/user/application_security/policies/merge_request_approval_policies.md
index 245853b6149a9d3397d689c0300993d91b3a7794..c1bafe4f4f16399d406fe2672c5de09a70ef4c3b 100644
--- a/doc/user/application_security/policies/merge_request_approval_policies.md
+++ b/doc/user/application_security/policies/merge_request_approval_policies.md
@@ -5,16 +5,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Merge request approval policies
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Group-level scan result policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7622) in GitLab 15.6.
-> - Scan result policies feature was renamed to merge request approval policies in GitLab 16.9.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Group-level scan result policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7622) in GitLab 15.6.
+- Scan result policies feature was renamed to merge request approval policies in GitLab 16.9.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
Scan result policies feature was renamed to merge request approval policies in GitLab 16.9.
+{{< /alert >}}
+
You can use merge request approval policies for multiple purposes, including:
- Detect results from security and license scanners to enforce approval rules. For example, one type of merge request
@@ -23,9 +33,12 @@ findings of one or more security scan jobs. Merge request approval policies are
- Enforce approval rules on all merge requests that meet certain conditions. For example, enforce that MRs are reviewed by multiple users with Developer and Maintainer roles for all MRs that target default branches.
- Enforce settings for security and compliance on a project. For example, prevent users who have authored or committed changes to an MR from approving the MR. Or prevent users from pushing or force pushing to the default branch to ensure all changes go through an MR.
-NOTE:
+{{< alert type="note" >}}
+
When a protected branch is created or deleted, the policy approval rules synchronize, with a delay of 1 minute.
+{{< /alert >}}
+
The following video gives you an overview of GitLab merge request approval policies (previously scan result policies):
<div class="video-fallback">
@@ -72,11 +85,15 @@ following when implementing a merge request approval policy:
## Merge request with multiple pipelines
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379108) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `multi_pipeline_scan_result_policies`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/409482) in GitLab 16.3. Feature flag `multi_pipeline_scan_result_policies` removed.
-> - Support for parent-child pipelines [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428591) in GitLab 16.11 [with a flag](../../../administration/feature_flags.md) named `approval_policy_parent_child_pipeline`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/451597) in GitLab 17.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/428591) in GitLab 17.1. Feature flag `approval_policy_parent_child_pipeline` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379108) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `multi_pipeline_scan_result_policies`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/409482) in GitLab 16.3. Feature flag `multi_pipeline_scan_result_policies` removed.
+- Support for parent-child pipelines [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428591) in GitLab 16.11 [with a flag](../../../administration/feature_flags.md) named `approval_policy_parent_child_pipeline`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/451597) in GitLab 17.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/428591) in GitLab 17.1. Feature flag `approval_policy_parent_child_pipeline` removed.
+
+{{< /history >}}
A project can have multiple pipeline types configured. A single commit can initiate multiple
pipelines, each of which may contain a security scan.
@@ -92,12 +109,19 @@ For more information see [Use security scanning tools with merge request pipelin
## Merge request approval policy editor
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/369473) in GitLab 15.6.
+{{< history >}}
+
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/369473) in GitLab 15.6.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
Only project Owners have the [permissions](../../permissions.md#project-members-permissions)
to select Security Policy Project.
+{{< /alert >}}
+
Once your policy is complete, save it by selecting **Configure with a merge request** at the bottom of the
editor. This redirects you to the merge request on the project's configured security policy project.
If a security policy project doesn't link to your project, GitLab creates such a project for you.
@@ -110,18 +134,24 @@ before the policy changes take effect.
The [policy editor](_index.md#policy-editor) supports YAML mode and rule mode.
-NOTE:
+{{< alert type="note" >}}
+
Propagating merge request approval policies created for groups with a large number of projects take a while to complete.
+{{< /alert >}}
+
## Merge request approval policies schema
The YAML file with merge request approval policies consists of an array of objects matching the merge request approval
policy schema nested under the `approval_policy` key. You can configure a maximum of five policies under the `approval_policy` key.
-NOTE:
+{{< alert type="note" >}}
+
Merge request approval policies were defined under the `scan_result_policy` key. Until GitLab 17.0, policies can be
defined under both keys. Starting from GitLab 17.0, only `approval_policy` key is supported.
+{{< /alert >}}
+
When you save a new policy, GitLab validates its contents against [this JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/security_orchestration_policy.json).
If you're not familiar with how to read [JSON schemas](https://json-schema.org/),
the following sections and tables provide an alternative.
@@ -132,7 +162,11 @@ the following sections and tables provide an alternative.
## Merge request approval policy schema
-> - The `approval_settings` fields were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request`, or `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information.
+{{< history >}}
+
+- The `approval_settings` fields were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request`, or `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information.
+
+{{< /history >}}
| Field | Type | Required | Possible values | Description |
|---------------------|--------------------|----------|-----------------|----------------------------------------------------------|
@@ -148,10 +182,14 @@ the following sections and tables provide an alternative.
## `scan_finding` rule type
-> - The merge request approval policy field `vulnerability_attributes` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123052) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `enforce_vulnerability_attributes_rules`. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/418784) in GitLab 16.3. Feature flag removed.
-> - The merge request approval policy field `vulnerability_age` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123956) in GitLab 16.2.
-> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133753) in GitLab 16.5. Feature flag removed.
-> - The `vulnerability_states` option `newly_detected` was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/422414) in GitLab 17.0 and the options `new_needs_triage` and `new_dismissed` were added to replace it.
+{{< history >}}
+
+- The merge request approval policy field `vulnerability_attributes` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123052) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `enforce_vulnerability_attributes_rules`. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/418784) in GitLab 16.3. Feature flag removed.
+- The merge request approval policy field `vulnerability_age` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123956) in GitLab 16.2.
+- The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133753) in GitLab 16.5. Feature flag removed.
+- The `vulnerability_states` option `newly_detected` was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/422414) in GitLab 17.0 and the options `new_needs_triage` and `new_dismissed` were added to replace it.
+
+{{< /history >}}
This rule enforces the defined actions based on security scan findings.
@@ -170,9 +208,13 @@ This rule enforces the defined actions based on security scan findings.
## `license_finding` rule type
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `license_scanning_policies`.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/397644) in GitLab 15.11. Feature flag `license_scanning_policies` removed.
-> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133753) in GitLab 16.5. Feature flag removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `license_scanning_policies`.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/397644) in GitLab 15.11. Feature flag `license_scanning_policies` removed.
+- The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133753) in GitLab 16.5. Feature flag removed.
+
+{{< /history >}}
This rule enforces the defined actions based on license findings.
@@ -188,8 +230,12 @@ This rule enforces the defined actions based on license findings.
## `any_merge_request` rule type
-> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133753) in GitLab 16.5. Feature flag removed.
-> - The `any_merge_request` rule type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136298) in GitLab 16.6. Feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/432127).
+{{< history >}}
+
+- The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133753) in GitLab 16.5. Feature flag removed.
+- The `any_merge_request` rule type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136298) in GitLab 16.6. Feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/432127).
+
+{{< /history >}}
This rule enforces the defined actions for any merge request based on the commits signature.
@@ -206,9 +252,13 @@ This rule enforces the defined actions for any merge request based on the commit
This action sets an approval rule to be required when conditions are met for at least one rule in
the defined policy.
-> - [Added](https://gitlab.com/groups/gitlab-org/-/epics/12319) support for up to five separate `require_approval` actions in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `multiple_approval_actions`.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/505374) in GitLab 17.8. Feature flag `multiple_approval_actions` removed.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13550) support to specify custom roles as `role_approvers` in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `security_policy_custom_roles`. Enabled by default.
+{{< history >}}
+
+- [Added](https://gitlab.com/groups/gitlab-org/-/epics/12319) support for up to five separate `require_approval` actions in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `multiple_approval_actions`.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/505374) in GitLab 17.8. Feature flag `multiple_approval_actions` removed.
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13550) support to specify custom roles as `role_approvers` in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `security_policy_custom_roles`. Enabled by default.
+
+{{< /history >}}
| Field | Type | Required | Possible values | Description |
|-------|------|----------|-----------------|-------------|
@@ -222,12 +272,16 @@ the defined policy.
## `send_bot_message` action type
-> - The `send_bot_message` action type was [introduced for projects](https://gitlab.com/gitlab-org/gitlab/-/issues/438269) in GitLab 16.11 [with a flag](../../../administration/feature_flags.md) named `approval_policy_disable_bot_comment`. Disabled by default.
-> - [Enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454852) in GitLab 17.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/454852) in GitLab 17.3. Feature flag `approval_policy_disable_bot_comment` removed.
-> - The `send_bot_message` action type was [introduced for groups](https://gitlab.com/gitlab-org/gitlab/-/issues/469449) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `approval_policy_disable_bot_comment_group`. Disabled by default.
-> - [Enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/469449) in GitLab 17.2.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/469449) in GitLab 17.3. Feature flag `approval_policy_disable_bot_comment_group` removed.
+{{< history >}}
+
+- The `send_bot_message` action type was [introduced for projects](https://gitlab.com/gitlab-org/gitlab/-/issues/438269) in GitLab 16.11 [with a flag](../../../administration/feature_flags.md) named `approval_policy_disable_bot_comment`. Disabled by default.
+- [Enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454852) in GitLab 17.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/454852) in GitLab 17.3. Feature flag `approval_policy_disable_bot_comment` removed.
+- The `send_bot_message` action type was [introduced for groups](https://gitlab.com/gitlab-org/gitlab/-/issues/469449) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `approval_policy_disable_bot_comment_group`. Disabled by default.
+- [Enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/469449) in GitLab 17.2.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/469449) in GitLab 17.3. Feature flag `approval_policy_disable_bot_comment_group` removed.
+
+{{< /history >}}
This action enables configuration of the bot message in merge requests when policy violations are detected.
If the action is not specified, the bot message is enabled by default. If there are multiple policies defined,
@@ -246,28 +300,36 @@ the bot message is sent as long as at least one of those policies has the `send_
## Warn mode
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/15552) in GitLab 17.8 [with a flag](../../../administration/feature_flags.md) named `security_policy_approval_warn_mode`. Disabled by default
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/15552) in GitLab 17.8 [with a flag](../../../administration/feature_flags.md) named `security_policy_approval_warn_mode`. Disabled by default
+
+{{< /history >}}
When warn mode is enabled and a merge request triggers a security policy that doesn't require any additional approvers, a bot comment is added to the merge request. The comment directs users to the policy for more information.
## `approval_settings`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420724) the `block_group_branch_modification` field in GitLab 16.8 [with flag](../../../administration/feature_flags.md) named `scan_result_policy_block_group_branch_modification`.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/437306) in GitLab 17.6.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/503930) in GitLab 17.7. Feature flag `scan_result_policy_block_group_branch_modification` removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423101) the `block_unprotecting_branches` field in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policy_settings`. Disabled by default.
-> - The `scan_result_policy_settings` feature flag was replaced by the `scan_result_policies_block_unprotecting_branches` feature flag in 16.4.
-> - The `block_unprotecting_branches` field was [replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137153) by `block_branch_modification` field in GitLab 16.7.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/423901) in GitLab 16.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433415) in GitLab 16.11. Feature flag `scan_result_policies_block_unprotecting_branches` removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) the `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.6.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/432127) in GitLab 16.8. Feature flag `scan_result_any_merge_request` removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420629) the `prevent_pushing_and_force_pushing` field in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.6.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/432123) in GitLab 16.9. Feature flag `scan_result_policies_block_force_push` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420724) the `block_group_branch_modification` field in GitLab 16.8 [with flag](../../../administration/feature_flags.md) named `scan_result_policy_block_group_branch_modification`.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/437306) in GitLab 17.6.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/503930) in GitLab 17.7. Feature flag `scan_result_policy_block_group_branch_modification` removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423101) the `block_unprotecting_branches` field in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policy_settings`. Disabled by default.
+- The `scan_result_policy_settings` feature flag was replaced by the `scan_result_policies_block_unprotecting_branches` feature flag in 16.4.
+- The `block_unprotecting_branches` field was [replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137153) by `block_branch_modification` field in GitLab 16.7.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/423901) in GitLab 16.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433415) in GitLab 16.11. Feature flag `scan_result_policies_block_unprotecting_branches` removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) the `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.6.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/432127) in GitLab 16.8. Feature flag `scan_result_any_merge_request` removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420629) the `prevent_pushing_and_force_pushing` field in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.6.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/432123) in GitLab 16.9. Feature flag `scan_result_policies_block_force_push` removed.
+
+{{< /history >}}
The settings set in the policy overwrite settings in the project.
@@ -283,12 +345,19 @@ The settings set in the policy overwrite settings in the project.
## `fallback_behavior`
-> - The `fallback_behavior` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451784) in GitLab 17.0 [with a flag](../../../administration/feature_flags.md) named `security_scan_result_policies_unblock_fail_open_approval_rules`. Disabled by default.
-> - The `fallback_behavior` field was [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/groups/gitlab-org/-/epics/10816) in GitLab 17.0.
+{{< history >}}
+
+- The `fallback_behavior` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451784) in GitLab 17.0 [with a flag](../../../administration/feature_flags.md) named `security_scan_result_policies_unblock_fail_open_approval_rules`. Disabled by default.
+- The `fallback_behavior` field was [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/groups/gitlab-org/-/epics/10816) in GitLab 17.0.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default the `fallback_behavior` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_scan_result_policies_unblock_fail_open_approval_rules`. On GitLab.com and GitLab Dedicated, this feature is available.
+{{< /alert >}}
+
| Field | Type | Required | Possible values | Description |
|--------|----------|----------|--------------------|----------------------------------------------------------------------------------------------------------------------|
| `fail` | `string` | false | `open` or `closed` | `closed` (default): Invalid or unenforceable rules of a policy require approval. `open`: Invalid or unenforceable rules of a policy do not require approval. |
@@ -440,8 +509,12 @@ actions:
## Understanding merge request approval policy approvals
-> - The branch comparison logic for `scan_finding` was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/428518) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `scan_result_policy_merge_base_pipeline`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435297) in GitLab 16.9. Feature flag `scan_result_policy_merge_base_pipeline` removed.
+{{< history >}}
+
+- The branch comparison logic for `scan_finding` was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/428518) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `scan_result_policy_merge_base_pipeline`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435297) in GitLab 16.9. Feature flag `scan_result_policy_merge_base_pipeline` removed.
+
+{{< /history >}}
### Scope of merge request approval policy comparison
@@ -515,9 +588,12 @@ The **False Positive** attribute only applies to findings detected by our Vulner
### Merge request rules widget shows a merge request approval policy is invalid or duplicated
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
On GitLab Self-Managed from 15.0 to 16.4, the most likely cause is that the project was exported from a group and imported into another, and had merge request approval policy rules. These rules are stored in a separate project to the one that was exported. As a result, the project contains policy rules that reference entities that don't exist in the imported project's group. The result is policy rules that are invalid, duplicated, or both.
diff --git a/doc/user/application_security/policies/pipeline_execution_policies.md b/doc/user/application_security/policies/pipeline_execution_policies.md
index 94fe982cbe364fabc0f180fa23672d3a5c8b620b..a8d96d2823461b16f1fd84d212f3ab995a7369f3 100644
--- a/doc/user/application_security/policies/pipeline_execution_policies.md
+++ b/doc/user/application_security/policies/pipeline_execution_policies.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pipeline execution policies
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13266) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `pipeline_execution_policy_type`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/454278) in GitLab 17.3. Feature flag `pipeline_execution_policy_type` removed.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13266) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `pipeline_execution_policy_type`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/454278) in GitLab 17.3. Feature flag `pipeline_execution_policy_type` removed.
+
+{{< /history >}}
Use Pipeline execution policies to enforce CI/CD jobs for all applicable projects.
@@ -18,8 +25,12 @@ Use Pipeline execution policies to enforce CI/CD jobs for all applicable project
## Pipeline execution policies schema
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/159858) the `suffix` field in GitLab 17.4.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165096) pipeline execution so later stages wait for the `.pipeline-policy-pre` stage to complete in GitLab 17.7. [with a flag](../../../administration/feature_flags.md) named `ensure_pipeline_policy_pre_stage_complete`. Disabled by default.
+{{< history >}}
+
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/159858) the `suffix` field in GitLab 17.4.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165096) pipeline execution so later stages wait for the `.pipeline-policy-pre` stage to complete in GitLab 17.7. [with a flag](../../../administration/feature_flags.md) named `ensure_pipeline_policy_pre_stage_complete`. Disabled by default.
+
+{{< /history >}}
The YAML file with pipeline execution policies consists of an array of objects matching pipeline execution
policy schema nested under the `pipeline_execution_policy` key. You can configure a maximum of five
@@ -65,7 +76,11 @@ Note the following:
### Job naming best practice
-> - Naming conflict handling [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/473189) in GitLab 17.4.
+{{< history >}}
+
+- Naming conflict handling [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/473189) in GitLab 17.4.
+
+{{< /history >}}
There is no visible indicator for jobs coming from a security policy. Adding a unique prefix or suffix to job names makes it easier to identify them and avoid job name collisions.
@@ -106,12 +121,15 @@ Jobs defined in a pipeline execution policy can use any [stage](../../../ci/yaml
defined in the project's CI/CD configuration, also the reserved stages `.pipeline-policy-pre` and
`.pipeline-policy-post`.
-NOTE:
+{{< alert type="note" >}}
+
If your policy contains jobs only in the `.pre` and `.post` stages, the policy's pipeline is
evaluated as "empty" and so is not merged with the project's pipeline. To use `.pre` and `.post`
stages in a pipeline execution policy, you **must** include another job running in another stage
which is available on the project, for example `.pipeline-policy-pre`.
+{{< /alert >}}
+
When using the `inject_ci` [pipeline strategy](#pipeline-configuration-strategies), if a target project does not
contain its own `.gitlab-ci.yml` file, then the only stages available are the default pipeline
stages and the reserved stages.
@@ -169,7 +187,11 @@ Prerequisites:
### `skip_ci` type
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173480) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173480) in GitLab 17.7.
+
+{{< /history >}}
Pipeline execution policies offer control over who can use the `[skip ci]` directive. You can specify certain users or service accounts that are allowed to use `[skip ci]` while still ensuring critical security and compliance checks are performed.
@@ -194,7 +216,11 @@ Pipeline configuration strategy defines the method for merging the policy config
### `inject_policy`
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/475152) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/475152) in GitLab 17.9.
+
+{{< /history >}}
This strategy adds custom CI/CD configurations into the existing project pipeline without completely replacing the project's original CI/CD configuration. It is suitable when you want to enhance or extend the current pipeline with additional steps, such as adding new security scans, compliance checks, or custom scripts.
@@ -207,11 +233,14 @@ When using this strategy, a project CI/CD configuration cannot override any beha
For projects without a `.gitlab-ci.yml` file, this strategy creates `.gitlab-ci.yml` file
implicitly. The executed pipeline contains only the jobs defined in the pipeline execution policy.
-NOTE:
+{{< alert type="note" >}}
+
When a pipeline execution policy uses workflow rules that prevent policy jobs from running, the only jobs that
run are the project's CI/CD jobs. If the project uses workflow rules that prevent project CI/CD jobs from running,
the only jobs that run are the pipeline execution policy jobs.
+{{< /alert >}}
+
#### Stages injection
The stages for the policy pipeline follow the usual CI/CD configuration.
@@ -344,9 +373,12 @@ Special cases:
### `inject_ci` (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/475152) in GitLab 17.9. Use [`inject_policy`](#inject_policy) instead as it supports the enforcement of custom policy stages.
+{{< /alert >}}
+
This strategy adds custom CI/CD configurations into the existing project pipeline without completely replacing the project's original CI/CD configuration. It is suitable when you want to enhance or extend the current pipeline with additional steps, such as adding new security scans, compliance checks, or custom scripts.
Having multiple policies enabled injects all jobs additively.
@@ -357,14 +389,21 @@ For projects without a `.gitlab-ci.yml` file, this strategy will create the `.gi
implicitly. That is, a pipeline containing only the jobs defined in the pipeline execution policy is
executed.
-NOTE:
+{{< alert type="note" >}}
+
When a pipeline execution policy uses workflow rules that prevent policy jobs from running, the only jobs that
run are the project's CI/CD jobs. If the project uses workflow rules that prevent project CI/CD jobs from running,
the only jobs that run are the pipeline execution policy jobs.
+{{< /alert >}}
+
### `override_project_ci`
-> - Updated handling of workflow rules [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175088) in GitLab 17.8 [with a flag](../../../administration/feature_flags.md) named `policies_always_override_project_ci`. Enabled by default.
+{{< history >}}
+
+- Updated handling of workflow rules [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175088) in GitLab 17.8 [with a flag](../../../administration/feature_flags.md) named `policies_always_override_project_ci`. Enabled by default.
+
+{{< /history >}}
This strategy replaces the project's existing CI/CD configuration with a new one defined by the pipeline execution policy. This strategy is ideal when the entire pipeline needs to be standardized or replaced, like when you want to enforce organization-wide CI/CD standards or compliance requirements in a highly regulated industry. To override the pipeline configuration, define the CI/CD jobs and do not use `include:project`.
@@ -463,7 +502,8 @@ PolicyVariablesYAML -- "Inject <code>policy-job</code> if Test Stage exists" -->
ProjectVariablesYAML -- "Basis of the resulting pipeline" --> ResultingProjectVariablesYAML
```
-NOTE:
+{{< alert type="note" >}}
+
When a pipeline execution policy uses workflow rules that prevent policy jobs from running, the
project's original CI/CD configuration remains in effect instead of being overridden. You can
conditionally apply pipeline execution policies to control when the policy impacts the project's
@@ -473,6 +513,8 @@ is a merge request event. However, if the feature flag `policies_always_override
the workflow rules in the pipeline execution policy also override the project's original CI/CD configuration.
As a result, if workflow rules cause the pipeline execution policy to be filtered out, no pipeline is created.
+{{< /alert >}}
+
### Include a project's CI/CD configuration in the pipeline execution policy configuration
When using `override_project_ci` strategy, the project configuration can be included into the pipeline execution policy configuration:
diff --git a/doc/user/application_security/policies/scan_execution_policies.md b/doc/user/application_security/policies/scan_execution_policies.md
index 2d0023d845cb35220ef4991f9a38848e3f055d56..de4a801641568975443bcdade7cb6ae344addc15 100644
--- a/doc/user/application_security/policies/scan_execution_policies.md
+++ b/doc/user/application_security/policies/scan_execution_policies.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Scan execution policies
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Group-level security policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2.
-> - Group-level security policies [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4.
-> - Operational container scanning [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3410) in GitLab 15.5
-> - Support for custom CI variables in the Scan Execution Policies editor [introduced](https://gitlab.com/groups/gitlab-org/-/epics/9566) in GitLab 16.2.
-> - Enforcement of scan execution policies on projects with an existing GitLab CI/CD configuration [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6880) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `scan_execution_policy_pipelines`. Feature flag `scan_execution_policy_pipelines` removed in GitLab 16.5.
-> - Overriding predefined variables in scan execution policies [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440855) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `allow_restricted_variables_at_policy_level`. Enabled by default. Feature flag `allow_restricted_variables_at_policy_level` removed in GitLab 17.5.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Group-level security policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2.
+- Group-level security policies [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4.
+- Operational container scanning [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3410) in GitLab 15.5
+- Support for custom CI variables in the Scan Execution Policies editor [introduced](https://gitlab.com/groups/gitlab-org/-/epics/9566) in GitLab 16.2.
+- Enforcement of scan execution policies on projects with an existing GitLab CI/CD configuration [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6880) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `scan_execution_policy_pipelines`. Feature flag `scan_execution_policy_pipelines` removed in GitLab 16.5.
+- Overriding predefined variables in scan execution policies [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440855) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `allow_restricted_variables_at_policy_level`. Enabled by default. Feature flag `allow_restricted_variables_at_policy_level` removed in GitLab 17.5.
+
+{{< /history >}}
Use scan execution policies to enforce GitLab security scans based on the default or latest [security CI templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Jobs), either as part of the pipeline or on a
specified schedule.
@@ -76,13 +83,16 @@ before the policy changes take effect.
-NOTE:
+{{< alert type="note" >}}
+
Selection of site and scanner profiles using the rule mode editor for DAST execution policies differs based on
whether the policy is being created at the project or group level. For project-level policies the rule mode editor
presents a list of profiles to choose from that are already defined in the project. For group-level policies
you are required to type in the names of the profiles to use, and to prevent pipeline errors, profiles with
matching names must exist in all of the group's projects.
+{{< /alert >}}
+
## Scan execution policies schema
The YAML file with scan execution policies consists of an array of objects matching scan execution
@@ -100,12 +110,19 @@ the following sections and tables provide an alternative.
## Scan execution policy schema
-> - Limit of actions per policy [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/472213) in GitLab 17.4 [with flags](../../../administration/feature_flags.md) named `scan_execution_policy_action_limit` (for projects) and `scan_execution_policy_action_limit_group` (for groups). Disabled by default.
+{{< history >}}
+
+- Limit of actions per policy [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/472213) in GitLab 17.4 [with flags](../../../administration/feature_flags.md) named `scan_execution_policy_action_limit` (for projects) and `scan_execution_policy_action_limit_group` (for groups). Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the actions per policy limit is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
| Field | Type | Required | Description |
|----------------|----------------------------------------------|----------|-------------|
| `name` | `string` | true | Name of the policy. Maximum of 255 characters. |
@@ -118,7 +135,11 @@ For more information, see the history.
### `skip_ci` type
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/482952) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/482952) in GitLab 17.9.
+
+{{< /history >}}
Scan execution policies offer control over who can use the `[skip ci]` directive. You can specify certain users or service accounts that are allowed to use `[skip ci]` while still ensuring critical security and compliance checks are performed.
@@ -133,8 +154,12 @@ from bypassing the pipeline execution policies.
## `pipeline` rule type
-> - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Generally available in GitLab 16.2. Feature flag removed.
-> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Generally available in GitLab 16.5. Feature flag removed.
+{{< history >}}
+
+- The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Generally available in GitLab 16.2. Feature flag removed.
+- The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Generally available in GitLab 16.5. Feature flag removed.
+
+{{< /history >}}
This rule enforces the defined actions whenever the pipeline runs for a selected branch.
@@ -149,18 +174,25 @@ This rule enforces the defined actions whenever the pipeline runs for a selected
## `schedule` rule type
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) the `branch_type` field in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Generally available in GitLab 16.2. Feature flag removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) the `branch_exceptions` field in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Generally available in GitLab 16.5. Feature flag removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147691) a new `scan_execution_pipeline_worker` worker to scheduled scans to create pipelines in GitLab 16.11 [with a flag](../../../administration/feature_flags.md).
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152855) a new application setting `security_policy_scheduled_scans_max_concurrency` in GitLab 17.1. The concurrency limit applies when both the `scan_execution_pipeline_worker` and `scan_execution_pipeline_concurrency_control` are enabled.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158636) a concurrency limit for scan execution scheduled jobs in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `scan_execution_pipeline_concurrency_control`.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/451890) the `scan_execution_pipeline_worker` feature flag on GitLab.com in GitLab 17.5.
-> - [Feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/451890) `scan_execution_pipeline_worker` removed in GitLab 17.6.
-> - [Feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/463802) `scan_execution_pipeline_concurrency_control` removed in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) the `branch_type` field in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Generally available in GitLab 16.2. Feature flag removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) the `branch_exceptions` field in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Generally available in GitLab 16.5. Feature flag removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147691) a new `scan_execution_pipeline_worker` worker to scheduled scans to create pipelines in GitLab 16.11 [with a flag](../../../administration/feature_flags.md).
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152855) a new application setting `security_policy_scheduled_scans_max_concurrency` in GitLab 17.1. The concurrency limit applies when both the `scan_execution_pipeline_worker` and `scan_execution_pipeline_concurrency_control` are enabled.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158636) a concurrency limit for scan execution scheduled jobs in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `scan_execution_pipeline_concurrency_control`.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/451890) the `scan_execution_pipeline_worker` feature flag on GitLab.com in GitLab 17.5.
+- [Feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/451890) `scan_execution_pipeline_worker` removed in GitLab 17.6.
+- [Feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/463802) `scan_execution_pipeline_concurrency_control` removed in GitLab 17.9.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
In GitLab 16.1 and earlier, you should **not** use [direct transfer](../../../administration/settings/import_and_export_settings.md#enable-migration-of-groups-and-projects-by-direct-transfer) with scheduled scan execution policies. If using direct transfer, first upgrade to GitLab 16.2 and ensure security policy bots are enabled in the projects you are enforcing.
+{{< /alert >}}
+
Use the `schedule` rule type to run security scanners on a schedule.
A scheduled pipeline:
@@ -292,9 +324,12 @@ To optimize performance for projects at scale:
- You can configure the policy to run the schedules on runners with a specified `tag`. Consider setting up a dedicated runner in each project to handle schedules enforced from a policy to reduce impact to other runners.
- Test your implementation in a staging or lower environment before deploying to production. Monitor performance and adjust your rollout plan based on results.
-NOTE:
+{{< alert type="note" >}}
+
Additional improvements for managing high-volume scheduled pipelines are planned in [Epic 13977](https://gitlab.com/groups/gitlab-org/-/epics/13997).
+{{< /alert >}}
+
### Concurrency control
GitLab applies concurrency control when:
@@ -306,11 +341,15 @@ The concurrency control distributes the scheduled pipelines according to the [`t
## `scan` action type
-> - Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. [Feature flag removed in GitLab 16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/435727).
-> - Selection of security templates for given action (for projects) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415427) in GitLab 17.1 [with feature flag](../../../administration/feature_flags.md) named `scan_execution_policies_with_latest_templates`. Disabled by default.
-> - Selection of security templates for given action (for groups) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468981) in GitLab 17.2 [with feature flag](../../../administration/feature_flags.md) named `scan_execution_policies_with_latest_templates_group`. Disabled by default.
-> - Selection of security templates for given action (for projects and groups) was enabled on GitLab Self-Managed, and GitLab Dedicated ([1](https://gitlab.com/gitlab-org/gitlab/-/issues/461474), [2](https://gitlab.com/gitlab-org/gitlab/-/issues/468981)) in GitLab 17.2.
-> - Selection of security templates for given action (for projects and groups) was generally available in GitLab 17.3. Feature flags `scan_execution_policies_with_latest_templates` and `scan_execution_policies_with_latest_templates_group` removed.
+{{< history >}}
+
+- Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. [Feature flag removed in GitLab 16.8](https://gitlab.com/gitlab-org/gitlab/-/issues/435727).
+- Selection of security templates for given action (for projects) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415427) in GitLab 17.1 [with feature flag](../../../administration/feature_flags.md) named `scan_execution_policies_with_latest_templates`. Disabled by default.
+- Selection of security templates for given action (for groups) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468981) in GitLab 17.2 [with feature flag](../../../administration/feature_flags.md) named `scan_execution_policies_with_latest_templates_group`. Disabled by default.
+- Selection of security templates for given action (for projects and groups) was enabled on GitLab Self-Managed, and GitLab Dedicated ([1](https://gitlab.com/gitlab-org/gitlab/-/issues/461474), [2](https://gitlab.com/gitlab-org/gitlab/-/issues/468981)) in GitLab 17.2.
+- Selection of security templates for given action (for projects and groups) was generally available in GitLab 17.3. Feature flags `scan_execution_policies_with_latest_templates` and `scan_execution_policies_with_latest_templates_group` removed.
+
+{{< /history >}}
This action executes the selected `scan` with additional parameters when conditions for at least one
rule in the defined policy are met.
@@ -325,9 +364,12 @@ rule in the defined policy are met.
| `template` | `string` | `default`, `latest` | CI/CD template version to be enforced. The [`latest`](../../../development/cicd/templates.md#latest-version) version may introduce breaking changes. See the `stable` and `latest` [security templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Jobs). |
| `scan_settings` | `object` | | A set of scan settings, supplied as an array of `key: value` pairs, to apply and enforce for the selected scan. The `key` is the setting name, with its `value` provided as a boolean or string. This parameter supports the settings defined in [scan settings](#scan-settings). |
-NOTE:
+{{< alert type="note" >}}
+
If you have Merge Request Pipelines enabled for your project, you must select `template: latest` in your policy for each enforced scan. Using the latest template is crucial for compatibility with Merge Request Pipelines and allows you to take full advantage of GitLab security features. For more information on using security scanning tools with Merge Request Pipelines, please refer to our [security scanning documentation](../detect/roll_out_security_scanning.md#use-security-scanning-tools-with-merge-request-pipelines).
+{{< /alert >}}
+
### Scanner behavior
Some scanners behave differently in a `scan` action than they do in a regular CI/CD pipeline-based
diff --git a/doc/user/application_security/policies/vulnerability_management_policy.md b/doc/user/application_security/policies/vulnerability_management_policy.md
index a1e2073fdcb272984f05b66d125dd1604a63a717..d587bd0e8732e3ac9ddfa67eab32834cd52944d2 100644
--- a/doc/user/application_security/policies/vulnerability_management_policy.md
+++ b/doc/user/application_security/policies/vulnerability_management_policy.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Vulnerability management policy
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5708) support for enforcing policies on projects in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `vulnerability_management_policy_type`. Enabled by default.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/15697) support for enforcing policies on groups in GitLab 17.8 for the group-level [with a flag](../../../administration/feature_flags.md) named `vulnerability_management_policy_type_group`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178031) in GitLab 17.9. Feature flags `vulnerability_management_policy_type` and `vulnerability_management_policy_type_group` removed.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5708) support for enforcing policies on projects in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `vulnerability_management_policy_type`. Enabled by default.
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/15697) support for enforcing policies on groups in GitLab 17.8 for the group-level [with a flag](../../../administration/feature_flags.md) named `vulnerability_management_policy_type_group`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178031) in GitLab 17.9. Feature flags `vulnerability_management_policy_type` and `vulnerability_management_policy_type_group` removed.
+
+{{< /history >}}
Use a vulnerability management policy to automatically resolve vulnerabilities that are no longer
detected. This can help reduce the workload of triaging vulnerabilities.
diff --git a/doc/user/application_security/sast/_index.md b/doc/user/application_security/sast/_index.md
index b1ae1b3aa64aa5378d3213fbe2a1ded40993c487..6efcd605d8eebf1c1e9f5405f132e3982cfedcb3 100644
--- a/doc/user/application_security/sast/_index.md
+++ b/doc/user/application_security/sast/_index.md
@@ -42,9 +42,12 @@ table.no-vertical-table-lines tr {
}
</style>
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you're using [GitLab CI/CD](../../../ci/_index.md), you can use Static Application Security
Testing (SAST) to check your source code for known vulnerabilities. You can run SAST analyzers in
@@ -63,15 +66,15 @@ The following table lists the GitLab tiers in which each feature is available.
| Feature | In Free & Premium | In Ultimate |
|:-----------------------------------------------------------------------------------------|:-----------------------|:-----------------------|
-| Basic scanning with [open-source analyzers](#supported-languages-and-frameworks) | **{check-circle}** Yes | **{check-circle}** Yes |
-| Downloadable [SAST JSON report](#download-a-sast-report) | **{check-circle}** Yes | **{check-circle}** Yes |
-| Cross-file, cross-function scanning with [GitLab Advanced SAST](gitlab_advanced_sast.md) | **{dotted-circle}** No | **{check-circle}** Yes |
-| New findings in [merge request widget](#merge-request-widget) | **{dotted-circle}** No | **{check-circle}** Yes |
-| New findings in [merge request changes view](#merge-request-changes-view) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Vulnerability Management](../vulnerabilities/_index.md) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [UI-based scanner configuration](#configure-sast-by-using-the-ui) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Ruleset customization](customize_rulesets.md) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Advanced Vulnerability Tracking](#advanced-vulnerability-tracking) | **{dotted-circle}** No | **{check-circle}** Yes |
+| Basic scanning with [open-source analyzers](#supported-languages-and-frameworks) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Downloadable [SAST JSON report](#download-a-sast-report) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Cross-file, cross-function scanning with [GitLab Advanced SAST](gitlab_advanced_sast.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| New findings in [merge request widget](#merge-request-widget) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| New findings in [merge request changes view](#merge-request-changes-view) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Vulnerability Management](../vulnerabilities/_index.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [UI-based scanner configuration](#configure-sast-by-using-the-ui) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Ruleset customization](customize_rulesets.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Advanced Vulnerability Tracking](#advanced-vulnerability-tracking) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
## Requirements
@@ -140,9 +143,12 @@ To learn more about SAST analyzers that are no longer supported, see [Analyzers
## Advanced vulnerability tracking
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Source code is volatile; as developers make changes, source code may move within files or between files.
Security analyzers may have already reported vulnerabilities that are being tracked in the [Vulnerability Report](../vulnerability_report/_index.md).
@@ -169,9 +175,13 @@ For more information, see the confidential project `https://gitlab.com/gitlab-or
## Automatic vulnerability resolution
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`.
-> - Enabled by default in GitLab 15.10. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/375128) in GitLab 16.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`.
+- Enabled by default in GitLab 15.10. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/375128) in GitLab 16.2.
+
+{{< /history >}}
To help you focus on the vulnerabilities that are still relevant, GitLab SAST automatically [resolves](../vulnerabilities/_index.md#vulnerability-status-values) vulnerabilities when:
@@ -207,9 +217,12 @@ include:
A FIPS-compliant image is only available for the GitLab Advanced SAST and Semgrep-based analyzer.
-WARNING:
+{{< alert type="warning" >}}
+
To use SAST in a FIPS-compliant manner, you must [exclude other analyzers from running](analyzers.md#customize-analyzers). If you use a FIPS-enabled image to run Advanced SAST or Semgrep in [a runner with non-root user](https://docs.gitlab.com/runner/install/kubernetes_helm_chart_configuration.html#run-with-non-root-user), you must update the `run_as_user` attribute under `runners.kubernetes.pod_security_context` to use the ID of `gitlab` user [created by the image](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/a5d822401014f400b24450c92df93467d5bbc6fd/Dockerfile.fips#L58), which is `1000`.
+{{< /alert >}}
+
## Vulnerability details
SAST vulnerabilities are named according to the primary Common Weakness Enumeration (CWE) identifier for the discovered vulnerability.
@@ -230,9 +243,12 @@ For more information, see:
## View SAST results
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In Ultimate, the [SAST report file](#download-a-sast-report) is processed by GitLab and the details are shown in the UI:
@@ -260,9 +276,13 @@ The results are compared using [Advanced Vulnerability Tracking](#advanced-vulne
### Merge request changes view
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10959) in GitLab 16.6 with a [flag](../../../administration/feature_flags.md) named `sast_reports_in_inline_diff`. Disabled by default.
-> - Enabled by default in GitLab 16.8.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410191) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10959) in GitLab 16.6 with a [flag](../../../administration/feature_flags.md) named `sast_reports_in_inline_diff`. Disabled by default.
+- Enabled by default in GitLab 16.8.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410191) in GitLab 16.9.
+
+{{< /history >}}
SAST results display in the merge request **Changes** view. Lines containing SAST
issues are marked by a symbol beside the gutter. Select the symbol to see the list of issues, then select an issue to see its details.
@@ -332,17 +352,23 @@ The method you can use depends on your GitLab license tier.
#### Configure SAST with customizations
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410013) individual SAST analyzers configuration options from the UI in GitLab 16.2.
-NOTE:
+{{< alert type="note" >}}
+
The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal
configuration file. If you have a complex GitLab configuration file it may not be parsed
successfully, and an error may occur.
+{{< /alert >}}
+
To enable and configure SAST with customizations:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -361,11 +387,14 @@ Pipelines now include a SAST job.
#### Configure SAST with default settings only
-NOTE:
+{{< alert type="note" >}}
+
The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal
configuration file. If you have a complex GitLab configuration file it may not be parsed
successfully, and an error may occur.
+{{< /alert >}}
+
To enable and configure SAST with default settings:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -559,11 +588,14 @@ See [Use security scanning tools with merge request pipelines](../detect/roll_ou
SAST can be configured using the [`variables`](../../../ci/yaml/_index.md#variables) parameter in
`.gitlab-ci.yml`.
-WARNING:
+{{< alert type="warning" >}}
+
All customization of GitLab security scanning tools should be tested in a merge request before
merging these changes to the default branch. Failure to do so can give unexpected results,
including a large number of false positives.
+{{< /alert >}}
+
The following example includes the SAST template to override the `SEARCH_MAX_DEPTH`
variable to `10` in all jobs. The template is [evaluated before](../../../ci/yaml/_index.md#include) the pipeline
configuration, so the last mention of the variable takes precedence.
@@ -900,9 +932,12 @@ For more details see [Semgrep documentation](https://semgrep.dev/docs/ignoring-f
## Running SAST in an offline environment
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
For instances in an environment with limited, restricted, or intermittent access
to external resources through the internet, some adjustments are required for the SAST job to
diff --git a/doc/user/application_security/sast/advanced_sast_coverage.md b/doc/user/application_security/sast/advanced_sast_coverage.md
index 01e758df006687d5463fea5bd5038b8e1b8c11e0..53be00ee50ae852a99462fe2eac480883a52d612 100644
--- a/doc/user/application_security/sast/advanced_sast_coverage.md
+++ b/doc/user/application_security/sast/advanced_sast_coverage.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Advanced SAST CWE coverage
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[GitLab Advanced SAST](gitlab_advanced_sast.md) finds many types of potential security vulnerabilities in code written in [supported languages](gitlab_advanced_sast.md#supported-languages).
@@ -30,94 +33,97 @@ GitLab Advanced SAST finds the following types of weaknesses in each programming
| CWE | CWE Description | C# | Go | Java | JavaScript, TypeScript | Python | Ruby |
|:-------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-----------------------|:-----------------------|:-----------------------|
-| [CWE-15](https://cwe.mitre.org/data/definitions/15.html) | External Control of System or Configuration Setting | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-22](https://cwe.mitre.org/data/definitions/22.html) | Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal') | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-23](https://cwe.mitre.org/data/definitions/23.html) | Relative Path Traversal | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-73](https://cwe.mitre.org/data/definitions/73.html) | External Control of File Name or Path | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-76](https://cwe.mitre.org/data/definitions/76.html) | Improper Neutralization of Equivalent Special Elements | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-77](https://cwe.mitre.org/data/definitions/77.html) | Improper Neutralization of Special Elements used in a Command ('Command Injection') | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-78](https://cwe.mitre.org/data/definitions/78.html) | Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection') | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-79](https://cwe.mitre.org/data/definitions/79.html) | Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting') | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-80](https://cwe.mitre.org/data/definitions/80.html) | Improper Neutralization of Script-Related HTML Tags in a Web Page (Basic XSS) | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-88](https://cwe.mitre.org/data/definitions/88.html) | Improper Neutralization of Argument Delimiters in a Command ('Argument Injection') | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-89](https://cwe.mitre.org/data/definitions/89.html) | Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection') | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-90](https://cwe.mitre.org/data/definitions/90.html) | Improper Neutralization of Special Elements used in an LDAP Query ('LDAP Injection') | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-91](https://cwe.mitre.org/data/definitions/91.html) | XML Injection (aka Blind XPath Injection) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-94](https://cwe.mitre.org/data/definitions/94.html) | Improper Control of Generation of Code ('Code Injection') | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-95](https://cwe.mitre.org/data/definitions/95.html) | Improper Neutralization of Directives in Dynamically Evaluated Code ('Eval Injection') | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-113](https://cwe.mitre.org/data/definitions/113.html) | Improper Neutralization of CRLF Sequences in HTTP Headers ('HTTP Request/Response Splitting') | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-116](https://cwe.mitre.org/data/definitions/116.html) | Improper Encoding or Escaping of Output | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-117](https://cwe.mitre.org/data/definitions/117.html) | Improper Output Neutralization for Logs | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-118](https://cwe.mitre.org/data/definitions/118.html) | Incorrect Access of Indexable Resource ('Range Error') | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-125](https://cwe.mitre.org/data/definitions/125.html) | Out-of-bounds Read | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-134](https://cwe.mitre.org/data/definitions/134.html) | Use of Externally-Controlled Format String | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-155](https://cwe.mitre.org/data/definitions/155.html) | Improper Neutralization of Wildcards or Matching Symbols | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-180](https://cwe.mitre.org/data/definitions/180.html) | Incorrect Behavior Order: Validate Before Canonicalize | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-182](https://cwe.mitre.org/data/definitions/182.html) | Collapse of Data into Unsafe Value | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-185](https://cwe.mitre.org/data/definitions/185.html) | Incorrect Regular Expression | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-190](https://cwe.mitre.org/data/definitions/190.html) | Integer Overflow or Wraparound | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-208](https://cwe.mitre.org/data/definitions/208.html) | Observable Timing Discrepancy | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-209](https://cwe.mitre.org/data/definitions/209.html) | Generation of Error Message Containing Sensitive Information | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-242](https://cwe.mitre.org/data/definitions/242.html) | Use of Inherently Dangerous Function | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-272](https://cwe.mitre.org/data/definitions/272.html) | Least Privilege Violation | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-276](https://cwe.mitre.org/data/definitions/276.html) | Incorrect Default Permissions | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-295](https://cwe.mitre.org/data/definitions/295.html) | Improper Certificate Validation | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-297](https://cwe.mitre.org/data/definitions/297.html) | Improper Validation of Certificate with Host Mismatch | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-306](https://cwe.mitre.org/data/definitions/306.html) | Missing Authentication for Critical Function | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-311](https://cwe.mitre.org/data/definitions/311.html) | Missing Encryption of Sensitive Data | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-319](https://cwe.mitre.org/data/definitions/319.html) | Cleartext Transmission of Sensitive Information | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-322](https://cwe.mitre.org/data/definitions/322.html) | Key Exchange without Entity Authentication | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-323](https://cwe.mitre.org/data/definitions/323.html) | Reusing a Nonce, Key Pair in Encryption | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-326](https://cwe.mitre.org/data/definitions/326.html) | Inadequate Encryption Strength | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-327](https://cwe.mitre.org/data/definitions/327.html) | Use of a Broken or Risky Cryptographic Algorithm | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-328](https://cwe.mitre.org/data/definitions/328.html) | Use of Weak Hash | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-338](https://cwe.mitre.org/data/definitions/338.html) | Use of Cryptographically Weak Pseudo-Random Number Generator (PRNG) | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-346](https://cwe.mitre.org/data/definitions/346.html) | Origin Validation Error | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-347](https://cwe.mitre.org/data/definitions/347.html) | Improper Verification of Cryptographic Signature | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-348](https://cwe.mitre.org/data/definitions/348.html) | Use of Less Trusted Source | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-352](https://cwe.mitre.org/data/definitions/352.html) | Cross-Site Request Forgery (CSRF) | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-358](https://cwe.mitre.org/data/definitions/358.html) | Improperly Implemented Security Check for Standard | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-369](https://cwe.mitre.org/data/definitions/369.html) | Divide By Zero | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-377](https://cwe.mitre.org/data/definitions/377.html) | Insecure Temporary File | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-409](https://cwe.mitre.org/data/definitions/409.html) | Improper Handling of Highly Compressed Data (Data Amplification) | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-470](https://cwe.mitre.org/data/definitions/470.html) | Use of Externally-Controlled Input to Select Classes or Code ('Unsafe Reflection') | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-489](https://cwe.mitre.org/data/definitions/489.html) | Active Debug Code | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-502](https://cwe.mitre.org/data/definitions/502.html) | Deserialization of Untrusted Data | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-521](https://cwe.mitre.org/data/definitions/521.html) | Weak Password Requirements | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-522](https://cwe.mitre.org/data/definitions/522.html) | Insufficiently Protected Credentials | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-552](https://cwe.mitre.org/data/definitions/552.html) | Files or Directories Accessible to External Parties | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-554](https://cwe.mitre.org/data/definitions/554.html) | ASP.NET Misconfiguration: Not Using Input Validation Framework | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-599](https://cwe.mitre.org/data/definitions/599.html) | Missing Validation of OpenSSL Certificate | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-601](https://cwe.mitre.org/data/definitions/601.html) | URL Redirection to Untrusted Site ('Open Redirect') | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-606](https://cwe.mitre.org/data/definitions/606.html) | Unchecked Input for Loop Condition | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-611](https://cwe.mitre.org/data/definitions/611.html) | Improper Restriction of XML External Entity Reference | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-613](https://cwe.mitre.org/data/definitions/613.html) | Insufficient Session Expiration | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-614](https://cwe.mitre.org/data/definitions/614.html) | Sensitive Cookie in HTTPS Session Without 'Secure' Attribute | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-639](https://cwe.mitre.org/data/definitions/639.html) | Authorization Bypass Through User-Controlled Key | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-643](https://cwe.mitre.org/data/definitions/643.html) | Improper Neutralization of Data within XPath Expressions ('XPath Injection') | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-704](https://cwe.mitre.org/data/definitions/704.html) | Incorrect Type Conversion or Cast | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-732](https://cwe.mitre.org/data/definitions/732.html) | Incorrect Permission Assignment for Critical Resource | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-749](https://cwe.mitre.org/data/definitions/749.html) | Exposed Dangerous Method or Function | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-754](https://cwe.mitre.org/data/definitions/754.html) | Improper Check for Unusual or Exceptional Conditions | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-757](https://cwe.mitre.org/data/definitions/757.html) | Selection of Less-Secure Algorithm During Negotiation ('Algorithm Downgrade') | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-770](https://cwe.mitre.org/data/definitions/770.html) | Allocation of Resources Without Limits or Throttling | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-776](https://cwe.mitre.org/data/definitions/776.html) | Improper Restriction of Recursive Entity References in DTDs ('XML Entity Expansion') | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-780](https://cwe.mitre.org/data/definitions/780.html) | Use of RSA Algorithm without OAEP | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-787](https://cwe.mitre.org/data/definitions/787.html) | Out-of-bounds Write | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-798](https://cwe.mitre.org/data/definitions/798.html) | Use of Hard-coded Credentials | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-913](https://cwe.mitre.org/data/definitions/913.html) | Improper Control of Dynamically-Managed Code Resources | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-915](https://cwe.mitre.org/data/definitions/915.html) | Improperly Controlled Modification of Dynamically-Determined Object Attributes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-917](https://cwe.mitre.org/data/definitions/917.html) | Improper Neutralization of Special Elements used in an Expression Language Statement ('Expression Language Injection') | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-918](https://cwe.mitre.org/data/definitions/918.html) | Server-Side Request Forgery (SSRF) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| [CWE-942](https://cwe.mitre.org/data/definitions/942.html) | Permissive Cross-domain Policy with Untrusted Domains | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-943](https://cwe.mitre.org/data/definitions/943.html) | Improper Neutralization of Special Elements in Data Query Logic | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-1004](https://cwe.mitre.org/data/definitions/1004.html) | Sensitive Cookie Without 'HttpOnly' Flag | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| [CWE-1104](https://cwe.mitre.org/data/definitions/1104.html) | Use of Unmaintained Third Party Components | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-1204](https://cwe.mitre.org/data/definitions/1204.html) | Generation of Weak Initialization Vector (IV) | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-1275](https://cwe.mitre.org/data/definitions/1275.html) | Sensitive Cookie with Improper SameSite Attribute | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-1321](https://cwe.mitre.org/data/definitions/1321.html) | Improperly Controlled Modification of Object Prototype Attributes ('Prototype Pollution') | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| [CWE-1327](https://cwe.mitre.org/data/definitions/1327.html) | Binding to an Unrestricted IP Address | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| [CWE-1390](https://cwe.mitre.org/data/definitions/1390.html) | Weak Authentication | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
+| [CWE-15](https://cwe.mitre.org/data/definitions/15.html) | External Control of System or Configuration Setting | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-22](https://cwe.mitre.org/data/definitions/22.html) | Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal') | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-23](https://cwe.mitre.org/data/definitions/23.html) | Relative Path Traversal | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-73](https://cwe.mitre.org/data/definitions/73.html) | External Control of File Name or Path | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-76](https://cwe.mitre.org/data/definitions/76.html) | Improper Neutralization of Equivalent Special Elements | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-77](https://cwe.mitre.org/data/definitions/77.html) | Improper Neutralization of Special Elements used in a Command ('Command Injection') | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-78](https://cwe.mitre.org/data/definitions/78.html) | Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection') | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-79](https://cwe.mitre.org/data/definitions/79.html) | Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting') | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-80](https://cwe.mitre.org/data/definitions/80.html) | Improper Neutralization of Script-Related HTML Tags in a Web Page (Basic XSS) | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-88](https://cwe.mitre.org/data/definitions/88.html) | Improper Neutralization of Argument Delimiters in a Command ('Argument Injection') | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-89](https://cwe.mitre.org/data/definitions/89.html) | Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection') | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-90](https://cwe.mitre.org/data/definitions/90.html) | Improper Neutralization of Special Elements used in an LDAP Query ('LDAP Injection') | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-91](https://cwe.mitre.org/data/definitions/91.html) | XML Injection (aka Blind XPath Injection) | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-94](https://cwe.mitre.org/data/definitions/94.html) | Improper Control of Generation of Code ('Code Injection') | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-95](https://cwe.mitre.org/data/definitions/95.html) | Improper Neutralization of Directives in Dynamically Evaluated Code ('Eval Injection') | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-113](https://cwe.mitre.org/data/definitions/113.html) | Improper Neutralization of CRLF Sequences in HTTP Headers ('HTTP Request/Response Splitting') | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-116](https://cwe.mitre.org/data/definitions/116.html) | Improper Encoding or Escaping of Output | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-117](https://cwe.mitre.org/data/definitions/117.html) | Improper Output Neutralization for Logs | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-118](https://cwe.mitre.org/data/definitions/118.html) | Incorrect Access of Indexable Resource ('Range Error') | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-125](https://cwe.mitre.org/data/definitions/125.html) | Out-of-bounds Read | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-134](https://cwe.mitre.org/data/definitions/134.html) | Use of Externally-Controlled Format String | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-155](https://cwe.mitre.org/data/definitions/155.html) | Improper Neutralization of Wildcards or Matching Symbols | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-180](https://cwe.mitre.org/data/definitions/180.html) | Incorrect Behavior Order: Validate Before Canonicalize | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-182](https://cwe.mitre.org/data/definitions/182.html) | Collapse of Data into Unsafe Value | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-185](https://cwe.mitre.org/data/definitions/185.html) | Incorrect Regular Expression | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-190](https://cwe.mitre.org/data/definitions/190.html) | Integer Overflow or Wraparound | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-208](https://cwe.mitre.org/data/definitions/208.html) | Observable Timing Discrepancy | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-209](https://cwe.mitre.org/data/definitions/209.html) | Generation of Error Message Containing Sensitive Information | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-242](https://cwe.mitre.org/data/definitions/242.html) | Use of Inherently Dangerous Function | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-272](https://cwe.mitre.org/data/definitions/272.html) | Least Privilege Violation | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-276](https://cwe.mitre.org/data/definitions/276.html) | Incorrect Default Permissions | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-295](https://cwe.mitre.org/data/definitions/295.html) | Improper Certificate Validation | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-297](https://cwe.mitre.org/data/definitions/297.html) | Improper Validation of Certificate with Host Mismatch | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-306](https://cwe.mitre.org/data/definitions/306.html) | Missing Authentication for Critical Function | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-311](https://cwe.mitre.org/data/definitions/311.html) | Missing Encryption of Sensitive Data | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-319](https://cwe.mitre.org/data/definitions/319.html) | Cleartext Transmission of Sensitive Information | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-322](https://cwe.mitre.org/data/definitions/322.html) | Key Exchange without Entity Authentication | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-323](https://cwe.mitre.org/data/definitions/323.html) | Reusing a Nonce, Key Pair in Encryption | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-326](https://cwe.mitre.org/data/definitions/326.html) | Inadequate Encryption Strength | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-327](https://cwe.mitre.org/data/definitions/327.html) | Use of a Broken or Risky Cryptographic Algorithm | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-328](https://cwe.mitre.org/data/definitions/328.html) | Use of Weak Hash | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-338](https://cwe.mitre.org/data/definitions/338.html) | Use of Cryptographically Weak Pseudo-Random Number Generator (PRNG) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-346](https://cwe.mitre.org/data/definitions/346.html) | Origin Validation Error | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-347](https://cwe.mitre.org/data/definitions/347.html) | Improper Verification of Cryptographic Signature | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-348](https://cwe.mitre.org/data/definitions/348.html) | Use of Less Trusted Source | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-352](https://cwe.mitre.org/data/definitions/352.html) | Cross-Site Request Forgery (CSRF) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-358](https://cwe.mitre.org/data/definitions/358.html) | Improperly Implemented Security Check for Standard | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-369](https://cwe.mitre.org/data/definitions/369.html) | Divide By Zero | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-377](https://cwe.mitre.org/data/definitions/377.html) | Insecure Temporary File | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-409](https://cwe.mitre.org/data/definitions/409.html) | Improper Handling of Highly Compressed Data (Data Amplification) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-470](https://cwe.mitre.org/data/definitions/470.html) | Use of Externally-Controlled Input to Select Classes or Code ('Unsafe Reflection') | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-489](https://cwe.mitre.org/data/definitions/489.html) | Active Debug Code | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-502](https://cwe.mitre.org/data/definitions/502.html) | Deserialization of Untrusted Data | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-521](https://cwe.mitre.org/data/definitions/521.html) | Weak Password Requirements | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-522](https://cwe.mitre.org/data/definitions/522.html) | Insufficiently Protected Credentials | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-552](https://cwe.mitre.org/data/definitions/552.html) | Files or Directories Accessible to External Parties | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-554](https://cwe.mitre.org/data/definitions/554.html) | ASP.NET Misconfiguration: Not Using Input Validation Framework | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-599](https://cwe.mitre.org/data/definitions/599.html) | Missing Validation of OpenSSL Certificate | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-601](https://cwe.mitre.org/data/definitions/601.html) | URL Redirection to Untrusted Site ('Open Redirect') | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-606](https://cwe.mitre.org/data/definitions/606.html) | Unchecked Input for Loop Condition | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-611](https://cwe.mitre.org/data/definitions/611.html) | Improper Restriction of XML External Entity Reference | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-613](https://cwe.mitre.org/data/definitions/613.html) | Insufficient Session Expiration | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-614](https://cwe.mitre.org/data/definitions/614.html) | Sensitive Cookie in HTTPS Session Without 'Secure' Attribute | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-639](https://cwe.mitre.org/data/definitions/639.html) | Authorization Bypass Through User-Controlled Key | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-643](https://cwe.mitre.org/data/definitions/643.html) | Improper Neutralization of Data within XPath Expressions ('XPath Injection') | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-704](https://cwe.mitre.org/data/definitions/704.html) | Incorrect Type Conversion or Cast | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-732](https://cwe.mitre.org/data/definitions/732.html) | Incorrect Permission Assignment for Critical Resource | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-749](https://cwe.mitre.org/data/definitions/749.html) | Exposed Dangerous Method or Function | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-754](https://cwe.mitre.org/data/definitions/754.html) | Improper Check for Unusual or Exceptional Conditions | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-757](https://cwe.mitre.org/data/definitions/757.html) | Selection of Less-Secure Algorithm During Negotiation ('Algorithm Downgrade') | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-770](https://cwe.mitre.org/data/definitions/770.html) | Allocation of Resources Without Limits or Throttling | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-776](https://cwe.mitre.org/data/definitions/776.html) | Improper Restriction of Recursive Entity References in DTDs ('XML Entity Expansion') | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-780](https://cwe.mitre.org/data/definitions/780.html) | Use of RSA Algorithm without OAEP | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-787](https://cwe.mitre.org/data/definitions/787.html) | Out-of-bounds Write | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-798](https://cwe.mitre.org/data/definitions/798.html) | Use of Hard-coded Credentials | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-913](https://cwe.mitre.org/data/definitions/913.html) | Improper Control of Dynamically-Managed Code Resources | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-915](https://cwe.mitre.org/data/definitions/915.html) | Improperly Controlled Modification of Dynamically-Determined Object Attributes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-917](https://cwe.mitre.org/data/definitions/917.html) | Improper Neutralization of Special Elements used in an Expression Language Statement ('Expression Language Injection') | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-918](https://cwe.mitre.org/data/definitions/918.html) | Server-Side Request Forgery (SSRF) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [CWE-942](https://cwe.mitre.org/data/definitions/942.html) | Permissive Cross-domain Policy with Untrusted Domains | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-943](https://cwe.mitre.org/data/definitions/943.html) | Improper Neutralization of Special Elements in Data Query Logic | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-1004](https://cwe.mitre.org/data/definitions/1004.html) | Sensitive Cookie Without 'HttpOnly' Flag | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [CWE-1104](https://cwe.mitre.org/data/definitions/1104.html) | Use of Unmaintained Third Party Components | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-1204](https://cwe.mitre.org/data/definitions/1204.html) | Generation of Weak Initialization Vector (IV) | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-1275](https://cwe.mitre.org/data/definitions/1275.html) | Sensitive Cookie with Improper SameSite Attribute | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-1321](https://cwe.mitre.org/data/definitions/1321.html) | Improperly Controlled Modification of Object Prototype Attributes ('Prototype Pollution') | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| [CWE-1327](https://cwe.mitre.org/data/definitions/1327.html) | Binding to an Unrestricted IP Address | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| [CWE-1390](https://cwe.mitre.org/data/definitions/1390.html) | Weak Authentication | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+
+{{< alert type="note" >}}
-NOTE:
Did this page answer the question you had? If not, please comment on [epic 15343](https://gitlab.com/groups/gitlab-org/-/epics/15343) to share your use case.
+
+{{< /alert >}}
diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md
index e38223b47f8dae5a2b73e83db2330a0b489dcec6..e6517f812411701d753cda6c02a3bc6d17224998 100644
--- a/doc/user/application_security/sast/analyzers.md
+++ b/doc/user/application_security/sast/analyzers.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: SAST analyzers
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3.
+
+{{< /history >}}
Static Application Security Testing (SAST) uses analyzers
to detect vulnerabilities in source code. Each analyzer is a wrapper around a [scanner](../terminology/_index.md#scanner), a third-party code analysis tool.
@@ -90,9 +97,12 @@ support the following features:
## Post analyzers
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Post analyzers enrich the report output by an analyzer. A post analyzer doesn't modify report
content directly. Instead, it enhances the results with additional properties, including:
@@ -136,9 +146,12 @@ Prerequisites:
- The custom Docker registry must provide images for all the official analyzers.
-NOTE:
+{{< alert type="note" >}}
+
This variable affects all Secure analyzers, not just the analyzers for SAST.
+{{< /alert >}}
+
To have GitLab download the analyzers' images from a custom Docker registry, define the prefix with
the `SECURE_ANALYZERS_PREFIX` CI/CD variable.
diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md
index a8ba52142685b985bb212f8952d2bc90741fd4fa..0400c9533434b9ca4b6146874df3d002592dcb5a 100644
--- a/doc/user/application_security/sast/customize_rulesets.md
+++ b/doc/user/application_security/sast/customize_rulesets.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Customize rulesets
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Enabled](https://gitlab.com/gitlab-org/security-products/analyzers/ruleset/-/merge_requests/18) support for specifying ambiguous passthrough refs in GitLab 16.2.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Enabled](https://gitlab.com/gitlab-org/security-products/analyzers/ruleset/-/merge_requests/18) support for specifying ambiguous passthrough refs in GitLab 16.2.
+
+{{< /history >}}
You can customize the behavior of our SAST analyzers by [defining a ruleset configuration file](#create-the-configuration-file) in the
repository being scanned. There are two kinds of customization:
@@ -75,7 +82,11 @@ To create the ruleset configuration file:
## Specify a remote configuration file
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393452) in 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393452) in 16.1.
+
+{{< /history >}}
You can set a [CI/CD variable](../../../ci/variables/_index.md) to use a ruleset configuration file that's stored outside of the current repository.
This can help you apply the same rules across multiple projects.
@@ -88,9 +99,12 @@ optional authentication, and optional Git SHA. The variable uses the following f
[<AUTH_USER>[:<AUTH_PASSWORD>]@]<PROJECT_PATH>[@<GIT_SHA>]
```
-NOTE:
+{{< alert type="note" >}}
+
If a project has a `.gitlab/sast-ruleset.toml` file committed, that local configuration takes precedence and the file from `SAST_RULESET_GIT_REFERENCE` isn't used.
+{{< /alert >}}
+
The following example [enables SAST](_index.md#configure-sast-in-your-cicd-yaml) and uses a shared ruleset customization file.
In this example, the file is committed on the default branch of `example-ruleset-project` at the path `.gitlab/sast-ruleset.toml`.
@@ -150,9 +164,12 @@ differ based on the kind of configuration you're making.
#### `interpolate`
-WARNING:
+{{< alert type="warning" >}}
+
To reduce the risk of leaking secrets, use this feature with caution.
+{{< /alert >}}
+
The example below shows a configuration that uses the `$GITURL` environment variable to access a
private repository. The variable contains a username and token (for example `https://user:token@url`), so
they're not explicitly stored in the configuration file.
@@ -261,10 +278,13 @@ The `[$analyzer.ruleset.override]` section allows you to override attributes of
| `name` | The name of the rule. |
| `severity` | The severity of the rule. Valid options are: `Critical`, `High`, `Medium`, `Low`, `Unknown`, `Info`) |
-NOTE:
+{{< alert type="note" >}}
+
While `message` is populated by the analyzers, it has been [deprecated](https://gitlab.com/gitlab-org/security-products/analyzers/report/-/blob/1d86d5f2e61dc38c775fb0490ee27a45eee4b8b3/vulnerability.go#L22)
in favor of `name` and `description`.
+{{< /alert >}}
+
Configuration example:
```toml
@@ -278,9 +298,12 @@ Configuration example:
### The `[[$analyzer.passthrough]]` section
-NOTE:
+{{< alert type="note" >}}
+
Passthrough configurations are available for the [Semgrep-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) only.
+{{< /alert >}}
+
The `[[$analyzer.passthrough]]` section allows you to build a custom configuration for an analyzer. You
can define up to 20 of these sections per analyzer. Passthroughs are composed into a _passthrough chain_
that evaluates into a complete configuration that replaces the predefined rules of the analyzer.
@@ -311,11 +334,14 @@ The size of the configuration generated by a single passthrough is limited to 10
| `git` | Pull the configuration from a remote Git repository. |
| `url` | Fetch the configuration using HTTP. |
-WARNING:
+{{< alert type="warning" >}}
+
When using the `raw` passthrough with a YAML snippet, it's recommended to format all indentation
in the `sast-ruleset.toml` file as spaces. The YAML specification mandates spaces over tabs, and the
analyzer fails to parse your custom ruleset unless the indentation is represented accordingly.
+{{< /alert >}}
+
## Examples
### Disable predefined GitLab Advanced SAST rules
diff --git a/doc/user/application_security/sast/evaluation_guide.md b/doc/user/application_security/sast/evaluation_guide.md
index ba23975a371747dcbe96e3ca26af068ec3242995..81ed1eb6cb5f9cac18e4ed3752ccb0b8562f00a3 100644
--- a/doc/user/application_security/sast/evaluation_guide.md
+++ b/doc/user/application_security/sast/evaluation_guide.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Evaluate GitLab SAST
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You might choose to evaluate GitLab SAST before using it in your organization.
Consider the following guidance as you plan and conduct your evaluation.
diff --git a/doc/user/application_security/sast/gitlab_advanced_sast.md b/doc/user/application_security/sast/gitlab_advanced_sast.md
index e7980ed06ff218f5c253c60a40b2669f9d880199..059299a90493be372481f4a6e6c4273eb26d7ed3 100644
--- a/doc/user/application_security/sast/gitlab_advanced_sast.md
+++ b/doc/user/application_security/sast/gitlab_advanced_sast.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Advanced SAST
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Introduced in GitLab 17.1 as an [experiment](../../../policy/development_stages_support.md) for Python.
-> - Support for Go and Java added in 17.2.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461859) from experiment to beta in GitLab 17.2.
-> - Support for JavaScript, TypeScript, and C# added in 17.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/474094) in GitLab 17.3.
-> - Support for Java Server Pages (JSP) added in GitLab 17.4.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced in GitLab 17.1 as an [experiment](../../../policy/development_stages_support.md) for Python.
+- Support for Go and Java added in 17.2.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/461859) from experiment to beta in GitLab 17.2.
+- Support for JavaScript, TypeScript, and C# added in 17.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/474094) in GitLab 17.3.
+- Support for Java Server Pages (JSP) added in GitLab 17.4.
+
+{{< /history >}}
GitLab Advanced SAST is a Static Application Security Testing (SAST) analyzer
designed to discover vulnerabilities by performing cross-function and cross-file taint analysis.
@@ -154,9 +161,13 @@ You can set this variable anywhere you can configure CI/CD variables, including
## Vulnerability code flow
-> - Introduced in GitLab 17.3 [with several flags](../../../administration/feature_flags.md). Enabled by default.
-> - Enabled on GitLab Self-Managed and GitLab Dedicated in GitLab 17.7.
-> - Generally available in GitLab 17.7. All feature flags removed.
+{{< history >}}
+
+- Introduced in GitLab 17.3 [with several flags](../../../administration/feature_flags.md). Enabled by default.
+- Enabled on GitLab Self-Managed and GitLab Dedicated in GitLab 17.7.
+- Generally available in GitLab 17.7. All feature flags removed.
+
+{{< /history >}}
For specific types of vulnerabilities, GitLab Advanced SAST provides code flow information.
A vulnerability's code flow is the path the data takes from the user input (source) to the vulnerable line of code (sink), through all assignments, manipulation, and sanitization.
diff --git a/doc/user/application_security/sast/rules.md b/doc/user/application_security/sast/rules.md
index a3264b9c6739c91e2390d694e3f6d1e2bf4ebf98..4599725e2bb431a73e5bd56d06dc2c554e372442 100644
--- a/doc/user/application_security/sast/rules.md
+++ b/doc/user/application_security/sast/rules.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: SAST rules
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab SAST uses a set of [analyzers](analyzers.md) to scan code for potential vulnerabilities.
It automatically chooses which analyzers to run based on which programming languages are found in the repository.
@@ -28,8 +31,11 @@ GitLab SAST is designed to be used in its default configuration, but you can [co
### GitLab Advanced SAST
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
GitLab creates, maintains, and supports the rules for [GitLab Advanced SAST](gitlab_advanced_sast.md).
Its rules are custom-built to leverage the GitLab Advanced SAST scanning engine's cross-file, cross-function analysis capabilities.
diff --git a/doc/user/application_security/sast/troubleshooting.md b/doc/user/application_security/sast/troubleshooting.md
index 7f1ca913645152891a4ff3989122862a0b2f9a07..c3f8453fa632446d59d208b74355d25e255ed4cc 100644
--- a/doc/user/application_security/sast/troubleshooting.md
+++ b/doc/user/application_security/sast/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting SAST
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The following troubleshooting scenarios have been collected from customer support cases. If you
experience a problem not addressed here, or the information here does not fix your problem, see the
diff --git a/doc/user/application_security/secret_detection/_index.md b/doc/user/application_security/secret_detection/_index.md
index 15d21a5dbd07a722c21029ed66481ba3d5735393..7f4f75f7d7c65e4196218190a69390305105c07b 100644
--- a/doc/user/application_security/secret_detection/_index.md
+++ b/doc/user/application_security/secret_detection/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Secret detection
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Your application might use external resources, including a CI/CD
service, a database, or external storage. Access to these resources
diff --git a/doc/user/application_security/secret_detection/automatic_response.md b/doc/user/application_security/secret_detection/automatic_response.md
index e4459f6ddb51728636b7e9593acf8d18271a66a4..7808bafffbffc23c322348a316c0f3a4de85b381 100644
--- a/doc/user/application_security/secret_detection/automatic_response.md
+++ b/doc/user/application_security/secret_detection/automatic_response.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Automatic response to leaked secrets
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab Secret Detection automatically responds when it finds certain types of leaked secrets.
Automatic responses can:
@@ -33,7 +36,11 @@ GitLab supports automatic response for the following types of secrets:
## Feature availability
-> - [Enabled for non-default branches](https://gitlab.com/gitlab-org/gitlab/-/issues/299212) in GitLab 15.11.
+{{< history >}}
+
+- [Enabled for non-default branches](https://gitlab.com/gitlab-org/gitlab/-/issues/299212) in GitLab 15.11.
+
+{{< /history >}}
Credentials are only post-processed when Secret Detection finds them:
diff --git a/doc/user/application_security/secret_detection/client/_index.md b/doc/user/application_security/secret_detection/client/_index.md
index d33e9f16a31c28a778a728c977b6243cb4f6957a..f409db02c156667d6a4670e58988f20a11fb908f 100644
--- a/doc/user/application_security/secret_detection/client/_index.md
+++ b/doc/user/application_security/secret_detection/client/_index.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Client-side secret detection
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368434) in GitLab 15.11.
-> - Detection of personal access tokens with a custom prefix was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/411146) in GitLab 16.1. GitLab Self-Managed only.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368434) in GitLab 15.11.
+- Detection of personal access tokens with a custom prefix was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/411146) in GitLab 16.1. GitLab Self-Managed only.
+
+{{< /history >}}
When you create an issue, propose a merge request, or write a comment, you might accidentally post a
secret. For example, you might paste in the details of an API request or an environment variable
diff --git a/doc/user/application_security/secret_detection/detected_secrets.md b/doc/user/application_security/secret_detection/detected_secrets.md
index b9ff75089951027f068eb00148e386a646ade013..dfdddda76b0252ff9805ba2b021bfb6e36fe572c 100644
--- a/doc/user/application_security/secret_detection/detected_secrets.md
+++ b/doc/user/application_security/secret_detection/detected_secrets.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Detected secrets
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This table lists the secrets detected by:
@@ -21,131 +24,131 @@ This table lists the secrets detected by:
| Description | ID | Pipeline secret detection | Client-side secret detection | Secret push protection |
|:----------------------------------------------|:----------------------------------------------|:--------------------------|:-----------------------------|:-----------------------|
-| Adobe Client ID (OAuth Web) | Adobe Client ID (OAuth Web) | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Adobe Client Secret | Adobe Client Secret | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Age secret key | Age secret key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Alibaba AccessKey ID | Alibaba AccessKey ID | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Alibaba Secret Key | Alibaba Secret Key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Anthropic keys | anthropic_key | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| Asana Client ID | Asana Client ID | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Asana Client Secret | Asana Client Secret | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Atlassian API token | Atlassian API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| AWS Access Token | AWS | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Beamer API token | Beamer API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Bitbucket client ID | Bitbucket client ID | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Bitbucket client secret | Bitbucket client secret | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| CircleCI access tokens | CircleCI access tokens | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Clojars API token | Clojars API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Contentful delivery API token | Contentful delivery API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Contentful preview API token | Contentful preview API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Databricks API token | Databricks API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| DigitalOcean OAuth Access Token | digitalocean-access-token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| DigitalOcean OAuth Refresh Token | digitalocean-refresh-token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| DigitalOcean Personal Access Token | digitalocean-pat | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Discord API key | Discord API key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Discord client ID | Discord client ID | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Discord client secret | Discord client secret | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Doppler API token | Doppler API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Dropbox API secret/key | Dropbox API secret/key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Dropbox long lived API token | Dropbox long lived API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Dropbox short lived API token | Dropbox short lived API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Duffel API token | Duffel API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Dynatrace API token | Dynatrace API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| EasyPost API token | EasyPost API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| EasyPost test API token | EasyPost test API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Facebook token | Facebook token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Fastly API token | Fastly API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Finicity API token | Finicity API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Finicity client secret | Finicity client secret | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Flutterwave encrypted key | Flutterwave encrypted key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Flutterwave public key | Flutterwave public key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Flutterwave secret key | Flutterwave secret key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Frame.io API token | Frame.io API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| GCP API keys | GCP API key | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| GCP OAuth client secret | GCP OAuth client secret | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| GitHub App Token | GitHub App Token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| GitHub OAuth Access Token | GitHub OAuth Access Token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| GitHub Personal Access Token | GitHub Personal Access Token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| GitHub Refresh Token | GitHub Refresh Token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| GitLab Agent for Kubernetes token | gitlab_kubernetes_agent_token | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| GitLab CI Build (Job) token | gitlab_ci_build_token | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| GitLab Deploy Token | gitlab_deploy_token | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No |
-| GitLab Feature Flags Client Token | None | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No |
-| GitLab Feed Token | gitlab_feed_token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| GitLab Feed Token | gitlab_feed_token_v2 | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| GitLab Incoming email token | gitlab_incoming_email_token | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| GitLab OAuth Application Secrets | gitlab_oauth_app_secret | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| GitLab Personal Access Token | gitlab_personal_access_token | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| GitLab Pipeline Trigger Token | gitlab_pipeline_trigger_token | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| GitLab Runner Authentication Token | gitlab_runner_auth_token | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| GitLab Runner Registration Token | gitlab_runner_registration_token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| GitLab SCIM token | gitlab_scim_oauth_token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| GoCardless API token | GoCardless API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Google (GCP) Service-account | Google (GCP) Service-account | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Grafana API token | Grafana API token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Hashicorp Terraform user/org API token | Hashicorp Terraform user/org API token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Hashicorp Vault batch token | Hashicorp Vault batch token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Heroku API Key | Heroku API Key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Hubspot API token | Hubspot API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Instagram access token | Instagram access token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Intercom API token | Intercom API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Intercom client secret/ID | Intercom client secret/ID | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Ionic API token | Ionic API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Linear API token | Linear API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Linear client secret/ID | Linear client secret/ID | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Linkedin Client ID | Linkedin Client ID | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Linkedin Client secret | Linkedin Client secret | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Lob API Key | Lob API Key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Lob Publishable API Key | Lob Publishable API Key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Mailchimp API key | Mailchimp API key | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Mailgun private API token | Mailgun private API token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Mailgun public validation key | Mailgun public validation key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Mailgun webhook signing key | Mailgun webhook signing key | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Mapbox API token | Mapbox API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| MessageBird API client ID | MessageBird API client ID | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| MessageBird API token | messagebird-api-token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Meta access token | Meta access token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| New Relic ingest browser API token | New Relic ingest browser API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| New Relic user API ID | New Relic user API ID | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| New Relic user API Key | New Relic user API Key | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| npm access token | npm access token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Oculus access token | Oculus access token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Open AI API key | open ai token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Password in URL | Password in URL | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| PGP private key | PGP private key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| PKCS8 private key | PKCS8 private key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Planetscale API token | Planetscale API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Planetscale password | Planetscale password | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Postman API token | Postman API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Pulumi API token | Pulumi API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| PyPI upload token | PyPI upload token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| RSA private key | RSA private key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Rubygem API token | Rubygem API token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Segment Public API token | Segment Public API token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Sendgrid API token | Sendgrid API token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Sendinblue API token | Sendinblue API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Sendinblue SMTP token | Sendinblue SMTP token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Shippo API token | Shippo API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Shopify access token | Shopify access token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Shopify custom app access token | Shopify custom app access token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Shopify private app access token | Shopify private app access token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Shopify shared secret | Shopify shared secret | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Slack token | Slack token | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| Slack Webhook | Slack Webhook | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| SSH (DSA) private key | SSH (DSA) private key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| SSH (EC) private key | SSH (EC) private key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| SSH private key | SSH private key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Stripe | Stripe | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes |
-| systemd machine-id | systemd-machine-id | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Tailscale keys | Tailscale key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Twilio API Key | Twilio API Key | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Twitch API token | Twitch API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Twitter token | Twitter token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Typeform API token | Typeform API token | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Yandex.Cloud AWS API compatible Access Secret | Yandex.Cloud AWS API compatible Access Secret | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Yandex.Cloud IAM API key v1 | Yandex.Cloud IAM Cookie v1 - 3 | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Yandex.Cloud IAM Cookie v1 | Yandex.Cloud IAM Cookie v1 - 1 | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
-| Yandex.Cloud IAM Token v1 | Yandex.Cloud IAM Cookie v1 - 2 | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No |
+| Adobe Client ID (OAuth Web) | Adobe Client ID (OAuth Web) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Adobe Client Secret | Adobe Client Secret | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Age secret key | Age secret key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Alibaba AccessKey ID | Alibaba AccessKey ID | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Alibaba Secret Key | Alibaba Secret Key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Anthropic keys | anthropic_key | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| Asana Client ID | Asana Client ID | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Asana Client Secret | Asana Client Secret | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Atlassian API token | Atlassian API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| AWS Access Token | AWS | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Beamer API token | Beamer API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Bitbucket client ID | Bitbucket client ID | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Bitbucket client secret | Bitbucket client secret | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| CircleCI access tokens | CircleCI access tokens | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Clojars API token | Clojars API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Contentful delivery API token | Contentful delivery API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Contentful preview API token | Contentful preview API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Databricks API token | Databricks API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| DigitalOcean OAuth Access Token | digitalocean-access-token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| DigitalOcean OAuth Refresh Token | digitalocean-refresh-token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| DigitalOcean Personal Access Token | digitalocean-pat | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Discord API key | Discord API key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Discord client ID | Discord client ID | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Discord client secret | Discord client secret | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Doppler API token | Doppler API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Dropbox API secret/key | Dropbox API secret/key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Dropbox long lived API token | Dropbox long lived API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Dropbox short lived API token | Dropbox short lived API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Duffel API token | Duffel API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Dynatrace API token | Dynatrace API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| EasyPost API token | EasyPost API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| EasyPost test API token | EasyPost test API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Facebook token | Facebook token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Fastly API token | Fastly API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Finicity API token | Finicity API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Finicity client secret | Finicity client secret | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Flutterwave encrypted key | Flutterwave encrypted key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Flutterwave public key | Flutterwave public key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Flutterwave secret key | Flutterwave secret key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Frame.io API token | Frame.io API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| GCP API keys | GCP API key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| GCP OAuth client secret | GCP OAuth client secret | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| GitHub App Token | GitHub App Token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| GitHub OAuth Access Token | GitHub OAuth Access Token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| GitHub Personal Access Token | GitHub Personal Access Token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| GitHub Refresh Token | GitHub Refresh Token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| GitLab Agent for Kubernetes token | gitlab_kubernetes_agent_token | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| GitLab CI Build (Job) token | gitlab_ci_build_token | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| GitLab Deploy Token | gitlab_deploy_token | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| GitLab Feature Flags Client Token | None | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No |
+| GitLab Feed Token | gitlab_feed_token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| GitLab Feed Token | gitlab_feed_token_v2 | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| GitLab Incoming email token | gitlab_incoming_email_token | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| GitLab OAuth Application Secrets | gitlab_oauth_app_secret | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| GitLab Personal Access Token | gitlab_personal_access_token | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| GitLab Pipeline Trigger Token | gitlab_pipeline_trigger_token | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| GitLab Runner Authentication Token | gitlab_runner_auth_token | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| GitLab Runner Registration Token | gitlab_runner_registration_token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| GitLab SCIM token | gitlab_scim_oauth_token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| GoCardless API token | GoCardless API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Google (GCP) Service-account | Google (GCP) Service-account | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Grafana API token | Grafana API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Hashicorp Terraform user/org API token | Hashicorp Terraform user/org API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Hashicorp Vault batch token | Hashicorp Vault batch token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Heroku API Key | Heroku API Key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Hubspot API token | Hubspot API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Instagram access token | Instagram access token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Intercom API token | Intercom API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Intercom client secret/ID | Intercom client secret/ID | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Ionic API token | Ionic API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Linear API token | Linear API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Linear client secret/ID | Linear client secret/ID | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Linkedin Client ID | Linkedin Client ID | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Linkedin Client secret | Linkedin Client secret | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Lob API Key | Lob API Key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Lob Publishable API Key | Lob Publishable API Key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Mailchimp API key | Mailchimp API key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Mailgun private API token | Mailgun private API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Mailgun public validation key | Mailgun public validation key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Mailgun webhook signing key | Mailgun webhook signing key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Mapbox API token | Mapbox API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| MessageBird API client ID | MessageBird API client ID | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| MessageBird API token | messagebird-api-token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Meta access token | Meta access token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| New Relic ingest browser API token | New Relic ingest browser API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| New Relic user API ID | New Relic user API ID | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| New Relic user API Key | New Relic user API Key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| npm access token | npm access token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Oculus access token | Oculus access token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Open AI API key | open ai token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Password in URL | Password in URL | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| PGP private key | PGP private key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| PKCS8 private key | PKCS8 private key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Planetscale API token | Planetscale API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Planetscale password | Planetscale password | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Postman API token | Postman API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Pulumi API token | Pulumi API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| PyPI upload token | PyPI upload token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| RSA private key | RSA private key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Rubygem API token | Rubygem API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Segment Public API token | Segment Public API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Sendgrid API token | Sendgrid API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Sendinblue API token | Sendinblue API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Sendinblue SMTP token | Sendinblue SMTP token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Shippo API token | Shippo API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Shopify access token | Shopify access token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Shopify custom app access token | Shopify custom app access token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Shopify private app access token | Shopify private app access token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Shopify shared secret | Shopify shared secret | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Slack token | Slack token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| Slack Webhook | Slack Webhook | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| SSH (DSA) private key | SSH (DSA) private key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| SSH (EC) private key | SSH (EC) private key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| SSH private key | SSH private key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Stripe | Stripe | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| systemd machine-id | systemd-machine-id | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Tailscale keys | Tailscale key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Twilio API Key | Twilio API Key | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Twitch API token | Twitch API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Twitter token | Twitter token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Typeform API token | Typeform API token | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Yandex.Cloud AWS API compatible Access Secret | Yandex.Cloud AWS API compatible Access Secret | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Yandex.Cloud IAM API key v1 | Yandex.Cloud IAM Cookie v1 - 3 | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Yandex.Cloud IAM Cookie v1 | Yandex.Cloud IAM Cookie v1 - 1 | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Yandex.Cloud IAM Token v1 | Yandex.Cloud IAM Cookie v1 - 2 | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
<!-- vale gitlab_base.SentenceSpacing = YES -->
<!-- markdownlint-enable MD034 -->
diff --git a/doc/user/application_security/secret_detection/exclusions.md b/doc/user/application_security/secret_detection/exclusions.md
index 1baccba7da0966086433c158d0f0e1b8db54f617..c729915a45d918b756fdd4bb7a87d69019748dcd 100644
--- a/doc/user/application_security/secret_detection/exclusions.md
+++ b/doc/user/application_security/secret_detection/exclusions.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Secret detection exclusions
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14878) as an [experiment](../../../policy/development_stages_support.md) in GitLab 17.5 [with a flag](../../feature_flags.md) named `secret_detection_project_level_exclusions`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/499059) in GitLab 17.7. Feature flag `secret_detection_project_level_exclusions` removed.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14878) as an [experiment](../../../policy/development_stages_support.md) in GitLab 17.5 [with a flag](../../feature_flags.md) named `secret_detection_project_level_exclusions`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/499059) in GitLab 17.7. Feature flag `secret_detection_project_level_exclusions` removed.
+
+{{< /history >}}
Secret detection may detect something that's not actually a secret. For example, if you use
a fake value as a placeholder in your code, it might be detected and possibly blocked.
@@ -55,6 +62,6 @@ To define an exclusion:
1. Select **Secure > Security configuration**.
1. Scroll down to **Secret push protection**.
1. Turn on the **Secret push protection** toggle.
-1. Select **Configure Secret Detection** (**{settings}**).
+1. Select **Configure Secret Detection** ({{< icon name="settings" >}}).
1. Select **Add exclusion** to open the exclusion form.
1. Enter the details of the exclusion, then select **Add exclusion**.
diff --git a/doc/user/application_security/secret_detection/pipeline/_index.md b/doc/user/application_security/secret_detection/pipeline/_index.md
index 85cc84ae4967a02faeb9bc52cdca5c281d7eca06..494e09cad1c811aaf0e5133e2837272f9e4fabb7 100644
--- a/doc/user/application_security/secret_detection/pipeline/_index.md
+++ b/doc/user/application_security/secret_detection/pipeline/_index.md
@@ -4,11 +4,15 @@ group: Secret Detection
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
title: Pipeline secret detection
---
+
<!-- markdownlint-disable MD025 -->
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Pipeline secret detection scans files after they are committed to a Git repository and pushed to GitLab.
@@ -102,11 +106,18 @@ pipeline.
## Advanced vulnerability tracking
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434096) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434096) in GitLab 17.0.
+
+{{< /history >}}
When developers make changes to a file with identified secrets, it's likely that the positions of these secrets will also change. Pipeline secret detection may have already flagged these secrets as vulnerabilities, tracked in the [Vulnerability Report](../../vulnerability_report/_index.md). These vulnerabilities are associated with specific secrets for easy identification and action. However, if the detected secrets aren't accurately tracked as they shift, managing vulnerabilities becomes challenging, potentially resulting in duplicate vulnerability reports.
@@ -146,15 +157,15 @@ Different features are available in different [GitLab tiers](https://about.gitla
| Capability | In Free & Premium | In Ultimate |
|:-----------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|
-| [Enable the analyzer](#enable-the-analyzer) | **{check-circle}** Yes | **{check-circle}** Yes |
-| [Customize analyzer settings](#customize-analyzer-settings) | **{check-circle}** Yes | **{check-circle}** Yes |
-| Download [output](#output) | **{check-circle}** Yes | **{check-circle}** Yes |
-| See new findings in the merge request widget | **{dotted-circle}** No | **{check-circle}** Yes |
-| View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Manage vulnerabilities](../../vulnerability_report/_index.md) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Access the Security Dashboard](../../security_dashboard/_index.md) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Customize analyzer rulesets](#customize-analyzer-rulesets) | **{dotted-circle}** No | **{check-circle}** Yes |
-| [Enable security policies](../../policies/_index.md) | **{dotted-circle}** No | **{check-circle}** Yes |
+| [Enable the analyzer](#enable-the-analyzer) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| [Customize analyzer settings](#customize-analyzer-settings) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Download [output](#output) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| See new findings in the merge request widget | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| View identified secrets in the pipelines' **Security** tab | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Manage vulnerabilities](../../vulnerability_report/_index.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Access the Security Dashboard](../../security_dashboard/_index.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Customize analyzer rulesets](#customize-analyzer-rulesets) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
+| [Enable security policies](../../policies/_index.md) | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes |
### Enable the analyzer
@@ -192,17 +203,24 @@ Pipelines now include a pipeline secret detection job.
#### Use an automatically configured merge request
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, deployed behind a feature flag, enabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329886) in GitLab 14.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, deployed behind a feature flag, enabled by default.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329886) in GitLab 14.1.
+
+{{< /history >}}
This method automatically prepares a merge request, with the pipeline secret detection template included in
the `.gitlab-ci.yml` file. You then merge the merge request to enable pipeline secret detection.
-NOTE:
+{{< alert type="note" >}}
+
This method works best with no existing `.gitlab-ci.yml` file, or with a minimal configuration
file. If you have a complex GitLab configuration file it may not be parsed successfully, and an
error may occur. In that case, use the [manual](#edit-the-gitlab-ciyml-file-manually) method instead.
+{{< /alert >}}
+
To enable pipeline secret detection:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -219,11 +237,14 @@ Pipelines now include a pipeline secret detection job.
The pipeline secret detection scan settings can be changed through [CI/CD variables](#available-cicd-variables)
by using the [`variables`](../../../../ci/yaml/_index.md#variables) parameter in `.gitlab-ci.yml`.
-WARNING:
+{{< alert type="warning" >}}
+
All configuration of GitLab security scanning tools should be tested in a merge request before
merging these changes to the default branch. Failure to do so can give unexpected results,
including a large number of false positives.
+{{< /alert >}}
+
#### Add new patterns
To search for other types of secrets in your repositories, you can [customize analyzer rulesets](#customize-analyzer-rulesets).
@@ -291,13 +312,20 @@ secret_detection:
### Customize analyzer rulesets
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5.
-> - Expanded to include additional passthrough types of `file` and `raw` in GitLab 14.6.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/336395) support for passthrough chains and included additional passthrough types of `git` and `url` in GitLab 17.2.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5.
+- Expanded to include additional passthrough types of `file` and `raw` in GitLab 14.6.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/336395) support for passthrough chains and included additional passthrough types of `git` and `url` in GitLab 17.2.
+
+{{< /history >}}
You can customize the behavior of pipeline secret detection by [creating a ruleset configuration file](#create-a-ruleset-configuration-file),
either in the repository being scanned or a remote repository. Customization enables you to modify, replace, or extend the default ruleset.
@@ -337,7 +365,11 @@ You can also use a ruleset configuration file stored remotely (that is, a remote
##### Disable a rule
-> - Ability to disable a rule with a remote ruleset was [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/425251) in GitLab 16.0 and later.
+{{< history >}}
+
+- Ability to disable a rule with a remote ruleset was [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/425251) in GitLab 16.0 and later.
+
+{{< /history >}}
You can disable rules that you don't want active. To disable rules from the analyzer default ruleset:
@@ -361,7 +393,11 @@ In the following example `secret-detection-ruleset.toml` file, the disabled rule
##### Override a rule
-> - Ability to override a rule with a remote ruleset was [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/425251) in GitLab 16.0 and later.
+{{< history >}}
+
+- Ability to override a rule with a remote ruleset was [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/425251) in GitLab 16.0 and later.
+
+{{< /history >}}
If there are specific rules to customize, you can override them. For example, you may increase the severity of a specific type of secret because leaking it would have a higher impact on your workflow.
@@ -409,10 +445,13 @@ variables:
Pipeline secret detection assumes the configuration is defined in `.gitlab/secret-detection-ruleset.toml` file in the repository referenced by the CI variable where the remote ruleset is stored. If that file doesn't exist, please make sure to [create one](#create-a-ruleset-configuration-file) and follow the steps to [override](#override-a-rule) or [disable](#disable-a-rule) a predefined rule as outlined above.
-NOTE:
+{{< alert type="note" >}}
+
A local `.gitlab/secret-detection-ruleset.toml` file in the project takes precedence over `SECRET_DETECTION_RULESET_GIT_REFERENCE` by default because `SECURE_ENABLE_LOCAL_CONFIGURATION` is set to `true`.
If you set `SECURE_ENABLE_LOCAL_CONFIGURATION` to `false`, the local file is ignored and the default configuration or `SECRET_DETECTION_RULESET_GIT_REFERENCE` (if set) is used.
+{{< /alert >}}
+
The `SECRET_DETECTION_RULESET_GIT_REFERENCE` variable uses a format similar to [Git URLs](https://git-scm.com/docs/git-clone#_git_urls) for specifying a URI, optional authentication, and optional Git SHA. The variable uses the following format:
```plaintext
@@ -530,9 +569,12 @@ For more information on the passthrough syntax to use, see [Schema](../pipeline/
If a ruleset configuration is stored in a private repository you must provide the credentials to access the repository by using the passthrough's [`auth` setting](../pipeline/custom_rulesets_schema.md#the-secretspassthrough-section).
-NOTE:
+{{< alert type="note" >}}
+
The `auth` setting only works with `git` passthrough.
+{{< /alert >}}
+
To use a remote ruleset stored in a private repository, add the following to the `.gitlab/secret-detection-ruleset.toml` configuration file stored in a repository, adjust the `value` to point to the address of the Git repository, and update `auth` to use the appropriate credentials:
```toml
@@ -545,9 +587,12 @@ To use a remote ruleset stored in a private repository, add the following to the
value = "https://gitlab.com/user_group/central_repository_with_shared_ruleset"
```
-WARNING:
+{{< alert type="warning" >}}
+
Beware of leaking credentials when using this feature. Check [this section](../pipeline/custom_rulesets_schema.md#interpolate) for an example on how to use environment variables to minimize the risk.
+{{< /alert >}}
+
For more information on the passthrough syntax to use, see [Schema](../pipeline/custom_rulesets_schema.md#schema).
#### Extend the default ruleset
@@ -649,9 +694,12 @@ There may be situations in which you need to ignore a certain pattern or path fr
In that case, you can utilize [Gitleaks' native `[allowlist]`](https://github.com/gitleaks/gitleaks#configuration) directive to ignore specific patterns or paths.
-NOTE:
+{{< alert type="note" >}}
+
This feature works regardless of whether you're using a local or a remote ruleset configuration file. The examples below utilizes a local ruleset using `file` passthrough though.
+{{< /alert >}}
+
To ignore a pattern, add the following to the `.gitlab/secret-detection-ruleset.toml` configuration file stored in the same repository, and adjust the `value` as appropriate to point to the path of the extended configuration file:
```toml
@@ -782,11 +830,14 @@ path = "/gitleaks.toml"
keywords = ["pwd", "passwd", "password"]
```
-NOTE:
+{{< alert type="note" >}}
+
This example configuration is provided only for convenience, and might not work
for all use cases. If you configure your ruleset to detect complex strings, you might
create a large number of false positives, or fail to capture certain patterns.
+{{< /alert >}}
+
### Available CI/CD variables
Pipeline secret detection can be customized by defining available CI/CD variables:
@@ -808,9 +859,12 @@ In previous GitLab versions, the following variables were also available:
### Offline configuration
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
An offline environment has limited, restricted, or intermittent access to external resources through
the internet. For instances in such an environment, pipeline secret detection requires
@@ -921,7 +975,11 @@ There are also some video demonstrations walking through setting up remote rules
## FIPS-enabled images
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10.
+
+{{< /history >}}
The default scanner images are built off a base Alpine image for size and maintainability. GitLab
offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image)
diff --git a/doc/user/application_security/secret_detection/pipeline/custom_rulesets_schema.md b/doc/user/application_security/secret_detection/pipeline/custom_rulesets_schema.md
index ee9f68d7782db370699b1342a01224a8ee8c2245..d0e260ee511ddef6ac834b8f2a0f96135ba08511 100644
--- a/doc/user/application_security/secret_detection/pipeline/custom_rulesets_schema.md
+++ b/doc/user/application_security/secret_detection/pipeline/custom_rulesets_schema.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Custom rulesets schema
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use [different kinds of ruleset customizations](../pipeline/_index.md#customize-analyzer-rulesets)
to customize the behavior of pipeline secret detection.
@@ -48,9 +51,12 @@ based on the kind of configuration you're making.
#### `interpolate`
-WARNING:
+{{< alert type="warning" >}}
+
To reduce the risk of leaking secrets, use this feature with caution.
+{{< /alert >}}
+
The example below shows a configuration that uses the `$GITURL` environment variable to access a
private repository. The variable contains a username and token
(for example `https://user:token@url`), so they're not explicitly stored in the configuration file.
@@ -148,10 +154,13 @@ The `[secrets.ruleset.override]` section allows you to override attributes of a
| `name` | The name of the rule. |
| `severity` | The severity of the rule. Valid options are: `Critical`, `High`, `Medium`, `Low`, `Unknown`, `Info` |
-NOTE:
+{{< alert type="note" >}}
+
Although `message` is still populated by the analyzers, it has been [deprecated](https://gitlab.com/gitlab-org/security-products/analyzers/report/-/blob/1d86d5f2e61dc38c775fb0490ee27a45eee4b8b3/vulnerability.go#L22)
and replaced by `name` and `description`.
+{{< /alert >}}
+
Configuration example:
```toml
@@ -165,7 +174,11 @@ Configuration example:
### Custom rule format
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/511321) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/511321) in GitLab 17.9.
+
+{{< /history >}}
When creating custom rules, you can use both [Gitleaks' standard rule format](https://github.com/gitleaks/gitleaks?tab=readme-ov-file#configuration) and additional GitLab-specific fields. The following settings are available for each rule:
diff --git a/doc/user/application_security/secret_detection/secret_push_protection/_index.md b/doc/user/application_security/secret_detection/secret_push_protection/_index.md
index b9dc8433769304bfb3f3f24510a4ad2810bf4a40..ce3ff7cb9028d5f3b5175e18118982495fedc8b2 100644
--- a/doc/user/application_security/secret_detection/secret_push_protection/_index.md
+++ b/doc/user/application_security/secret_detection/secret_push_protection/_index.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Secret push protection
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11439) in GitLab 16.7 as an [experiment](../../../../policy/development_stages_support.md) for GitLab Dedicated customers.
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/12729) to Beta and made available on GitLab.com in GitLab 17.1.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/156907) in GitLab 17.2 [with flags](../../../../administration/feature_flags.md) named `pre_receive_secret_detection_beta_release` and `pre_receive_secret_detection_push_check`.
-> - Feature flag `pre_receive_secret_detection_beta_release` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/472418) in GitLab 17.4.
-> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/13107) in GitLab 17.5.
-> - Feature flag `pre_receive_secret_detection_push_check` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/472419) in GitLab 17.7.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11439) in GitLab 16.7 as an [experiment](../../../../policy/development_stages_support.md) for GitLab Dedicated customers.
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/12729) to Beta and made available on GitLab.com in GitLab 17.1.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/156907) in GitLab 17.2 [with flags](../../../../administration/feature_flags.md) named `pre_receive_secret_detection_beta_release` and `pre_receive_secret_detection_push_check`.
+- Feature flag `pre_receive_secret_detection_beta_release` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/472418) in GitLab 17.4.
+- [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/13107) in GitLab 17.5.
+- Feature flag `pre_receive_secret_detection_push_check` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/472419) in GitLab 17.7.
+
+{{< /history >}}
Secret push protection blocks secrets such as keys and API tokens from being pushed to GitLab. The
content of each [file or commit](#coverage) is checked for secrets when pushed to GitLab. By
@@ -122,13 +129,20 @@ Secret push protection does not check a file in a commit when:
### Diff scanning
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/469161) in GitLab 17.5 [with a flag](../../../../administration/feature_flags.md) named `spp_scan_diffs`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/480092) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/469161) in GitLab 17.5 [with a flag](../../../../administration/feature_flags.md) named `spp_scan_diffs`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/480092) in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
By default, secret push protection checks the content of each file modified in a commit. This can
cause a [push to be blocked unexpectedly](#push-blocked-unexpectedly) even though your commits don't
contain a secret. To instead have only the changes (diff) scanned for secrets when pushing by using
diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md
index 6f7910d09bca01e8f2b6097d478e59c2735b41f2..2e376237e321dbcb2d208cc572864db4cbf38f1a 100644
--- a/doc/user/application_security/secure_your_application.md
+++ b/doc/user/application_security/secure_your_application.md
@@ -1,8 +1,8 @@
---
stage: Application Security Testing
group: Static Analysis
-description: Container, dependency, and vulnerability scans.
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
+description: Container, dependency, and vulnerability scans.
title: Secure your application
---
diff --git a/doc/user/application_security/security_dashboard/_index.md b/doc/user/application_security/security_dashboard/_index.md
index dd474958cb61f311ace66d1e3da886629463ad71..e9f35154709fd28bc1bd11d386480abedba55fcc 100644
--- a/doc/user/application_security/security_dashboard/_index.md
+++ b/doc/user/application_security/security_dashboard/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Security Dashboards and Security Center
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Security Dashboards
@@ -25,7 +28,11 @@ For an overview, see [Security Dashboard](https://www.youtube.com/watch?v=Uo-pDn
## Vulnerability metrics in the Value Streams Dashboard
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383697) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383697) in GitLab 16.0.
+
+{{< /history >}}
You can view vulnerability metrics also in the [Value Streams Dashboard](../../analytics/value_streams_dashboard.md) comparison panel, which helps you understand security exposure in the context of your organization's software delivery workflows.
@@ -58,10 +65,10 @@ To view a project's security dashboard:
1. Select **Secure > Security dashboard**.
1. Filter and search for what you need.
- To filter the chart by severity, select the legend name.
- - To view a specific time frame, use the time range handles (**{scroll-handle}**).
- - To view a specific area of the chart, select the left-most icon (**{marquee-selection}**) and drag
+ - To view a specific time frame, use the time range handles ({{< icon name="scroll-handle" >}}).
+ - To view a specific area of the chart, select the left-most icon ({{< icon name="marquee-selection" >}}) and drag
across the chart.
- - To reset to the original range, select **Remove Selection** (**{redo}**).
+ - To reset to the original range, select **Remove Selection** ({{< icon name="redo" >}}).
@@ -73,7 +80,7 @@ chart:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > Security dashboard**.
-1. Select **Save chart as an image** (**{download}**).
+1. Select **Save chart as an image** ({{< icon name="download" >}}).
You will then be prompted to download the image in SVG format.
@@ -153,7 +160,7 @@ The Security Center displays a maximum of 100 projects, so you may need to use t
1. Expand **Security**.
1. Select **Settings**.
1. Use the **Search your projects** text box to search for the project.
-1. Select **Remove project from dashboard** (**{remove}**).
+1. Select **Remove project from dashboard** ({{< icon name="remove" >}}).
After you remove projects, the security dashboard and vulnerability report no longer show the vulnerabilities found in those projects' default branches.
diff --git a/doc/user/application_security/terminology/_index.md b/doc/user/application_security/terminology/_index.md
index ddb3da6b2cce4746e7236bc8bac233666b13c152..f319afb054c1c0663761da27c552cbfa227626c7 100644
--- a/doc/user/application_security/terminology/_index.md
+++ b/doc/user/application_security/terminology/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Security glossary
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This glossary provides definitions for terms related to security features in GitLab. While some terms may have different meanings elsewhere, these definitions are specific to GitLab.
diff --git a/doc/user/application_security/troubleshooting_application_security.md b/doc/user/application_security/troubleshooting_application_security.md
index a345d9814690fffe684080f8fb4d3e7c55df286c..4ce03acab23d13b8ff366659120ccca2cf15631a 100644
--- a/doc/user/application_security/troubleshooting_application_security.md
+++ b/doc/user/application_security/troubleshooting_application_security.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting application security
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with application security features, you might encounter the following issues.
@@ -26,11 +29,14 @@ From highest to lowest severity, the logging levels are:
### Debug-level logging
-WARNING:
+{{< alert type="warning" >}}
+
Debug logging can be a serious security risk. The output may contain the content of
environment variables and other secrets available to the job. The output is uploaded
to the GitLab server and is visible in job logs.
+{{< /alert >}}
+
To enable debug-level logging, add the following to your `.gitlab-ci.yml` file:
```yaml
@@ -82,11 +88,14 @@ Select **new pipeline** to run a new pipeline.
## Getting warning messages `… report.json: no matching files`
-WARNING:
+{{< alert type="warning" >}}
+
Debug logging can be a serious security risk. The output may contain the content of
environment variables and other secrets available to the job. The output is uploaded
to the GitLab server and visible in job logs.
+{{< /alert >}}
+
This message is often followed by the [error `No files to upload`](../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload),
and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Check
the entire job log for such messages. If you don't find these messages, retry the failed job after
diff --git a/doc/user/application_security/vulnerabilities/_index.md b/doc/user/application_security/vulnerabilities/_index.md
index bb5a9f4dd4ea1ec39cc0d69b531534a6d704e296..9c91cd0d1529b91c7371210903bcb3dcc8e5788f 100644
--- a/doc/user/application_security/vulnerabilities/_index.md
+++ b/doc/user/application_security/vulnerabilities/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Vulnerability Page
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Each vulnerability in a project has a vulnerability page containing details of the vulnerability,
including:
@@ -34,15 +37,22 @@ the top of the vulnerability's page.
## Explaining a vulnerability
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**LLM:** Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/about-claude/models#claude-3-a-new-generation-of-ai)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- LLM: Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/about-claude/models#claude-3-a-new-generation-of-ai)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10368) in GitLab 16.0 as an [experiment](../../../policy/development_stages_support.md#experiment) on GitLab.com.
+- Promoted to [beta](../../../policy/development_stages_support.md#beta) status in GitLab 16.2.
+- [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/10642) in GitLab 17.2.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10368) in GitLab 16.0 as an [experiment](../../../policy/development_stages_support.md#experiment) on GitLab.com.
-> - Promoted to [beta](../../../policy/development_stages_support.md#beta) status in GitLab 16.2.
-> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/10642) in GitLab 17.2.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+{{< /history >}}
GitLab can help you with a vulnerability by using a large language model to:
@@ -67,7 +77,7 @@ To explain the vulnerability:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > Vulnerability report**.
-1. Optional. To remove the default filters, select **Clear** (**{clear}**).
+1. Optional. To remove the default filters, select **Clear** ({{< icon name="clear" >}}).
1. Above the list of vulnerabilities, select the filter bar.
1. In the dropdown list that appears, select **Tool**, then select all the values in the **SAST** category.
1. Select outside the filter field. The vulnerability severity totals and list of matching vulnerabilities are updated.
@@ -94,14 +104,21 @@ The following data is shared with third-party AI APIs:
## Vulnerability Resolution
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10779) in GitLab 16.7 as an [experiment](../../../policy/development_stages_support.md#experiment) on GitLab.com.
-> - Changed to beta in GitLab 17.3.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10779) in GitLab 16.7 as an [experiment](../../../policy/development_stages_support.md#experiment) on GitLab.com.
+- Changed to beta in GitLab 17.3.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+
+{{< /history >}}
Use GitLab Duo Vulnerability resolution to automatically create a merge request that
resolves the vulnerability. By default, it is powered by the Anthropic [`claude-3.5-sonnet`](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet) model.
@@ -127,7 +144,7 @@ To resolve the vulnerability:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > Vulnerability report**.
-1. Optional. To remove the default filters, select **Clear** (**{clear}**).
+1. Optional. To remove the default filters, select **Clear** ({{< icon name="clear" >}}).
1. Above the list of vulnerabilities, select the filter bar.
1. In the dropdown list that appears, select **Activity**, then select **Vulnerability Resolution available** in the **GitLab Duo (AI)** category.
1. Select outside the filter field. The vulnerability severity totals and list of matching vulnerabilities are updated.
@@ -225,9 +242,12 @@ The following data is shared with third-party AI APIs:
## Vulnerability Resolution in a merge request
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14862) in GitLab 17.6 with a flag named [`resolve_vulnerability_in_mr`](https://gitlab.com/gitlab-org/gitlab/-/issues/482753). Disabled by default.
> [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175150) in GitLab 17.7.
@@ -240,7 +260,7 @@ To resolve the vulnerability finding:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Merge requests**.
1. Select a merge request.
- - Vulnerability findings supported by Vulnerability Resolution are indicated by the tanuki AI icon (**{tanuki-ai}**).
+ - Vulnerability findings supported by Vulnerability Resolution are indicated by the tanuki AI icon ({{< icon name="tanuki-ai" >}}).
1. Select the supported findings to open the security finding dialog.
1. In the lower-right corner, select **Resolve with AI**.
@@ -265,9 +285,12 @@ Vulnerability Resolution in a merge request sometimes cannot generate a suggeste
## Vulnerability code flow
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
For specific types of vulnerabilities, GitLab Advanced SAST provides [code flow](../sast/gitlab_advanced_sast.md#vulnerability-code-flow) information.
A vulnerability's code flow is the path the data takes from the user input (source) to the vulnerable line of code (sink), through all assignments, manipulation, and sanitization.
@@ -311,7 +334,11 @@ stateDiagram
## Vulnerability is no longer detected
-> - A link to the commit that resolved the vulnerability was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372799) and made [generally available on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178748) in GitLab 17.9. Feature flag `vulnerability_representation_information` removed.
+{{< history >}}
+
+- A link to the commit that resolved the vulnerability was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372799) and made [generally available on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178748) in GitLab 17.9. Feature flag `vulnerability_representation_information` removed.
+
+{{< /history >}}
A vulnerability may be no longer detected because of changes made deliberately to remediate it or
as a side effect of other changes. When a security scan runs and a vulnerability is no longer
@@ -326,9 +353,13 @@ You can find a link to the commit that resolved the vulnerability at the top or
## Vulnerability dismissal reasons
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4942) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `dismissal_reason`.
-> - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/393005) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124397) in GitLab 16.2. Feature flag `dismissal_reason` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4942) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `dismissal_reason`.
+- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/393005) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124397) in GitLab 16.2. Feature flag `dismissal_reason` removed.
+
+{{< /history >}}
When you dismiss a vulnerability you must choose one of the following reasons:
@@ -346,8 +377,12 @@ When you dismiss a vulnerability you must choose one of the following reasons:
## Change the status of a vulnerability
-> - The permission allowing users with the `Developer` role to change the status of a vulnerability (`admin_vulnerability`) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/424133) in GitLab 16.4 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/412693) in GitLab 17.0.
-> - The **Comment** text box was [added](https://gitlab.com/gitlab-org/gitlab/-/issues/451480) in GitLab 17.9.
+{{< history >}}
+
+- The permission allowing users with the `Developer` role to change the status of a vulnerability (`admin_vulnerability`) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/424133) in GitLab 16.4 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/412693) in GitLab 17.0.
+- The **Comment** text box was [added](https://gitlab.com/gitlab-org/gitlab/-/issues/451480) in GitLab 17.9.
+
+{{< /history >}}
Prerequisites:
@@ -398,7 +433,7 @@ To link a vulnerability to existing GitLab issues:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > Vulnerability report**.
1. Select the vulnerability's description.
-1. In the **Linked issues** section, select the plus icon (**{plus}**).
+1. In the **Linked issues** section, select the plus icon ({{< icon name="plus" >}}).
1. For each issue to be linked, either:
- Paste a link to the issue.
- Enter the issue's ID (prefixed with a hash `#`).
@@ -494,11 +529,14 @@ To manually apply the patch that GitLab generated for a vulnerability:
## Enable security training for vulnerabilities
-NOTE:
+{{< alert type="note" >}}
+
Security training is not accessible in an environment that is offline, meaning computers that are isolated from the public internet as a security measure. Specifically, the GitLab server needs the ability to query the API endpoints for any training provider you choose to enable. Some third-party training vendors may require you to sign up for a _free_ account. Sign up for an account by going to
any of [Secure Code Warrior](https://www.securecodewarrior.com/), [Kontra](https://application.security/), or [SecureFlag](https://www.secureflag.com/index.html).
GitLab does not send any user information to these third-party vendors; we do send the CWE or OWASP identifier and the language name of the file extension.
+{{< /alert >}}
+
Security training helps your developers learn how to fix vulnerabilities. Developers can view security training from selected educational providers, relevant to the detected vulnerability.
To enable security training for vulnerabilities in your project:
diff --git a/doc/user/application_security/vulnerabilities/risk_assessment_data.md b/doc/user/application_security/vulnerabilities/risk_assessment_data.md
index 85f1f3eefb95a2bed8509ce60711f5eb582e91ca..1c321bbdefd5ba09003b6157f6f1635a2e2b3db1 100644
--- a/doc/user/application_security/vulnerabilities/risk_assessment_data.md
+++ b/doc/user/application_security/vulnerabilities/risk_assessment_data.md
@@ -19,9 +19,13 @@ high severity and a low EPSS score.
## EPSS
-> - Introduced in GitLab 17.4 [with flags](../../../administration/feature_flags.md) named `epss_querying` (in issue [470835](https://gitlab.com/gitlab-org/gitlab/-/issues/470835)) and `epss_ingestion` (in issue [467672](https://gitlab.com/gitlab-org/gitlab/-/issues/467672)). Disabled by default.
-> - Renamed to `cve_enrichment_querying` and `cve_enrichment_ingestion` respectively and [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/481431) in GitLab 17.6.
-> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/11544) in GitLab 17.7. Feature flags `cve_enrichment_querying` and `cve_enrichment_ingestion` removed.
+{{< history >}}
+
+- Introduced in GitLab 17.4 [with flags](../../../administration/feature_flags.md) named `epss_querying` (in issue [470835](https://gitlab.com/gitlab-org/gitlab/-/issues/470835)) and `epss_ingestion` (in issue [467672](https://gitlab.com/gitlab-org/gitlab/-/issues/467672)). Disabled by default.
+- Renamed to `cve_enrichment_querying` and `cve_enrichment_ingestion` respectively and [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/481431) in GitLab 17.6.
+- [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/11544) in GitLab 17.7. Feature flags `cve_enrichment_querying` and `cve_enrichment_ingestion` removed.
+
+{{< /history >}}
The EPSS score provides an estimate of the likelihood a vulnerability in the CVE catalog will be
exploited in the next 30 days. EPSS assigns each CVE a score between 0 to 1 (equivalent to 0% to
@@ -29,7 +33,11 @@ exploited in the next 30 days. EPSS assigns each CVE a score between 0 to 1 (equ
## KEV
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/499407) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/499407) in GitLab 17.7.
+
+{{< /history >}}
The KEV catalog lists vulnerabilities that are known to have been exploited. You should prioritize
the remediation of vulnerabilities in the KEV catalog above other vulnerabilities. Attacks using
@@ -115,8 +123,11 @@ Example output:
## Vulnerability Prioritizer
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
+
+{{< /details >}}
Use the [Vulnerability Prioritizer CI/CD component](https://gitlab.com/explore/catalog/components/vulnerability-prioritizer) to help prioritize a project's vulnerabilities (namely CVEs). The component outputs a prioritization report in the `vulnerability-prioritizer` job's output.
diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md
index 53f475bcd874c4bbbd60ba570e68ff642f4f25c7..0361cf24e56a91bb54c8b431a0e629f79f92a8ed 100644
--- a/doc/user/application_security/vulnerabilities/severities.md
+++ b/doc/user/application_security/vulnerabilities/severities.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Vulnerability severity levels
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab vulnerability analyzers attempt to return vulnerability severity level values whenever
possible. The following is a list of available GitLab vulnerability severity levels, ranked from
@@ -65,7 +68,7 @@ the following tables:
| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example |
|------------------------------------------------------------------------|--------------------------|----------------------------|--------------------------------------------------------------|
-| [`container-scanning`](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning)| **{check-circle}** Yes | String | `Unknown`, `Low`, `Medium`, `High`, `Critical` |
+| [`container-scanning`](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning)| {{< icon name="check-circle" >}} Yes | String | `Unknown`, `Low`, `Medium`, `High`, `Critical` |
When available, the vendor severity level takes precedence and is used by the analyzer. If that is not available then it falls back on the CVSS v3.1 rating. If that is also not available, then the CVSS v2.0 rating is used instead. Details on this implementation are available on the issue for [trivy](https://github.com/aquasecurity/trivy/issues/310).
@@ -73,19 +76,19 @@ When available, the vendor severity level takes precedence and is used by the an
| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example |
|------------------------------------------------------------------------------------------|------------------------------|----------------------------|-------------------------------------|
-| [`Browser-based DAST`](../dast/browser/_index.md) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW`, `INFO` |
+| [`Browser-based DAST`](../dast/browser/_index.md) | {{< icon name="check-circle" >}} Yes | String | `HIGH`, `MEDIUM`, `LOW`, `INFO` |
## API security testing
| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example |
|------------------------------------------------------------------------------------------|------------------------------|----------------------------|-------------------------------------|
-| [`API security testing`](../api_security_testing/_index.md) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` |
+| [`API security testing`](../api_security_testing/_index.md) | {{< icon name="check-circle" >}} Yes | String | `HIGH`, `MEDIUM`, `LOW` |
## Dependency Scanning
| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example |
|------------------------------------------------------------------------------------------|------------------------------|----------------------------|-------------------------------------|
-| [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | **{check-circle}** Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating <sup>1</sup> | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` |
+| [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | {{< icon name="check-circle" >}} Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating <sup>1</sup> | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` |
The CVSS v3.1 rating is used to calculate the severity level. If it's not available, the CVSS v2.0 rating is used instead.
@@ -97,17 +100,17 @@ All fuzz testing results are reported as Unknown. They should be reviewed and tr
| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example |
|----------------------------------------------------------------------------------|--------------------------|----------------------------|------------------------------------|
-| [`kubesec`](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | **{check-circle}** Yes | String | `CriticalSeverity`, `InfoSeverity` |
-| [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `4`, `5` |
-| [`semgrep`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) | **{check-circle}** Yes | String | `error`, `warning`, `note`, `none` |
-| [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | **{check-circle}** Yes | Not applicable | Hardcodes all severity levels to `Unknown` |
-| [`SpotBugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `11`, `12`, `18` |
+| [`kubesec`](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | {{< icon name="check-circle" >}} Yes | String | `CriticalSeverity`, `InfoSeverity` |
+| [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | {{< icon name="check-circle" >}} Yes | Integer | `1`, `2`, `3`, `4`, `5` |
+| [`semgrep`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) | {{< icon name="check-circle" >}} Yes | String | `error`, `warning`, `note`, `none` |
+| [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | {{< icon name="check-circle" >}} Yes | Not applicable | Hardcodes all severity levels to `Unknown` |
+| [`SpotBugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | {{< icon name="check-circle" >}} Yes | Integer | `1`, `2`, `3`, `11`, `12`, `18` |
## IaC Scanning
| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example |
|----------------------------------------------------------------------------------------------------------|--------------------------|----------------------------|------------------------------------|
-| [`kics`](https://gitlab.com/gitlab-org/security-products/analyzers/kics) | **{check-circle}** Yes | String | `error`, `warning`, `note`, `none` (gets mapped to `info` in [analyzer version 3.7.0 and later](https://gitlab.com/gitlab-org/security-products/analyzers/kics/-/releases/v3.7.0)) |
+| [`kics`](https://gitlab.com/gitlab-org/security-products/analyzers/kics) | {{< icon name="check-circle" >}} Yes | String | `error`, `warning`, `note`, `none` (gets mapped to `info` in [analyzer version 3.7.0 and later](https://gitlab.com/gitlab-org/security-products/analyzers/kics/-/releases/v3.7.0)) |
### KICS severity mapping
diff --git a/doc/user/application_security/vulnerability_report/_index.md b/doc/user/application_security/vulnerability_report/_index.md
index cf807ac19c753811ec03730c82367b65123719f5..e7991f40119af8b68ff84ed189a4cc8541d3c54d 100644
--- a/doc/user/application_security/vulnerability_report/_index.md
+++ b/doc/user/application_security/vulnerability_report/_index.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Vulnerability Report
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Vulnerability Resolution activity icon [introduced](https://gitlab.com/groups/gitlab-org/-/epics/15036) in GitLab 17.5 with a flag named [`vulnerability_report_vr_badge`](https://gitlab.com/gitlab-org/gitlab/-/issues/486549). Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171718) in GitLab 17.6.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Vulnerability Resolution activity icon [introduced](https://gitlab.com/groups/gitlab-org/-/epics/15036) in GitLab 17.5 with a flag named [`vulnerability_report_vr_badge`](https://gitlab.com/gitlab-org/gitlab/-/issues/486549). Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171718) in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of Vulnerability Resolution activity icon is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It contains
cumulative results of all successful jobs, regardless of whether the pipeline was successful. The scan results from a
pipeline are ingested either after the job in the pipeline is complete or when the pipeline is [blocked by manual jobs](../vulnerability_report/pipeline.md#security-reports-from-pipelines-in-a-blocked-or-incomplete-state). The report is updated by the last scan pipeline to run against the default branch.
@@ -40,18 +50,18 @@ For projects, the Vulnerability Report also contains:
The **Activity** column contains icons to indicate the activity, if any, taken on the vulnerability
in that row:
-- Issues **{issues}**: Links to issues created for the vulnerability. For more information, see
+- Issues {{< icon name="issues" >}}: Links to issues created for the vulnerability. For more information, see
[Create a GitLab issue for a vulnerability](../vulnerabilities/_index.md#create-a-gitlab-issue-for-a-vulnerability).
-- Merge requests **{merge-request}**: Links to merge requests created for the vulnerability. For more information, see
+- Merge requests {{< icon name="merge-request" >}}: Links to merge requests created for the vulnerability. For more information, see
[Resolve a vulnerability with a merge request](../vulnerabilities/_index.md#resolve-a-vulnerability-with-a-merge-request).
-- Checked circle **{check-circle-dashed}**: The vulnerability has been remediated.
-- False positive **{false-positive}**: The scanner determined this vulnerability to be a false
+- Checked circle {{< icon name="check-circle-dashed" >}}: The vulnerability has been remediated.
+- False positive {{< icon name="false-positive" >}}: The scanner determined this vulnerability to be a false
positive.
-- Solution **{bulb}**: Indicates that the vulnerability has a solution available.
-- Vulnerability Resolution **{tanuki-ai}**: Indicates that the vulnerability has an available AI resolution.
+- Solution {{< icon name="bulb" >}}: Indicates that the vulnerability has a solution available.
+- Vulnerability Resolution {{< icon name="tanuki-ai" >}}: Indicates that the vulnerability has an available AI resolution.
To open an issue created for a vulnerability, hover over the **Activity** entry, then select the link.
-The issue icon (**{issues}**) indicates the issue's status. If [Jira issue support](../../../integration/jira/configure.md) is enabled, the
+The issue icon ({{< icon name="issues" >}}) indicates the issue's status. If [Jira issue support](../../../integration/jira/configure.md) is enabled, the
issue link found in the **Activity** entry links out to the issue in Jira. Unlike GitLab issues, the
status of a Jira issue is not shown in the GitLab UI.
@@ -75,8 +85,12 @@ To view the vulnerability report:
## Filtering vulnerabilities
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/452492) the **Identifier** filter in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `vulnerability_filtering_by_identifier`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/502930) in GitLab 17.9. Feature flag `vulnerability_filtering_by_identifier` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/452492) the **Identifier** filter in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `vulnerability_filtering_by_identifier`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/502930) in GitLab 17.9. Feature flag `vulnerability_filtering_by_identifier` removed.
+
+{{< /history >}}
You can filter vulnerabilities in the vulnerability report to more efficiently triage them.
@@ -99,9 +113,13 @@ You can filter by:
### Filter vulnerabilities
-> - Improved filtering [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13339) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `vulnerability_report_advanced_filtering`. Disabled by default.
-> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/437128) in GitLab 17.1.
-> - [Generally available in 17.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157172). Feature flag `vulnerability_report_advanced_filtering` removed.
+{{< history >}}
+
+- Improved filtering [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13339) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `vulnerability_report_advanced_filtering`. Disabled by default.
+- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/437128) in GitLab 17.1.
+- [Generally available in 17.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157172). Feature flag `vulnerability_report_advanced_filtering` removed.
+
+{{< /history >}}
Filter the vulnerability report to focus on a subset of vulnerabilities.
@@ -109,7 +127,7 @@ To filter the list of vulnerabilities:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > Vulnerability report**.
-1. Optional. To remove the default filters, select **Clear** (**{clear}**).
+1. Optional. To remove the default filters, select **Clear** ({{< icon name="clear" >}}).
1. Above the list of vulnerabilities, select the filter bar.
1. In the dropdown list that appears, select an attribute you want to filter by, then select the
values from the dropdown list.
@@ -120,7 +138,11 @@ To filter the list of vulnerabilities:
### Tool filter
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11237) for projects in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11237) for projects in GitLab 16.6.
+
+{{< /history >}}
You can filter vulnerabilities by the tool that detected them. By default, the vulnerability report
lists vulnerabilities from all tools. For details of each of the available tools, see
@@ -152,15 +174,22 @@ The content of the Project filter varies:
### Activity filter
-> - Introduced in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `activity_filter_has_remediations`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/429262) in GitLab 16.9. Feature flag `activity_filter_has_remediations` removed.
-> - Activity filter option **GitLab Duo (AI)** [introduced](https://gitlab.com/groups/gitlab-org/-/epics/15036) in GitLab 17.5 with a flag named [`vulnerability_report_vr_filter`](https://gitlab.com/gitlab-org/gitlab/-/issues/486534). Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171718) in GitLab 17.6.
+{{< history >}}
+
+- Introduced in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `activity_filter_has_remediations`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/429262) in GitLab 16.9. Feature flag `activity_filter_has_remediations` removed.
+- Activity filter option **GitLab Duo (AI)** [introduced](https://gitlab.com/groups/gitlab-org/-/epics/15036) in GitLab 17.5 with a flag named [`vulnerability_report_vr_filter`](https://gitlab.com/gitlab-org/gitlab/-/issues/486534). Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171718) in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the activity filter option **GitLab Duo (AI)** is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
The activity filter behaves differently from the other filters. You can select only one value in
each category. To remove a filter, from the activity filter dropdown list select the filter you want to remove.
@@ -192,18 +221,22 @@ The **GitLab Duo (AI)** filter is available when:
## Grouping vulnerabilities
-> - Grouping of vulnerabilities per project [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10164) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `vulnerability_report_grouping`. Disabled by default.
-> - Grouping of vulnerabilities per project [enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134073) in GitLab 16.5.
-> - Grouping of vulnerabilities per project [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/422509) in GitLab 16.6. Feature flag `vulnerability_report_grouping` removed.
-> - Grouping of vulnerabilities per group [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137778) in GitLab 16.7 with a flag named [`group_level_vulnerability_report_grouping`](https://gitlab.com/gitlab-org/gitlab/-/issues/432778). Disabled by default.
-> - Grouping of vulnerabilities per group [enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157949) in GitLab 17.2.
-> - Grouping of vulnerabilities per group [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472669) in GitLab 17.3. Feature flag `group_level_vulnerability_report_grouping` removed.
-> - OWASP top 10 grouping of vulnerabilities per group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432618) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `vulnerability_owasp_top_10_group`. Disabled by default.
-> - OWASP top 10 grouping of vulnerabilities per group [enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/437253) in GitLab 17.4.
-> - OWASP top 10 grouping of vulnerabilities per group [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/437253) in GitLab 17.4. Feature flag `vulnerability_owasp_top_10_group` removed.
-> - Non-OWASP category in OWASP top 10 grouping [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442526) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `owasp_top_10_null_filtering`. Disabled by default.
-> - Non-OWASP category in OWASP top 10 grouping [enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/463783) in GitLab 17.5.
-> - Non-OWASP category in OWASP top 10 grouping [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/463783) in GitLab 17.6. Feature flag `owasp_top_10_null_filtering` removed.
+{{< history >}}
+
+- Grouping of vulnerabilities per project [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10164) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `vulnerability_report_grouping`. Disabled by default.
+- Grouping of vulnerabilities per project [enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134073) in GitLab 16.5.
+- Grouping of vulnerabilities per project [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/422509) in GitLab 16.6. Feature flag `vulnerability_report_grouping` removed.
+- Grouping of vulnerabilities per group [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137778) in GitLab 16.7 with a flag named [`group_level_vulnerability_report_grouping`](https://gitlab.com/gitlab-org/gitlab/-/issues/432778). Disabled by default.
+- Grouping of vulnerabilities per group [enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157949) in GitLab 17.2.
+- Grouping of vulnerabilities per group [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472669) in GitLab 17.3. Feature flag `group_level_vulnerability_report_grouping` removed.
+- OWASP top 10 grouping of vulnerabilities per group [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432618) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `vulnerability_owasp_top_10_group`. Disabled by default.
+- OWASP top 10 grouping of vulnerabilities per group [enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/437253) in GitLab 17.4.
+- OWASP top 10 grouping of vulnerabilities per group [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/437253) in GitLab 17.4. Feature flag `vulnerability_owasp_top_10_group` removed.
+- Non-OWASP category in OWASP top 10 grouping [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442526) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `owasp_top_10_null_filtering`. Disabled by default.
+- Non-OWASP category in OWASP top 10 grouping [enabled on GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/463783) in GitLab 17.5.
+- Non-OWASP category in OWASP top 10 grouping [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/463783) in GitLab 17.6. Feature flag `owasp_top_10_null_filtering` removed.
+
+{{< /history >}}
You can group vulnerabilities on the vulnerability report page to more efficiently triage them.
@@ -233,7 +266,11 @@ To view more details of a vulnerability, select the vulnerability's **Descriptio
## Change status of vulnerabilities
-> - Providing a comment and dismissal reason [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408366) in GitLab 16.0.
+{{< history >}}
+
+- Providing a comment and dismissal reason [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408366) in GitLab 16.0.
+
+{{< /history >}}
As you triage vulnerabilities you can change their status, including dismissing vulnerabilities.
@@ -270,7 +307,11 @@ To sort vulnerabilities by the date each vulnerability was detected, select the
## Export vulnerability details
-> - Added "Dismissal Reason" as a column in the CSV export [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434076) in GitLab 16.8.
+{{< history >}}
+
+- Added "Dismissal Reason" as a column in the CSV export [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434076) in GitLab 16.8.
+
+{{< /history >}}
You can export details of the vulnerabilities listed in the Vulnerability Report. The export format
is CSV (comma separated values). All vulnerabilities are included because filters do not
@@ -298,12 +339,15 @@ Fields included are:
- CVSS Vectors
- [Dismissal Reason](../vulnerabilities/_index.md#vulnerability-dismissal-reasons)
-NOTE:
+{{< alert type="note" >}}
+
Full details are available through our
[Job Artifacts API](../../../api/job_artifacts.md#download-a-single-artifact-file-from-specific-tag-or-branch).
Use one of the `gl-*-report.json` report filenames in place of `*artifact_path`
to obtain, for example, the path of files in which vulnerabilities were detected.
+{{< /alert >}}
+
The Status field's values shown in the vulnerability report are different to those contained
in the vulnerability export. Use the following reference table to match them.
@@ -321,16 +365,23 @@ To export details of all vulnerabilities listed in the Vulnerability Report, sel
The details are retrieved from the database, then the CSV file is downloaded to your local
computer.
-NOTE:
+{{< alert type="note" >}}
+
It may take several minutes for the download to start if your project contains
thousands of vulnerabilities. Do not close the page until the download finishes.
Some CSV readers have limitations on the number of rows or size of columns which
may make them incompatible with larger exports. The vulnerability export does not
account for the limitations of individual programs.
+{{< /alert >}}
+
## Manually add a vulnerability
-> - [Feature flag `new_vulnerability_form`](https://gitlab.com/gitlab-org/gitlab/-/issues/359049) removed in GitLab 15.0.
+{{< history >}}
+
+- [Feature flag `new_vulnerability_form`](https://gitlab.com/gitlab-org/gitlab/-/issues/359049) removed in GitLab 15.0.
+
+{{< /history >}}
Add a vulnerability manually when it is not available in the GitLab vulnerabilities database. You
can add a vulnerability only in a project's vulnerability report.
diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md
index 238df20e9c298562d8fe36dcf55d6e9f02f7eca2..ff44336ba5460ee226deb143e14cdf23f9719cf1 100644
--- a/doc/user/application_security/vulnerability_report/pipeline.md
+++ b/doc/user/application_security/vulnerability_report/pipeline.md
@@ -5,16 +5,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Vulnerabilities in a pipeline
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/490334) in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `dependency_scanning_for_pipelines_with_cyclonedx_reports`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/490332) in GitLab 17.9.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/490334) in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `dependency_scanning_for_pipelines_with_cyclonedx_reports`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/490332) in GitLab 17.9.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
This feature flag controls the recently added support for pipeline security findings based on [CycloneDX reports](../dependency_scanning/dependency_scanning_sbom/_index.md#cyclonedx-software-bill-of-materials).
+{{< /alert >}}
+
All enabled security analyzers run in the pipeline and output their results as artifacts. These
artifacts are processed, including [deduplication](#deduplication-process), and the results are
listed on the pipeline **Security** tab. By identifying vulnerability
@@ -91,7 +101,11 @@ default branch are incorporated after the pipeline finishes, according to the fo
## Security reports from pipelines in a blocked or incomplete state
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439691) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `include_manual_to_pipeline_completion`. Enabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/439691) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `include_manual_to_pipeline_completion`. Enabled by default.
+
+{{< /history >}}
| Pipeline status | Pipeline completion | What vulnerabilities are displayed? |
|:---------------------|:--------------------|:-------------------------------------------------|
@@ -101,7 +115,11 @@ default branch are incorporated after the pipeline finishes, according to the fo
## Retention period for findings
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351524) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351524) in GitLab 15.5.
+
+{{< /history >}}
Findings are no longer available:
@@ -113,13 +131,20 @@ To view findings, either:
- Run a new pipeline.
- Download the related CI job artifacts if they are available.
-NOTE:
+{{< alert type="note" >}}
+
This does not apply for the vulnerabilities existing on the default branch.
+{{< /alert >}}
+
## Change status of findings
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331408) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `pipeline_security_dashboard_graphql`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/328818) in GitLab 17.4. Feature flag `pipeline_security_dashboard_graphql` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331408) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `pipeline_security_dashboard_graphql`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/328818) in GitLab 17.4. Feature flag `pipeline_security_dashboard_graphql` removed.
+
+{{< /history >}}
To change the status of findings to **Dismiss** or **Needs triage**:
@@ -208,9 +233,12 @@ This can be resolved by upgrading to GitLab 16.9 and later.
### Report parsing and scan ingestion errors
-NOTE:
+{{< alert type="note" >}}
+
These steps are to be used by GitLab Support to reproduce such errors.
+{{< /alert >}}
+
Some security scans may result in errors in the **Security** tab of the pipeline related to report parsing or scan ingestion. If it is not possible to get a copy of the project from the user, you can reproduce the error using the report generated from the scan.
To recreate the error:
diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md
index c2b6ced4fa2b4fa85f9291248c5c8d089d96c6f8..1246898f80a1fc5f44ab2be8cf0f328fdd6425cc 100644
--- a/doc/user/asciidoc.md
+++ b/doc/user/asciidoc.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Use AsciiDoc files in your GitLab project, and understand AsciiDoc syntax."
+description: Use AsciiDoc files in your GitLab project, and understand AsciiDoc syntax.
title: AsciiDoc
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab uses the [Asciidoctor](https://asciidoctor.org) gem to convert AsciiDoc content to HTML5.
Consult the [Asciidoctor User Manual](https://asciidoctor.org/docs/user-manual/) for a complete Asciidoctor reference.
@@ -204,11 +207,14 @@ v1.0, 2019-01-01
## Includes
-NOTE:
+{{< alert type="note" >}}
+
[Wiki pages](project/wiki/_index.md#create-a-new-wiki-page) created with the AsciiDoc
format are saved with the file extension `.asciidoc`. When working with AsciiDoc wiki
pages, change the filename from `.adoc` to `.asciidoc`.
+{{< /alert >}}
+
```plaintext
include::basics.adoc[]
```
@@ -228,10 +234,13 @@ inclusive of transitive dependencies. To customize the number of processed inclu
the application setting `asciidoc_max_includes` with the
[application settings API](../api/settings.md#available-settings).
-NOTE:
+{{< alert type="note" >}}
+
The current maximum allowed value for `asciidoc_max_includes` is 64. If the value is
too high, it might cause performance issues in some situations.
+{{< /alert >}}
+
To use includes from separate pages or external URLs, enable the `allow-uri-read`
in [application settings](../administration/wikis/_index.md#allow-uri-includes-for-asciidoc).
diff --git a/doc/user/clusters/agent/_index.md b/doc/user/clusters/agent/_index.md
index 84a6df57963d9123c395081260a062977ab00e63..9f4419f0bea61c00182a8582a6391e82ab98c1cb 100644
--- a/doc/user/clusters/agent/_index.md
+++ b/doc/user/clusters/agent/_index.md
@@ -5,7 +5,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Connecting a Kubernetes cluster with GitLab
---
-> - Flux [recommended](https://gitlab.com/gitlab-org/gitlab/-/issues/357947#note_1253489000) as GitOps solution in GitLab 15.10.
+{{< history >}}
+
+- Flux [recommended](https://gitlab.com/gitlab-org/gitlab/-/issues/357947#note_1253489000) as GitOps solution in GitLab 15.10.
+
+{{< /history >}}
You can connect your Kubernetes cluster with GitLab to deploy, manage,
and monitor your cloud-native solutions.
@@ -31,11 +35,18 @@ and you can scale a single installation to multiple tenants.
## Receptive agents
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12180) in GitLab 17.4.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12180) in GitLab 17.4.
+{{< /history >}}
Receptive agents allow GitLab to integrate with Kubernetes clusters that cannot establish a network connection
to the GitLab instance, but can be connected to by GitLab. For example, this can occur when:
diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md
index 878088f9ee51582d2c3dbefb4a6c0d9e72d223a5..d4c49cd30cdf377de6722a6c9ba780710a1430c9 100644
--- a/doc/user/clusters/agent/ci_cd_workflow.md
+++ b/doc/user/clusters/agent/ci_cd_workflow.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using GitLab CI/CD with a Kubernetes cluster
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Agent connection sharing limit [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149844) from 100 to 500 in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Agent connection sharing limit [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149844) from 100 to 500 in GitLab 17.0.
+
+{{< /history >}}
You can use GitLab CI/CD to safely connect, deploy, and update your Kubernetes clusters.
@@ -58,8 +65,12 @@ Authorization configuration can take one or two minutes to propagate.
### Authorize the agent to access your projects
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346566) to remove hierarchy restrictions in GitLab 15.6.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/356831) to allow authorizing projects in a user namespace in GitLab 15.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346566) to remove hierarchy restrictions in GitLab 15.6.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/356831) to allow authorizing projects in a user namespace in GitLab 15.7.
+
+{{< /history >}}
To authorize the agent to access the GitLab project where you keep Kubernetes manifests:
@@ -83,7 +94,11 @@ Choose the context to run `kubectl` commands from your CI/CD scripts.
### Authorize the agent to access projects in your groups
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346566) to remove hierarchy restrictions in GitLab 15.6.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346566) to remove hierarchy restrictions in GitLab 15.6.
+
+{{< /history >}}
To authorize the agent to access all of the GitLab projects in a group or subgroup:
@@ -193,11 +208,18 @@ To configure your client, do one of the following:
## Restrict project and group access by using impersonation
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/357934) in GitLab 15.5 to add impersonation support for environment tiers.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/357934) in GitLab 15.5 to add impersonation support for environment tiers.
+
+{{< /history >}}
By default, your CI/CD job inherits all the permissions from the service account used to install the
agent in the cluster.
@@ -299,11 +321,18 @@ See the [official Kubernetes documentation for details](https://kubernetes.io/do
## Restrict project and group access to specific environments
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343885) in GitLab 15.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343885) in GitLab 15.7.
+
+{{< /history >}}
By default, if your agent is [available to a project](#authorize-the-agent), all of the project's CI/CD jobs can use that agent.
@@ -332,17 +361,27 @@ In this example:
## Restrict access to the agent to protected branches
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467936) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `kubernetes_agent_protected_branches`. Disabled by default.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467936) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `kubernetes_agent_protected_branches`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
To restrict access to the agent to only jobs run on [protected branches](../../project/repository/branches/protected.md):
- Add `protected_branches_only: true` to `ci_access.projects` or `ci_access.groups`.
diff --git a/doc/user/clusters/agent/getting_started.md b/doc/user/clusters/agent/getting_started.md
index c3c5184c9d5c431b354b36e33e46f5ceeba400a6..1f0bbfe8fb2d1d5584041a76bba947fc3f9dbd71 100644
--- a/doc/user/clusters/agent/getting_started.md
+++ b/doc/user/clusters/agent/getting_started.md
@@ -142,8 +142,11 @@ To view your dashboard:
## Secure the deployment
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
So far, we've deployed an agent using the `.gitlab/agents/testing/config.yaml` file.
This configuration enables user access using the service account configured for the agent deployment. User access is used by the dashboard for Kubernetes, and for local access.
diff --git a/doc/user/clusters/agent/getting_started_deployments.md b/doc/user/clusters/agent/getting_started_deployments.md
index ac644c5276017f059d1f4674f28e6f526d3ec9aa..d5cde547c56eda6b940476ff6bdae67de992fd24 100644
--- a/doc/user/clusters/agent/getting_started_deployments.md
+++ b/doc/user/clusters/agent/getting_started_deployments.md
@@ -190,9 +190,12 @@ In this section, you'll build a simple Kubernetes manifest as an OCI artifact, t
## Secure the GitLab pipeline access
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The previously deployed agent is configured using the `.gitlab/agents/testing/config.yaml` file.
By default, the configuration enables access to the clusters configured in the project where the GitLab pipelines run.
diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md
index cffbb551f0289ddd2ae6f364d121d37a957646b4..862553786b02eb4743aabcdd5dd09a7f40c0ea9b 100644
--- a/doc/user/clusters/agent/gitops.md
+++ b/doc/user/clusters/agent/gitops.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Using GitOps with a Kubernetes cluster
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346585) to make the `id` attribute optional in GitLab 15.7.
-> - Specifying a branch, tag, or commit reference to fetch the Kubernetes manifest files [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4516) in GitLab 15.7.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/395364) in GitLab 16.1 to prioritize Flux for GitOps.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346585) to make the `id` attribute optional in GitLab 15.7.
+- Specifying a branch, tag, or commit reference to fetch the Kubernetes manifest files [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4516) in GitLab 15.7.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/395364) in GitLab 16.1 to prioritize Flux for GitOps.
+
+{{< /history >}}
GitLab integrates [Flux](https://fluxcd.io/flux/) for GitOps.
To get started with Flux, see the [Flux for GitOps tutorial](gitops/flux_tutorial.md).
@@ -82,9 +89,13 @@ For additional repository structure recommendations, see the [Flux documentation
## Immediate Git repository reconciliation
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392852) in GitLab 16.1 with a [flag](../../../administration/feature_flags.md) named `notify_kas_on_git_push`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126527) in GitLab 16.2.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410429) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392852) in GitLab 16.1 with a [flag](../../../administration/feature_flags.md) named `notify_kas_on_git_push`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126527) in GitLab 16.2.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410429) in GitLab 16.3.
+
+{{< /history >}}
Usually, the Flux source controller reconciles Git repositories at configured intervals.
This can cause delays between a `git push` and the reconciliation of the cluster state, and results in
@@ -106,11 +117,14 @@ but it doesn't guarantee that every `git push` event is received. You should sti
[`GitRepository.spec.interval`](https://fluxcd.io/flux/components/source/gitrepositories/#interval)
to an acceptable duration.
-NOTE:
+{{< alert type="note" >}}
+
The agent only has access to the agent configuration project and all public projects.
The agent is not able to immediately reconcile any private projects, except the agent configuration project.
Allowing the agent to access private projects is proposed in [issue 389393](https://gitlab.com/gitlab-org/gitlab/-/issues/389393).
+{{< /alert >}}
+
### Custom webhook endpoints
When the agent for Kubernetes calls the `Receiver` webhook,
@@ -138,12 +152,15 @@ You can use this if you run an agent outside a cluster
and you haven't [configured an `Ingress`](https://fluxcd.io/flux/guides/webhook-receivers/#expose-the-webhook-receiver)
for the Flux notification controller.
-WARNING:
+{{< alert type="warning" >}}
+
You should configure only trusted service proxy URLs.
When you provide a service proxy URL,
the agent for Kubernetes sends typical Kubernetes API requests which include
the credentials necessary to authenticate with the API service.
+{{< /alert >}}
+
## Token management
To use certain Flux features, you might need multiple access tokens. Additionally, you can use multiple token types to achieve the same result.
diff --git a/doc/user/clusters/agent/gitops/example_repository_structure.md b/doc/user/clusters/agent/gitops/example_repository_structure.md
index a2b77b903b458d10b3f9373577e33fd1b303fb09..6e9425224533d5f6b2eaa918ee3cc4019fe23dd2 100644
--- a/doc/user/clusters/agent/gitops/example_repository_structure.md
+++ b/doc/user/clusters/agent/gitops/example_repository_structure.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../getting_started_deployments.md'
-remove_date: '2025-02-07'
+redirect_to: ../getting_started_deployments.md
+remove_date: "2025-02-07"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md
index a2b77b903b458d10b3f9373577e33fd1b303fb09..6e9425224533d5f6b2eaa918ee3cc4019fe23dd2 100644
--- a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md
+++ b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../getting_started_deployments.md'
-remove_date: '2025-02-07'
+redirect_to: ../getting_started_deployments.md
+remove_date: "2025-02-07"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md
index 0bfd0ef837b75b2089430b64f91ac548af24d4bb..e8b25e8c7f9261260e24589d4ca05a4dc249ef7a 100644
--- a/doc/user/clusters/agent/gitops/flux_tutorial.md
+++ b/doc/user/clusters/agent/gitops/flux_tutorial.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../getting_started.md'
-remove_date: '2025-02-07'
+redirect_to: ../getting_started.md
+remove_date: "2025-02-07"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/clusters/agent/gitops/migrate_to_flux.md b/doc/user/clusters/agent/gitops/migrate_to_flux.md
index 9d5afbeea4905f872d3601acaa749abe76e3a53a..dcdfcefc77f40dca4dd2e4bf7477fc9d947e1efc 100644
--- a/doc/user/clusters/agent/gitops/migrate_to_flux.md
+++ b/doc/user/clusters/agent/gitops/migrate_to_flux.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrate from legacy GitOps to Flux
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Most users can migrate from their legacy agent-based GitOps solution
to Flux without additional work or downtime. In most cases, Flux can
diff --git a/doc/user/clusters/agent/install/_index.md b/doc/user/clusters/agent/install/_index.md
index 9773bfc025f6ec1c41ce140ef0e8d360b35a5282..a53cc90d0a993bda3e2c5ccd6ef1382dd10c1de0 100644
--- a/doc/user/clusters/agent/install/_index.md
+++ b/doc/user/clusters/agent/install/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Installing the agent for Kubernetes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To connect a Kubernetes cluster to GitLab, you must install an agent in your cluster.
@@ -120,26 +123,39 @@ You must register an agent before you can install the agent in your cluster. To
1. GitLab generates an access token for the agent. You need this token to install the agent
in your cluster.
- WARNING:
+ {{< alert type="warning" >}}
+
Securely store the agent access token. A bad actor can use this token to access source code in the agent's configuration project, access source code in any public project on the GitLab instance, or even, under very specific conditions, obtain a Kubernetes manifest.
+ {{< /alert >}}
+
1. Copy the command under **Recommended installation method**. You need it when you use
the one-liner installation method to install the agent in your cluster.
#### Option 2: GitLab connects to agent (receptive agent)
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12180) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12180) in GitLab 17.4.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
The GitLab Agent Helm Chart release does not fully support mTLS authentication.
You should authenticate with the JWT method instead.
Support for mTLS is tracked in
[issue 64](https://gitlab.com/gitlab-org/charts/gitlab-agent/-/issues/64).
+{{< /alert >}}
+
[Receptive agents](../_index.md#receptive-agents) allow GitLab to integrate with Kubernetes clusters that
cannot establish a network connection to the GitLab instance, but can be connected to by GitLab.
@@ -183,14 +199,20 @@ If you do not know which one to choose, we recommend starting with Helm.
To install a receptive agent, follow the steps in [GitLab connects to agent (receptive agent)](#option-2-gitlab-connects-to-agent-receptive-agent).
-NOTE:
+{{< alert type="note" >}}
+
To connect to multiple clusters, you must configure, register, and install an agent in each cluster. Make sure to give each agent a unique name.
+{{< /alert >}}
+
#### Install the agent with Helm
-WARNING:
+{{< alert type="warning" >}}
+
For simplicity, the default Helm chart configuration sets up a service account for the agent with `cluster-admin` rights. You should not use this on production systems. To deploy to a production system, follow the instructions in [Customize the Helm installation](#customize-the-helm-installation) to create a service account with the minimum permissions required for your deployment and specify that during installation.
+{{< /alert >}}
+
To install the agent on your cluster using Helm:
1. [Install the Helm CLI](https://helm.sh/docs/intro/install/).
@@ -244,7 +266,11 @@ an [auto-generated self-signed wildcard certificate](https://docs.gitlab.com/cha
##### Use the agent behind an HTTP proxy
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351867) in GitLab 15.0, the GitLab agent Helm chart supports setting environment variables.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351867) in GitLab 15.0, the GitLab agent Helm chart supports setting environment variables.
+
+{{< /history >}}
To configure an HTTP proxy when using the Helm chart, you can use the environment variables `HTTP_PROXY`, `HTTPS_PROXY`,
and `NO_PROXY`. Upper and lowercase are both acceptable.
@@ -259,19 +285,25 @@ helm upgrade --install gitlab-agent gitlab/gitlab-agent \
...
```
-NOTE:
+{{< alert type="note" >}}
+
DNS rebind protection is disabled when either the `HTTP_PROXY` or the `HTTPS_PROXY` environment variable is set,
and the domain DNS can't be resolved.
+{{< /alert >}}
+
#### Advanced installation method
GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). This method provides greater flexibility, but is only recommended for advanced users.
## Install multiple agents in your cluster
-NOTE:
+{{< alert type="note" >}}
+
In most cases, you should run one agent per cluster and use the agent impersonation features (Premium and Ultimate only) to support multi-tenancy. If you must run multiple agents, we would love to hear from you about any issues you encounter. You can provide your feedback in [issue 454110](https://gitlab.com/gitlab-org/gitlab/-/issues/454110).
+{{< /alert >}}
+
To install a second agent in your cluster, you can follow the [previous steps](#register-the-agent-with-gitlab) a second time. To avoid resource name collisions within the cluster, you must either:
- Use a different release name for the agent, for example, `second-gitlab-agent`:
@@ -313,13 +345,16 @@ For the best experience, the version of the agent installed in your cluster shou
### Update the agent version
-NOTE:
+{{< alert type="note" >}}
+
Instead of using `--reuse-values`, you should specify all needed values.
If you use `--reuse-values`, you might miss new defaults or use deprecated values.
To retrieve previous `--set` arguments, use `helm get values <release name>`.
You can save the values to a file with `helm get values gitlab-agent > agent.yaml`, and pass the file to Helm with `-f`:
`helm upgrade gitlab-agent gitlab/gitlab-agent -f agent.yaml`. This safely replaces the behavior of `--reuse-values`.
+{{< /alert >}}
+
To update the agent to the latest version, you can run:
```shell
diff --git a/doc/user/clusters/agent/managed_kubernetes_resources.md b/doc/user/clusters/agent/managed_kubernetes_resources.md
index 6558806e44c7ccdcaa8417eaf475a380cfe4bfa7..aa8733fc29c8b3b5b1b902d3d348b465a7368ad4 100644
--- a/doc/user/clusters/agent/managed_kubernetes_resources.md
+++ b/doc/user/clusters/agent/managed_kubernetes_resources.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab-managed Kubernetes resources
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/16130) in GitLab 17.9
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/16130) in GitLab 17.9
+
+{{< /history >}}
Use GitLab-managed Kubernetes resources to provision Kubernetes resources with environment templates. An environment template can:
diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md
index 5731f958d966bce72d1a59497b9a816cbaa26fe8..b71189954b976c3115b435b585f8d4f5f1ea6423 100644
--- a/doc/user/clusters/agent/user_access.md
+++ b/doc/user/clusters/agent/user_access.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Grant users Kubernetes access
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [beta](../../../policy/development_stages_support.md#beta).
-> - Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2.
-> - Feature flags `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125835) in GitLab 16.2.
-> - The [limit of agent connection sharing was raised](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149844) from 100 to 500 in GitLab 17.0
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [beta](../../../policy/development_stages_support.md#beta).
+- Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2.
+- Feature flags `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125835) in GitLab 16.2.
+- The [limit of agent connection sharing was raised](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149844) from 100 to 500 in GitLab 17.0
+
+{{< /history >}}
As an administrator of Kubernetes clusters in an organization, you can grant Kubernetes access to members
of a specific project or group.
@@ -63,9 +70,12 @@ user_access:
## Configure access with user impersonation
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can grant access to a Kubernetes cluster and transform
requests into impersonation requests for authenticated users.
@@ -151,7 +161,11 @@ subjects:
## Access a cluster with the Kubernetes API
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131144) in GitLab 16.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131144) in GitLab 16.4.
+
+{{< /history >}}
You can configure an agent to allow GitLab users to access a cluster with the Kubernetes API.
diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md
index 2a006df1c13a633189f75e69551af0d49e7f3df7..26745d511d2be49f46bb8b1fedd033fee2e2f620 100644
--- a/doc/user/clusters/agent/vulnerabilities.md
+++ b/doc/user/clusters/agent/vulnerabilities.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Operational container scanning
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive is scheduled for removal in GitLab 16.0.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive is scheduled for removal in GitLab 16.0.
+
+{{< /history >}}
## Supported architectures
@@ -23,9 +30,12 @@ Before GitLab 16.9, OCS directly used the [Trivy](https://github.com/aquasecurit
OCS can be configured to run on a cadence by using `agent config` or a project's scan execution policy.
-NOTE:
+{{< alert type="note" >}}
+
If both `agent config` and `scan execution policies` are configured, the configuration from `scan execution policy` takes precedence.
+{{< /alert >}}
+
### Enable via agent configuration
To enable scanning of images within your Kubernetes cluster via the agent configuration, add a `container_scanning` configuration block to your agent
@@ -41,11 +51,16 @@ The `cadence` field is required. GitLab supports the following types of CRON syn
- A daily cadence of once per hour at a specified hour, for example: `0 18 * * *`
- A weekly cadence of once per week on a specified day and at a specified hour, for example: `0 13 * * 0`
-NOTE:
+{{< alert type="note" >}}
+
Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod.
+{{< /alert >}}
By default, operational container scanning does not scan any workloads for vulnerabilities.
You can set the `vulnerability_report` block with the `namespaces`
@@ -79,11 +94,16 @@ To enable scanning of images in your Kubernetes cluster by using scan execution
[scan execution policy editor](../../application_security/policies/scan_execution_policies.md#scan-execution-policy-editor)
to create a new schedule rule.
-NOTE:
+{{< alert type="note" >}}
+
The Kubernetes agent must be running in your cluster to scan running container images
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
Operational Container Scanning operates independently of GitLab pipelines. It is fully automated and managed by the Kubernetes Agent, which initiates new scans at the scheduled time configured in the Scan Execution Policy. The agent creates a dedicated Job within your cluster to perform the scan and report findings back to GitLab.
+{{< /alert >}}
Here is an example of a policy which enables operational container scanning within the cluster the Kubernetes agent is attached to:
@@ -108,11 +128,16 @@ The keys for a schedule rule are:
- `agents:<agent-name>` (required): The name of the agent to use for scanning
- `agents:<agent-name>:namespaces` (required): The Kubernetes namespaces to scan.
-NOTE:
+{{< alert type="note" >}}
+
Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod.
+{{< /alert >}}
You can view the complete schema within the [scan execution policy documentation](../../application_security/policies/scan_execution_policies.md#scan-execution-policies-schema).
@@ -156,11 +181,13 @@ container_scanning:
When using a fractional value for CPU, format the value as a string.
-NOTE:
+{{< alert type="note" >}}
- Resource requirements can only be set by using the agent configuration. If you enabled Operational Container Scanning through scan execution policies and need to configure resource requirements, you should do so via the agent configuration file.
- When using Google Kubernetes Engine (GKE) for Kubernetes orchestration, [the ephemeral storage limit value will always be set to equal the request value](https://cloud.google.com/kubernetes-engine/docs/concepts/autopilot-resource-requests#resource-limits). This is enforced by GKE.
+{{< /alert >}}
+
## Custom repository for Trivy K8s Wrapper
During a scan, OCS deploys pods using an image from the [Trivy K8s Wrapper repository](https://gitlab.com/security-products/trivy-k8s-wrapper/container_registry/5992609), which transmits the vulnerability report generated by [Trivy Kubernetes](https://aquasecurity.github.io/trivy/v0.54/docs/target/kubernetes) to OCS.
@@ -175,7 +202,11 @@ container_scanning:
## Configure scan timeout
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/497460) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/497460) in GitLab 17.7.
+
+{{< /history >}}
By default, the Trivy scan times out after five minutes. The agent itself provides an extra 15 minutes to read the chained configmaps and transmit the vulnerabilities.
@@ -192,7 +223,11 @@ container_scanning:
## Configure Trivy report size
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/497460) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/497460) in GitLab 17.7.
+
+{{< /history >}}
By default, the Trivy report is limited to 100 MB, which is sufficient for most scans. However, if you have a lot of workloads, you might need to increase the limit.
@@ -209,7 +244,11 @@ container_scanning:
## Configure Trivy Kubernetes resource detection
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431707) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431707) in GitLab 17.9.
+
+{{< /history >}}
By default, Trivy looks for the following Kubernetes resource types to discover scannable images:
@@ -239,7 +278,11 @@ To do this:
## Configure Trivy report artifact deletion
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/480845) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/480845) in GitLab 17.9.
+
+{{< /history >}}
By default, the GitLab agent deletes the Trivy report artifact after a scan has completed.
@@ -267,12 +310,19 @@ To view vulnerability information in GitLab:
This information can also be found under [operational vulnerabilities](../../application_security/vulnerability_report/_index.md#operational-vulnerabilities).
-NOTE:
+{{< alert type="note" >}}
+
You must have at least the Developer role.
+{{< /alert >}}
+
## Scanning private images
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415451) in GitLab 16.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415451) in GitLab 16.4.
+
+{{< /history >}}
To scan private images, the scanner relies on the image pull secrets (direct references and from the service account) to pull the image.
diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md
index 950e1e506bc3b4abde7ecb2bc2dc79c88e767eea..94fda1662dd08b658f9fc075838a5b7d6b6a8b21 100644
--- a/doc/user/clusters/agent/work_with_agent.md
+++ b/doc/user/clusters/agent/work_with_agent.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Managing the agent for Kubernetes instances
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the following tasks when you work with the agent for Kubernetes.
@@ -53,7 +56,11 @@ The agent configuration file manages the various agent features:
## View shared agents
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/395498) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/395498) in GitLab 16.1.
+
+{{< /history >}}
In addition to the agents owned by your project, you can also view agents shared with the
[`ci_access`](ci_cd_workflow.md) and [`user_access`](user_access.md) keywords. Once an agent
@@ -89,7 +96,11 @@ View and provide feedback about the UI in [this epic](https://gitlab.com/groups/
## Debug the agent
-> - The `grpc_level` was [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/669) in GitLab 15.1.
+{{< history >}}
+
+- The `grpc_level` was [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/669) in GitLab 15.1.
+
+{{< /history >}}
To debug the cluster-side component (`agentk`) of the agent, set the log
level according to the available options:
@@ -124,8 +135,12 @@ For more information about debugging, see [troubleshooting documentation](troubl
## Reset the agent token
-> - Two-token limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361030/) in GitLab 16.1 with a [flag](../../../administration/feature_flags.md) named `cluster_agents_limit_tokens_created`.
-> - Two-token limit [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/412399) in GitLab 16.2. Feature flag `cluster_agents_limit_tokens_created` removed.
+{{< history >}}
+
+- Two-token limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361030/) in GitLab 16.1 with a [flag](../../../administration/feature_flags.md) named `cluster_agents_limit_tokens_created`.
+- Two-token limit [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/412399) in GitLab 16.2. Feature flag `cluster_agents_limit_tokens_created` removed.
+
+{{< /history >}}
An agent can have only two active tokens at one time.
@@ -139,7 +154,7 @@ To reset the agent token without downtime:
1. Enter token's name and description (optional) and select **Create token**.
1. Securely store the generated token.
1. Use the token to [install the agent in your cluster](install/_index.md#install-the-agent-in-the-cluster) and to [update the agent](install/_index.md#update-the-agent-version) to another version.
-1. To delete the token you're no longer using, return to the token list and select **Revoke** (**{remove}**).
+1. To delete the token you're no longer using, return to the token list and select **Revoke** ({{< icon name="remove" >}}).
## Remove an agent
@@ -154,7 +169,7 @@ To remove an agent from the UI:
1. On the left sidebar, select **Search or go to** and find the project that contains the agent configuration file.
1. Select **Operate > Kubernetes clusters**.
-1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**).
+1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. Select **Delete agent**.
### Remove an agent with the GitLab GraphQL API
diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md
index 4611579b3e59a0ec96da4d42724da673d3d9badd..15c8f8bafd6c92e1b8b0c1ff3c28fa105eea5534 100644
--- a/doc/user/clusters/environments.md
+++ b/doc/user/clusters/environments.md
@@ -5,18 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Cluster Environments (deprecated)
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> - [Disabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/353410) in GitLab 15.0.
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
-FLAG:
+{{< /alert >}}
+
+{{< alert type="flag" >}}
+
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `certificate_based_clusters`.
+{{< /alert >}}
+
Cluster environments provide a consolidated view of which CI [environments](../../ci/environments/_index.md) are
deployed to the Kubernetes cluster and it:
diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md
index 14d0f52d7b96af6ff57cf22c82b539f793d90b0a..da855142252ce9a6c74707840cf5a0228e24f702 100644
--- a/doc/user/clusters/management_project.md
+++ b/doc/user/clusters/management_project.md
@@ -5,20 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Cluster management project (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> - [Disabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/353410) in GitLab 15.0.
-WARNING:
+{{< alert type="warning" >}}
+
The cluster management project was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
To manage cluster applications, use the [GitLab agent](agent/_index.md)
with the [Cluster Management Project Template](management_project_template.md).
-FLAG:
+{{< /alert >}}
+
+{{< alert type="flag" >}}
+
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `certificate_based_clusters`.
+{{< /alert >}}
+
A project can be designated as the management project for a cluster.
A management project can be used to run deployment jobs with
Kubernetes
diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md
index 2c38cda16675eda7ffdc8d3e2c073602f7131566..6def7adc1ba967abd0ea997d54a9732924c5612d 100644
--- a/doc/user/clusters/management_project_template.md
+++ b/doc/user/clusters/management_project_template.md
@@ -5,18 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Manage cluster applications
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides a cluster management project template, which you use
to create a project. The project includes cluster applications that integrate with GitLab
and extend GitLab functionality. You can use the pattern shown in the project to extend
your custom cluster applications.
-NOTE:
+{{< alert type="note" >}}
+
The project template works on GitLab.com without modifications. If you're on a self-managed instance, you must modify the `.gitlab-ci.yml` file.
+{{< /alert >}}
+
## Use one project for the agent and your manifests
If you **have not yet** used the agent to connect your cluster with GitLab:
@@ -44,7 +50,7 @@ If you have already configured the agent and connected a cluster with GitLab:
To create a project from the cluster management project template:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. From the list of templates, next to **GitLab Cluster Management**, select **Use template**.
1. Enter the project details.
diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md
index 3a72bd7b40c5768ec64598462529ec9579353609..2324f4d68326866418e1061047194776db56be8a 100644
--- a/doc/user/clusters/migrating_from_gma_to_project_template.md
+++ b/doc/user/clusters/migrating_from_gma_to_project_template.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrate from GitLab Managed Apps to Cluster Management Projects (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The GitLab Managed Apps were deprecated in GitLab 14.0
in favor of user-controlled Cluster Management projects.
@@ -107,9 +110,12 @@ See also [video walk-throughs](#video-walk-throughs) with examples.
`applications/cert-manager-legacy/helmfile.yaml`
in your project's main Helmfile ([`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file)).
- WARNING:
+ {{< alert type="warning" >}}
+
Cert-manager v0.10 breaks when Kubernetes is upgraded to version 1.20 or later.
+ {{< /alert >}}
+
1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/_index.md#run-a-pipeline-manually)
and watch the `apply` job logs to see if any of your applications were successfully detected, installed, and whether they got any
unexpected updates.
diff --git a/doc/user/compliance/_index.md b/doc/user/compliance/_index.md
index f6a0cc04b42963e00b17e3023dac6cabe13bb41e..11596f3a553956153951231842602b83b2134290 100644
--- a/doc/user/compliance/_index.md
+++ b/doc/user/compliance/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Compliance
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The compliance tools provided by GitLab help you keep an eye on various aspects of your project, including:
diff --git a/doc/user/compliance/audit_event_schema.md b/doc/user/compliance/audit_event_schema.md
index da64a27bd19b0c95261b31fdbf054c740cff966c..9a73981a8c42e69b1bb79f8d564433e53bc9b8a0 100644
--- a/doc/user/compliance/audit_event_schema.md
+++ b/doc/user/compliance/audit_event_schema.md
@@ -7,25 +7,29 @@ title: Audit event schema and examples
## Audit event schema
-> - Documentation for an audit event streaming schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358149) in GitLab 15.3.
+{{< history >}}
+
+- Documentation for an audit event streaming schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358149) in GitLab 15.3.
+
+{{< /history >}}
Audit events have a predictable schema in the body of the response.
| Field | Description | Notes | Streaming Only Field |
|------------------|------------------------------------------------------------|-----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
-| `author_id` | User ID of the user who triggered the event | | **{dotted-circle}** No |
-| `author_name` | Human-readable name of the author that triggered the event | Helpful when the author no longer exists | **{check-circle}** Yes |
-| `created_at` | Timestamp when event was triggered | | **{dotted-circle}** No |
-| `details` | JSON object containing additional metadata | Has no defined schema but often contains additional information about an event | **{dotted-circle}** No |
-| `entity_id` | ID of the audit event's entity | | **{dotted-circle}** No |
-| `entity_path` | Full path of the entity affected by the auditable event | | **{check-circle}** Yes |
-| `entity_type` | String representation of the type of entity | Acceptable values include `User`, `Group`, and `Key`. This list is not exhaustive | **{dotted-circle}** No |
-| `event_type` | String representation of the type of audit event | | **{check-circle}** Yes |
-| `id` | Unique identifier for the audit event | Can be used for deduplication if required | **{dotted-circle}** No |
-| `ip_address` | IP address of the host used to trigger the event | | **{check-circle}** Yes |
-| `target_details` | Additional details about the target | | **{check-circle}** Yes |
-| `target_id` | ID of the audit event's target | | **{check-circle}** Yes |
-| `target_type` | String representation of the target's type | | **{check-circle}** Yes |
+| `author_id` | User ID of the user who triggered the event | | {{< icon name="dotted-circle" >}} No |
+| `author_name` | Human-readable name of the author that triggered the event | Helpful when the author no longer exists | {{< icon name="check-circle" >}} Yes |
+| `created_at` | Timestamp when event was triggered | | {{< icon name="dotted-circle" >}} No |
+| `details` | JSON object containing additional metadata | Has no defined schema but often contains additional information about an event | {{< icon name="dotted-circle" >}} No |
+| `entity_id` | ID of the audit event's entity | | {{< icon name="dotted-circle" >}} No |
+| `entity_path` | Full path of the entity affected by the auditable event | | {{< icon name="check-circle" >}} Yes |
+| `entity_type` | String representation of the type of entity | Acceptable values include `User`, `Group`, and `Key`. This list is not exhaustive | {{< icon name="dotted-circle" >}} No |
+| `event_type` | String representation of the type of audit event | | {{< icon name="check-circle" >}} Yes |
+| `id` | Unique identifier for the audit event | Can be used for deduplication if required | {{< icon name="dotted-circle" >}} No |
+| `ip_address` | IP address of the host used to trigger the event | | {{< icon name="check-circle" >}} Yes |
+| `target_details` | Additional details about the target | | {{< icon name="check-circle" >}} Yes |
+| `target_id` | ID of the audit event's target | | {{< icon name="check-circle" >}} Yes |
+| `target_type` | String representation of the target's type | | {{< icon name="check-circle" >}} Yes |
### Audit event JSON schema
@@ -73,7 +77,11 @@ Audit events have a predictable schema in the body of the response.
### Headers
-> - `X-Gitlab-Audit-Event-Type` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86881) in GitLab 15.0.
+{{< history >}}
+
+- `X-Gitlab-Audit-Event-Type` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86881) in GitLab 15.0.
+
+{{< /history >}}
Headers are formatted as follows:
@@ -91,7 +99,7 @@ Streaming audit events can be sent when authenticated users push, pull, or clone
- [Using SSH](../ssh.md).
- Using HTTP or HTTPS.
-- Using **Download** (**{download}**) in GitLab UI.
+- Using **Download** ({{< icon name="download" >}}) in GitLab UI.
Audit events are not captured for users that are not signed in. For example, when downloading a public project.
diff --git a/doc/user/compliance/audit_event_streaming.md b/doc/user/compliance/audit_event_streaming.md
index 0b979cf6c01ed0c70e1d4ba31dbe113b7ffef045..205c17330a878ce46686d76d5d366b400be1d238 100644
--- a/doc/user/compliance/audit_event_streaming.md
+++ b/doc/user/compliance/audit_event_streaming.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Audit event streaming for top-level groups
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Subgroup events recording](https://gitlab.com/gitlab-org/gitlab/-/issues/366878) fixed in GitLab 15.2.
-> - Custom HTTP headers UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361630) in GitLab 15.2 [with a flag](../feature_flags.md) named `custom_headers_streaming_audit_events_ui`. Disabled by default.
-> - Custom HTTP headers UI [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) in GitLab 15.3. [Feature flag `custom_headers_streaming_audit_events_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) removed.
-> - [Improved user experience](https://gitlab.com/gitlab-org/gitlab/-/issues/367963) in GitLab 15.3.
-> - HTTP destination **Name** field [added](https://gitlab.com/gitlab-org/gitlab/-/issues/411357) in GitLab 16.3.
-> - Functionality for the **Active** checkbox [added](https://gitlab.com/gitlab-org/gitlab/-/issues/415268) in GitLab 16.5.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Subgroup events recording](https://gitlab.com/gitlab-org/gitlab/-/issues/366878) fixed in GitLab 15.2.
+- Custom HTTP headers UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361630) in GitLab 15.2 [with a flag](../feature_flags.md) named `custom_headers_streaming_audit_events_ui`. Disabled by default.
+- Custom HTTP headers UI [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) in GitLab 15.3. [Feature flag `custom_headers_streaming_audit_events_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/365259) removed.
+- [Improved user experience](https://gitlab.com/gitlab-org/gitlab/-/issues/367963) in GitLab 15.3.
+- HTTP destination **Name** field [added](https://gitlab.com/gitlab-org/gitlab/-/issues/411357) in GitLab 16.3.
+- Functionality for the **Active** checkbox [added](https://gitlab.com/gitlab-org/gitlab/-/issues/415268) in GitLab 16.5.
+
+{{< /history >}}
With audit event streaming for top-level groups, group owners can:
@@ -33,10 +40,13 @@ incoming data.
Audit events are sent using the POST request method protocol supported by HTTP.
-WARNING:
+{{< alert type="warning" >}}
+
Streaming destinations receive **all** audit event data, which could include sensitive information. Make sure you trust
the streaming destination.
+{{< /alert >}}
+
## HTTP destinations
Prerequisites:
@@ -133,12 +143,16 @@ To delete only the custom HTTP headers for a streaming destination:
1. Select the stream to expand.
1. Locate the **Custom HTTP headers** table.
1. Locate the header that you wish to remove.
-1. To the right of the header, select **Delete** (**{remove}**).
+1. To the right of the header, select **Delete** ({{< icon name="remove" >}}).
1. Select **Save** to update the streaming destination.
### Verify event authenticity
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360814) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360814) in GitLab 15.2.
+
+{{< /history >}}
Each streaming destination has a unique verification token (`verificationToken`) that can be used to verify the authenticity of the event. This
token is either specified by the Owner or generated automatically when the event destination is created and cannot be changed.
@@ -160,12 +174,16 @@ To list streaming destinations and see the verification tokens:
### Update event filters
-> - Event type filtering in the UI with a defined list of audit event types [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413581) in GitLab 16.1.
+{{< history >}}
+
+- Event type filtering in the UI with a defined list of audit event types [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413581) in GitLab 16.1.
+
+{{< /history >}}
When this feature is enabled for a group, you can permit users to filter streamed audit events per destination.
If the feature is enabled with no filters, the destination receives all audit events.
-A streaming destination that has an event type filter set has a **filtered** (**{filter}**) label.
+A streaming destination that has an event type filter set has a **filtered** ({{< icon name="filter" >}}) label.
To update a streaming destination's event filters:
@@ -179,12 +197,16 @@ To update a streaming destination's event filters:
### Update namespace filters
-> - Namespace filtering in the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390133) in GitLab 16.7.
+{{< history >}}
+
+- Namespace filtering in the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390133) in GitLab 16.7.
+
+{{< /history >}}
When this feature is enabled for a group, you can permit users to filter streamed audit events per destination.
If the feature is enabled with no filters, the destination receives all audit events.
-A streaming destination that has a namespace filter set has a **filtered** (**{filter}**) label.
+A streaming destination that has a namespace filter set has a **filtered** ({{< icon name="filter" >}}) label.
To update a streaming destination's namespace filters:
@@ -208,7 +230,11 @@ To override the `content-type` header default value for a top-level group stream
## Google Cloud Logging destinations
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124384) in GitLab 16.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124384) in GitLab 16.2.
+
+{{< /history >}}
Manage Google Cloud Logging destinations for top-level groups.
@@ -254,7 +280,11 @@ To list Google Cloud Logging streaming destinations for a top-level group:
### Update a Google Cloud Logging destination
-> - Button to add private key [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419675) in GitLab 16.3.
+{{< history >}}
+
+- Button to add private key [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419675) in GitLab 16.3.
+
+{{< /history >}}
Prerequisites:
@@ -289,8 +319,12 @@ To delete Google Cloud Logging streaming destinations to a top-level group:
## AWS S3 destinations
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132603) in GitLab 16.6 [with a flag](../feature_flags.md) named `allow_streaming_audit_events_to_amazon_s3`. Enabled by default.
-> - [Feature flag `allow_streaming_audit_events_to_amazon_s3`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137391) removed in GitLab 16.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132603) in GitLab 16.6 [with a flag](../feature_flags.md) named `allow_streaming_audit_events_to_amazon_s3`. Enabled by default.
+- [Feature flag `allow_streaming_audit_events_to_amazon_s3`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137391) removed in GitLab 16.7.
+
+{{< /history >}}
Manage AWS S3 destinations for top-level groups.
diff --git a/doc/user/compliance/audit_events.md b/doc/user/compliance/audit_events.md
index 6f3bf341de313c89be9f26c4b631201ed4ad2016..68af1f02cadd29130c1520d2863e528971fb9291 100644
--- a/doc/user/compliance/audit_events.md
+++ b/doc/user/compliance/audit_events.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Audit events
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A security audit is an in-depth analysis and review of your infrastructure, which is used to display
areas of concern and potentially hazardous practices. To assist with the audit process, GitLab provides
@@ -55,9 +58,12 @@ After upgrading to a paid tier, you can also see successful sign-in events on au
### Group audit events
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To view a group's audit events:
@@ -69,9 +75,12 @@ Group audit events can also be accessed using the [group audit events API](../..
### Project audit events
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Secure > Audit events**.
@@ -81,7 +90,11 @@ Project audit events can also be accessed using the [project audit events API](.
## Time zones
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/242014) in GitLab 15.7, GitLab UI shows dates and times in the user's local time zone instead of UTC.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/242014) in GitLab 15.7, GitLab UI shows dates and times in the user's local time zone instead of UTC.
+
+{{< /history >}}
The time zone used for audit events depends on where you view them:
diff --git a/doc/user/compliance/compliance_center/_index.md b/doc/user/compliance/compliance_center/_index.md
index 3c26e75de340e3b10e2ca8c0a65d4c2e952c07a9..79ccf0e8b4bc476867959048f6151d65036e01f6 100644
--- a/doc/user/compliance/compliance_center/_index.md
+++ b/doc/user/compliance/compliance_center/_index.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Compliance center
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122931) from Compliance report in GitLab 16.3.
-> - [Available at project level](https://gitlab.com/gitlab-org/gitlab/-/issues/441350) in GitLab 17.5.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122931) from Compliance report in GitLab 16.3.
+- [Available at project level](https://gitlab.com/gitlab-org/gitlab/-/issues/441350) in GitLab 17.5.
+
+{{< /history >}}
The compliance center is the central location for compliance teams to manage their compliance standards adherence reporting, violations reporting, and compliance frameworks for their group.
diff --git a/doc/user/compliance/compliance_center/compliance_chain_of_custody_report.md b/doc/user/compliance/compliance_center/compliance_chain_of_custody_report.md
index ea343a223882df261dee35b381dbfb71f76af407..92a957ec65d0b7e17d40169b090476b5474e733d 100644
--- a/doc/user/compliance/compliance_center/compliance_chain_of_custody_report.md
+++ b/doc/user/compliance/compliance_center/compliance_chain_of_custody_report.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Chain of Custody report
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3.
-> - Chain of Custody reports sent using email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342594) in GitLab 15.3 with a flag named `async_chain_of_custody_report`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370100) in GitLab 15.5. Feature flag `async_chain_of_custody_report` removed.
-> - Chain of Custody report includes all commits (instead of just merge commits) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267601) in GitLab 15.9 with a flag named `all_commits_compliance_report`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112092) in GitLab 15.9. Feature flag `all_commits_compliance_report` removed.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3.
+- Chain of Custody reports sent using email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342594) in GitLab 15.3 with a flag named `async_chain_of_custody_report`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370100) in GitLab 15.5. Feature flag `async_chain_of_custody_report` removed.
+- Chain of Custody report includes all commits (instead of just merge commits) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267601) in GitLab 15.9 with a flag named `all_commits_compliance_report`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112092) in GitLab 15.9. Feature flag `all_commits_compliance_report` removed.
+
+{{< /history >}}
The Chain of Custody report provides a 1 month trailing window of all commits to a project under the group.
@@ -56,8 +63,12 @@ Depending on your version of GitLab, the Chain of Custody report is either sent
## Generate commit-specific Chain of Custody report
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in GitLab 13.6.
-> - Support for including all commits instead of only merge commits [added](https://gitlab.com/gitlab-org/gitlab/-/issues/393446) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in GitLab 13.6.
+- Support for including all commits instead of only merge commits [added](https://gitlab.com/gitlab-org/gitlab/-/issues/393446) in GitLab 15.10.
+
+{{< /history >}}
You can generate a commit-specific Chain of Custody report for a given commit SHA. This report provides only the
details for the provided commit SHA.
diff --git a/doc/user/compliance/compliance_center/compliance_frameworks_report.md b/doc/user/compliance/compliance_center/compliance_frameworks_report.md
index a7ff6e275dc7141b80cd3b811bf254fd90484cea..00067bf1b02dfa4135bed4c383d6cdd29ce2a7f7 100644
--- a/doc/user/compliance/compliance_center/compliance_frameworks_report.md
+++ b/doc/user/compliance/compliance_center/compliance_frameworks_report.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Compliance frameworks report
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422973) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `compliance_framework_report_ui`. Disabled by default.
-> - In GitLab 16.4 and earlier, **Compliance frameworks report** referred to what is now called **Compliance projects report**. The formally-named **Compliance frameworks report** was [renamed to **Compliance projects report**](https://gitlab.com/gitlab-org/gitlab/-/issues/422963) in GitLab 16.5.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140825) in GitLab 16.8.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/425242) in GitLab 16.10.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422973) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `compliance_framework_report_ui`. Disabled by default.
+- In GitLab 16.4 and earlier, **Compliance frameworks report** referred to what is now called **Compliance projects report**. The formally-named **Compliance frameworks report** was [renamed to **Compliance projects report**](https://gitlab.com/gitlab-org/gitlab/-/issues/422963) in GitLab 16.5.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140825) in GitLab 16.8.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/425242) in GitLab 16.10.
+
+{{< /history >}}
With the compliance frameworks report, you can see all the compliance frameworks in a group. Each row of the report shows:
@@ -73,8 +80,12 @@ To delete a compliance framework from the compliance frameworks report:
## Export a report of compliance frameworks in a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413736) in GitLab 16.11 [with a flag](../../../administration/feature_flags.md) named `compliance_frameworks_report_csv_export`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152644) in GitLab 17.1. Feature flag `compliance_frameworks_report_csv_export` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413736) in GitLab 16.11 [with a flag](../../../administration/feature_flags.md) named `compliance_frameworks_report_csv_export`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152644) in GitLab 17.1. Feature flag `compliance_frameworks_report_csv_export` removed.
+
+{{< /history >}}
Exports the contents of a compliance frameworks report in a group. Reports are truncated at 15 MB to avoid a large email attachment.
diff --git a/doc/user/compliance/compliance_center/compliance_projects_report.md b/doc/user/compliance/compliance_center/compliance_projects_report.md
index f998976fd052f0c2a62518fc99f1421806075ce7..706ebe58e0378735a11df4a11948fce9d4ec6b65 100644
--- a/doc/user/compliance/compliance_center/compliance_projects_report.md
+++ b/doc/user/compliance/compliance_center/compliance_projects_report.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Compliance projects report
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387910) in GitLab 15.10.
-> - [Renamed from **compliance frameworks report**](https://gitlab.com/gitlab-org/gitlab/-/issues/422963) in GitLab 16.5.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387910) in GitLab 15.10.
+- [Renamed from **compliance frameworks report**](https://gitlab.com/gitlab-org/gitlab/-/issues/422963) in GitLab 16.5.
+
+{{< /history >}}
With the compliance projects report, you can see the compliance frameworks that are applied to projects in a group, subgroup, or project.
Each row of the report shows:
@@ -35,10 +42,14 @@ To view the compliance projects report:
## Apply a compliance framework to projects in a group
-> - Adding compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11.
-> - Adding compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0.
-> - Ability to add compliance frameworks to subgroups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/469004) in GitLab 17.2.
-> - Ability to add compliance frameworks to projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/507986) in GitLab 17.9.
+{{< history >}}
+
+- Adding compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11.
+- Adding compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0.
+- Ability to add compliance frameworks to subgroups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/469004) in GitLab 17.2.
+- Ability to add compliance frameworks to projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/507986) in GitLab 17.9.
+
+{{< /history >}}
You can apply one or more compliance frameworks to projects in a group, subgroup, or project.
@@ -51,7 +62,7 @@ To apply a compliance framework to one project in a group:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Secure > Compliance center**.
1. On the page, select the **Projects** tab.
-1. Next to the project you want to add the compliance framework to, select **{pencil}** action.
+1. Next to the project you want to add the compliance framework to, select {{< icon name="pencil" >}} action.
1. Select one or more existing compliance frameworks or create a new one.
To apply a compliance framework to multiple projects in a group:
@@ -66,10 +77,14 @@ To apply a compliance framework to multiple projects in a group:
## Remove a compliance framework from projects in a group
-> - Removing compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11.
-> - Removing compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0.
-> - Ability to remove compliance frameworks from subgroups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/469004) in GitLab 17.2.
-> - Ability to remove compliance frameworks from projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/507986) in GitLab 17.9.
+{{< history >}}
+
+- Removing compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11.
+- Removing compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0.
+- Ability to remove compliance frameworks from subgroups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/469004) in GitLab 17.2.
+- Ability to remove compliance frameworks from projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/507986) in GitLab 17.9.
+
+{{< /history >}}
You can remove a compliance framework from projects in a group, subgroup, or project.
@@ -82,7 +97,7 @@ To remove a compliance framework from one project in a group:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Secure > Compliance center**.
1. On the page, select the **Projects** tab.
-1. Next to the compliance framework to remove from the project, select **{close}** on the framework label.
+1. Next to the compliance framework to remove from the project, select {{< icon name="close" >}} on the framework label.
To remove a compliance framework from multiple projects in a group:
@@ -95,7 +110,11 @@ To remove a compliance framework from multiple projects in a group:
## Export a report of compliance frameworks on projects in a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387912) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387912) in GitLab 16.0.
+
+{{< /history >}}
Export a report of compliance frameworks that are applied to projects in a group. Reports:
@@ -117,7 +136,11 @@ A report is compiled and delivered to your email inbox as an attachment.
## Filter the compliance projects report
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387911) in GitLab 15.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387911) in GitLab 15.11.
+
+{{< /history >}}
To filter the list of compliance frameworks:
diff --git a/doc/user/compliance/compliance_center/compliance_standards_adherence_dashboard.md b/doc/user/compliance/compliance_center/compliance_standards_adherence_dashboard.md
index 44f92022e44cbcfd4a88576e02912c67cb7c5d2f..48ccd233991ea4f623e5a85f09e9e7e391e7e23c 100644
--- a/doc/user/compliance/compliance_center/compliance_standards_adherence_dashboard.md
+++ b/doc/user/compliance/compliance_center/compliance_standards_adherence_dashboard.md
@@ -5,20 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Compliance standards adherence dashboard
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125875) GraphQL APIs in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `compliance_adherence_report`. Disabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125444) compliance standards adherence dashboard in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `adherence_report_ui`. Disabled by default.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/414495) in GitLab 16.5.
-> - [Feature flag `compliance_adherence_report` and `adherence_report_ui`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137398) removed in GitLab 16.7.
-> - Standards adherence filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413734) in GitLab 16.7.
-> - Standards adherence grouping [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413735) in GitLab 16.9.
-> - Standards adherence grouping by standards that a check belongs to and grouping by projects that a check belongs to [added](https://gitlab.com/gitlab-org/gitlab/-/issues/413735) in GitLab 16.10.
-> - **Last Scanned** column [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/439545) to **Date since last status change** in GitLab 16.10.
-> - DAST scanner check [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440721) to GitLab Standard in GitLab 17.6.
-> - SAST scanner check [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440722) to GitLab Standard in GitLab 17.6.
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125875) GraphQL APIs in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `compliance_adherence_report`. Disabled by default.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125444) compliance standards adherence dashboard in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `adherence_report_ui`. Disabled by default.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/414495) in GitLab 16.5.
+- [Feature flag `compliance_adherence_report` and `adherence_report_ui`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137398) removed in GitLab 16.7.
+- Standards adherence filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413734) in GitLab 16.7.
+- Standards adherence grouping [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413735) in GitLab 16.9.
+- Standards adherence grouping by standards that a check belongs to and grouping by projects that a check belongs to [added](https://gitlab.com/gitlab-org/gitlab/-/issues/413735) in GitLab 16.10.
+- **Last Scanned** column [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/439545) to **Date since last status change** in GitLab 16.10.
+- DAST scanner check [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440721) to GitLab Standard in GitLab 17.6.
+- SAST scanner check [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440722) to GitLab Standard in GitLab 17.6.
+
+{{< /history >}}
The compliance standards adherence dashboard lists the adherence status of projects complying to the _GitLab standard_.
@@ -93,7 +100,11 @@ information, see [DAST on-demand scan](../../application_security/dast/on-demand
## SOC 2 standard
-> - At least one non-author approval SOC 2 check [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433201) in GitLab 16.10.
+{{< history >}}
+
+- At least one non-author approval SOC 2 check [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433201) in GitLab 16.10.
+
+{{< /history >}}
The SOC 2 standard consists of one rule:
@@ -118,8 +129,12 @@ for these projects, you must update the group-level or project-level setting. Fo
## Export compliance standards adherence report for projects in a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413736) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `compliance_standards_adherence_csv_export`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142568) in GitLab 16.9. Feature flag `compliance_standards_adherence_csv_export` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413736) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `compliance_standards_adherence_csv_export`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142568) in GitLab 16.9. Feature flag `compliance_standards_adherence_csv_export` removed.
+
+{{< /history >}}
Exports the contents of a standards adherence report for projects in a group. Reports are truncated at 15 MB to avoid a large email attachment.
diff --git a/doc/user/compliance/compliance_center/compliance_violations_report.md b/doc/user/compliance/compliance_center/compliance_violations_report.md
index 099cfc2a8ae17f104a9df8c201bcdab661959c6b..246459050c4615e0b7f546dbcb14f9d90a7e6164 100644
--- a/doc/user/compliance/compliance_center/compliance_violations_report.md
+++ b/doc/user/compliance/compliance_center/compliance_violations_report.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Compliance violations report
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112111) to compliance violations report in GitLab 15.9.
-> - Ability to create and edit compliance frameworks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394950) in GitLab 16.0.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112111) to compliance violations report in GitLab 15.9.
+- Ability to create and edit compliance frameworks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394950) in GitLab 16.0.
+
+{{< /history >}}
With the compliance violations report, you can see a high-level view of merge request activity for all projects in the group.
@@ -27,7 +34,11 @@ When you select a row in the compliance violations report, a drawer appears that
## View the compliance violations report
-> - Target branch search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358414) in GitLab 16.0.
+{{< history >}}
+
+- Target branch search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358414) in GitLab 16.0.
+
+{{< /history >}}
Prerequisites:
@@ -60,11 +71,11 @@ Each compliance violation has one of the following severities.
| Icon | Severity level |
|:------------------------|:---------------|
-| **{severity-critical}** | Critical |
-| **{severity-high}** | High |
-| **{severity-medium}** | Medium |
-| **{severity-low}** | Low |
-| **{severity-info}** | Info |
+| {{< icon name="severity-critical" >}} | Critical |
+| {{< icon name="severity-high" >}} | High |
+| {{< icon name="severity-medium" >}} | Medium |
+| {{< icon name="severity-low" >}} | Low |
+| {{< icon name="severity-info" >}} | Info |
<!-- vale gitlab_base.SubstitutionWarning = YES -->
@@ -89,9 +100,13 @@ separation of duties is:
## Export a report of merge request compliance violations on projects in a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356791) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `compliance_violation_csv_export`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/424447) in GitLab 16.5.
-> - [Feature flag `compliance_violation_csv_export`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142568) removed in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356791) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `compliance_violation_csv_export`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/424447) in GitLab 16.5.
+- [Feature flag `compliance_violation_csv_export`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142568) removed in GitLab 16.9.
+
+{{< /history >}}
Export a report of merge request compliance violations on merge requests belonging to projects in a group. Reports:
diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md
index 145d782ca15252f63cc740935b4943bcc74ed38e..220cd76de7becb09966261eced2c6d23475101f7 100644
--- a/doc/user/compliance/license_approval_policies.md
+++ b/doc/user/compliance/license_approval_policies.md
@@ -5,18 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: License approval policies
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `license_scanning_policies`.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/397644) in GitLab 15.11. Feature flag `license_scanning_policies` removed.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `license_scanning_policies`.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/397644) in GitLab 15.11. Feature flag `license_scanning_policies` removed.
+
+{{< /history >}}
Use license approval policies to specify criteria that determines when approval is required before a merge request can be merged.
-NOTE:
+{{< alert type="note" >}}
+
License approval policies are applicable to [protected](../project/repository/branches/protected.md) target branches only.
+{{< /alert >}}
+
The following video provides an overview of these policies.
<div class="video-fallback">
diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/_index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/_index.md
index 7c1341b717f208e4a4653d5fa607e30c9cfd7db0..1c6869a35e13f16d5a831d01144e219cbd5606ec 100644
--- a/doc/user/compliance/license_scanning_of_cyclonedx_files/_index.md
+++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/_index.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: License scanning of CycloneDX files
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384932) in GitLab 15.9 for GitLab SaaS [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`. Both flags disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385176) in GitLab 16.4. Feature flags `license_scanning_sbom_scanner` and `package_metadata_synchronization` removed.
-> - The legacy License Compliance analyzer (`License-Scanning.gitlab-ci.yml`) was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/439162) in GitLab 17.0.
-> - In GitLab 17.5 we introduced the ability to use a CycloneDX report artifact as a source of data for license information behind the feature flag `license_scanning_with_sbom_licenses`, disabled by default.
-> - In GitLab 17.6 the ability to use a CycloneDX report artifact as a source of data for license information has been enabled by default. The feature flag `license_scanning_with_sbom_licenses` is still present to disable the feature if necessary.
-> - In GitLab 17.8 the feature flag `license_scanning_with_sbom_licenses` was removed.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384932) in GitLab 15.9 for GitLab SaaS [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`. Both flags disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385176) in GitLab 16.4. Feature flags `license_scanning_sbom_scanner` and `package_metadata_synchronization` removed.
+- The legacy License Compliance analyzer (`License-Scanning.gitlab-ci.yml`) was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/439162) in GitLab 17.0.
+- In GitLab 17.5 we introduced the ability to use a CycloneDX report artifact as a source of data for license information behind the feature flag `license_scanning_with_sbom_licenses`, disabled by default.
+- In GitLab 17.6 the ability to use a CycloneDX report artifact as a source of data for license information has been enabled by default. The feature flag `license_scanning_with_sbom_licenses` is still present to disable the feature if necessary.
+- In GitLab 17.8 the feature flag `license_scanning_with_sbom_licenses` was removed.
+
+{{< /history >}}
To detect the licenses in use, License Compliance relies on running the
[Dependency Scanning CI Jobs](../../application_security/dependency_scanning/_index.md),
@@ -23,12 +30,15 @@ This method of scanning is capable of parsing and identifying over 600 different
Third-party scanners may be used to generate the list of dependencies, as long as they produce a CycloneDX report artifact for [one of our supported languages](#supported-languages-and-package-managers) and follow the [GitLab CycloneDX property taxonomy](../../../development/sec/cyclonedx_property_taxonomy.md).
The ability to provide other licenses is tracked in [epic 10861](https://gitlab.com/groups/gitlab-org/-/epics/10861).
-NOTE:
+{{< alert type="note" >}}
+
The License Scanning feature relies on publicly available package metadata collected in an
external database and synced with the GitLab instance automatically. This database is a multi-region Google Cloud Storage bucket hosted in the United States.
The scan is executed exclusively within the GitLab instance.
No contextual information (for example, a list of project dependencies) is sent to the external service.
+{{< /alert >}}
+
## Configuration
To enable License scanning of CycloneDX files:
@@ -212,9 +222,12 @@ Users can require approval for merge requests based on the licenses that are det
## Running in an offline environment
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
For instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required to successfully scan
CycloneDX reports for licenses. For more information, see the offline [quick start guide](../../../topics/offline/quick_start_guide.md#enabling-the-package-metadata-database).
diff --git a/doc/user/crm/_index.md b/doc/user/crm/_index.md
index 64164ae4a4af5bd14c328e33b8db9e35dfd77a1c..d89b8a6cf8c7fac8e9eb30d41b37458726e7ad60 100644
--- a/doc/user/crm/_index.md
+++ b/doc/user/crm/_index.md
@@ -5,21 +5,31 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Customer relations management (CRM)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default.
-> - In GitLab 14.8 and later, you can [create contacts and organizations only in top-level groups](https://gitlab.com/gitlab-org/gitlab/-/issues/350634).
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/346082) in GitLab 15.0.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/346082) in GitLab 15.1.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default.
+- In GitLab 14.8 and later, you can [create contacts and organizations only in top-level groups](https://gitlab.com/gitlab-org/gitlab/-/issues/350634).
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/346082) in GitLab 15.0.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/346082) in GitLab 15.1.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is not under active development, but
[community contributions](https://about.gitlab.com/community/contribute/) are welcome.
To determine if the feature meets your needs, see the open issues in the [Managing and billing Clients Epic](https://gitlab.com/groups/gitlab-org/-/epics/5323).
+{{< /alert >}}
+
With customer relations management (CRM) you can create a record of contacts
(individuals) and organizations (companies) and relate them to issues.
@@ -40,7 +50,11 @@ For more information about what is planned for the future, see [issue 2256](http
## Enable customer relations management (CRM)
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108378) in GitLab 16.9.
+{{< history >}}
+
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108378) in GitLab 16.9.
+
+{{< /history >}}
Customer relations management features are enabled at the group level. If your
group also contains subgroups, and you want to use CRM features in the subgroup,
@@ -114,7 +128,7 @@ To edit an existing contact:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Customer relations**.
-1. Next to the contact you wish to edit, select **Edit** (**{pencil}**).
+1. Next to the contact you wish to edit, select **Edit** ({{< icon name="pencil" >}}).
1. Edit the required fields.
1. Select **Save changes**.
@@ -132,7 +146,7 @@ To change the state of a contact:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Customer relations**.
-1. Next to the contact you wish to edit, select **Edit** (**{pencil}**).
+1. Next to the contact you wish to edit, select **Edit** ({{< icon name="pencil" >}}).
1. Select or clear the **Active** checkbox.
1. Select **Save changes**.
@@ -181,7 +195,7 @@ To edit an existing organization:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Customer relations**.
1. In the upper right, select **Organizations**.
-1. Next to the organization you wish to edit, select **Edit** (**{pencil}**).
+1. Next to the organization you wish to edit, select **Edit** ({{< icon name="pencil" >}}).
1. Edit the required fields.
1. Select **Save changes**.
@@ -203,7 +217,7 @@ To view a contact's issues, select a contact from the issue sidebar, or:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Customer relations**.
-1. Next to the contact whose issues you wish to view, select **View issues** (**{issues}**).
+1. Next to the contact whose issues you wish to view, select **View issues** ({{< icon name="issues" >}}).
### View issues linked to an organization
@@ -216,7 +230,7 @@ To view an organization's issues:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Customer relations**.
1. In the upper right, select **Organizations**.
-1. Next to the organization whose issues you wish to view, select **View issues** (**{issues}**).
+1. Next to the organization whose issues you wish to view, select **View issues** ({{< icon name="issues" >}}).
### View contacts linked to an issue
@@ -262,9 +276,13 @@ API.
## Autocomplete contacts
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `contacts_autocomplete`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/352123) in GitLab 15.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352123) in GitLab 15.2. [Feature flag `contacts_autocomplete`](https://gitlab.com/gitlab-org/gitlab/-/issues/352123) removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `contacts_autocomplete`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/352123) in GitLab 15.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352123) in GitLab 15.2. [Feature flag `contacts_autocomplete`](https://gitlab.com/gitlab-org/gitlab/-/issues/352123) removed.
+
+{{< /history >}}
When you use the `/add_contacts` quick action, follow it with `[contact:` and an autocomplete list with the [active](#change-the-state-of-a-contact) contacts appears:
diff --git a/doc/user/custom_roles.md b/doc/user/custom_roles.md
index 3ee18d3a2a67a5701f9dc07a61ce9e1e3eac1c98..804bf424df813367f93600548fbd8057688ee48e 100644
--- a/doc/user/custom_roles.md
+++ b/doc/user/custom_roles.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Custom roles
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Custom roles feature introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106256) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `customizable_roles`.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114524) in GitLab 15.10.
-> - Ability to create and remove a custom role with the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393235) in GitLab 16.4.
-> - Ability to use the UI to add a user to your group with a custom role, change a user's custom role, or remove a custom role from a group member [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393239) in GitLab 16.7.
-> - Ability to create and remove an instance-wide custom role on GitLab Self-Managed [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141562) in GitLab 16.9.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Custom roles feature introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106256) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `customizable_roles`.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114524) in GitLab 15.10.
+- Ability to create and remove a custom role with the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393235) in GitLab 16.4.
+- Ability to use the UI to add a user to your group with a custom role, change a user's custom role, or remove a custom role from a group member [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393239) in GitLab 16.7.
+- Ability to create and remove an instance-wide custom role on GitLab Self-Managed [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141562) in GitLab 16.9.
+
+{{< /history >}}
Custom roles allow an organization to create user roles with the precise privileges and permissions required for that organization's needs.
@@ -23,16 +30,22 @@ For a demo of the custom roles feature, see [[Demo] Ultimate Guest can view code
You can discuss individual custom role and permission requests in [issue 391760](https://gitlab.com/gitlab-org/gitlab/-/issues/391760).
-NOTE:
+{{< alert type="note" >}}
+
Most custom roles are considered [billable users that use a seat](#billing-and-seat-usage). When you add a user to your group with a custom role and you are about to incur additional charges for having more seats than are included in your subscription, a warning is displayed.
+{{< /alert >}}
+
## Available permissions
For more information on available permissions, see [custom permissions](custom_roles/abilities.md).
-WARNING:
+{{< alert type="warning" >}}
+
Depending on the permissions added to a lower base role such as Guest, a user with a custom role might be able to perform actions that are usually restricted to the Maintainer role or higher. For example, if a custom role is Guest plus a permissions to manage CI/CD variables, a user with this role can manage CI/CD variables added by other Maintainers or Owners for that group or project.
+{{< /alert >}}
+
## Create a custom role
You create a custom role by adding [permissions](#available-permissions) to a base role.
@@ -93,7 +106,11 @@ To create a custom role, you can also [use the API](../api/graphql/reference/_in
## Edit a custom role
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/437590) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/437590) in GitLab 17.0.
+
+{{< /history >}}
After a custom role has been created, you can edit that custom role's name, description,
and permissions. You cannot change the base role. If you need to change the base role,
@@ -107,7 +124,7 @@ Prerequisites:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Settings > Roles and permissions**.
-1. Select the vertical ellipsis (**{ellipsis_v}**) for the custom role, then
+1. Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) for the custom role, then
select **Edit role**.
1. Modify the role as needed.
1. Select **Save role** to update the role.
@@ -120,7 +137,7 @@ Prerequisites:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Settings > Roles and permissions**.
-1. Select the vertical ellipsis (**{ellipsis_v}**) for the custom role, then
+1. Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) for the custom role, then
select **Edit role**.
1. Modify the role as needed.
1. Select **Save role** to update the role.
@@ -140,7 +157,7 @@ You can't remove a custom role from a group if there are members assigned that r
- For SaaS, select **Search or go to** and find your group.
1. Select **Settings > Roles and permissions**.
1. Select **Custom Roles**.
-1. In the **Actions** column, select **Delete role** (**{remove}**) and confirm.
+1. In the **Actions** column, select **Delete role** ({{< icon name="remove" >}}) and confirm.
You can also [use the API](../api/graphql/reference/_index.md#mutationmemberroledelete) to delete a custom role. To use the API, you must provide the `id` of the custom role. If you do not know this `id`, you can find it by making an [API request on the group](../api/graphql/reference/_index.md#groupmemberroles) or an [API request on the instance](../api/graphql/reference/_index.md#querymemberroles).
@@ -271,12 +288,19 @@ and do not use a seat.
## Assign a custom role to an invited group
-> - Support for custom roles for invited groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443369) in GitLab 17.4 behind a feature flag named `assign_custom_roles_to_group_links_sm`. Disabled by default.
-> - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/471999) in GitLab 17.4.
+{{< history >}}
+
+- Support for custom roles for invited groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443369) in GitLab 17.4 behind a feature flag named `assign_custom_roles_to_group_links_sm`. Disabled by default.
+- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/471999) in GitLab 17.4.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
When a group is invited to another group with a custom role, the following rules determine each user's custom permissions in the new group:
- When a user has a custom permission in one group with a base access level that is the same or higher than the default role in the other group, the user's maximum role is the default role. That is, the user is granted the lower of the two access levels.
@@ -322,7 +346,11 @@ You can sync users to custom roles with following authentication providers:
## Custom admin roles
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/15854) as an [experiment](../policy/development_stages_support.md) in GitLab 17.7 [with a flag](../administration/feature_flags.md) named `custom_ability_read_admin_dashboard`.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/15854) as an [experiment](../policy/development_stages_support.md) in GitLab 17.7 [with a flag](../administration/feature_flags.md) named `custom_ability_read_admin_dashboard`.
+
+{{< /history >}}
Prerequisites:
diff --git a/doc/user/discussions/_index.md b/doc/user/discussions/_index.md
index 69f250c665a61429e48118886c0619ff694076d9..85b0edc392e6bf47cc6ba3bed89983b6644377e9 100644
--- a/doc/user/discussions/_index.md
+++ b/doc/user/discussions/_index.md
@@ -1,20 +1,27 @@
---
stage: Create
group: Code Review
-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"
-description: "Use comments to discuss work, mention users, and suggest changes."
+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
+description: Use comments to discuss work, mention users, and suggest changes.
title: Comments and threads
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Paginated merge request discussions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340172) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. Disabled by default.
-> - Paginated merge request discussions [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.2.
-> - Paginated merge request discussions [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.3.
-> - Paginated merge request discussions [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370075) in GitLab 15.8. Feature flag `paginated_mr_discussions` removed.
-> - Comments and threads on Wiki pages [introduced](https://gitlab.com/groups/gitlab-org/-/epics/14461) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `wiki_comments`. Disabled by default.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Paginated merge request discussions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340172) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. Disabled by default.
+- Paginated merge request discussions [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.2.
+- Paginated merge request discussions [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.3.
+- Paginated merge request discussions [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370075) in GitLab 15.8. Feature flag `paginated_mr_discussions` removed.
+- Comments and threads on Wiki pages [introduced](https://gitlab.com/groups/gitlab-org/-/epics/14461) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `wiki_comments`. Disabled by default.
+
+{{< /history >}}
GitLab encourages communication through comments, threads, and
[suggesting changes for code](../project/merge_requests/reviews/suggestions.md).
@@ -56,12 +63,19 @@ mentions for yourself (the current, authenticated user) in a different color.
### Mentioning all members
-> - [Flag](../../administration/feature_flags.md) named `disable_all_mention` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110586) in GitLab 16.1. Disabled by default. [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/18442).
+{{< history >}}
+
+- [Flag](../../administration/feature_flags.md) named `disable_all_mention` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110586) in GitLab 16.1. Disabled by default. [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/18442).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Avoid mentioning `@all` in comments and descriptions. `@all` mentions more than
just the participants of the project, issue, or merge request, but all members
of that project's parent group. All these users receive an email notification
@@ -103,8 +117,8 @@ To add a commit diff comment:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests**, and find your merge request.
1. Select the **Commits** tab, then select the commit message.
-1. By the line you want to comment on, hover over the line number and select **Comment** (**{comment}**).
- You can select multiple lines by dragging the **Comment** (**{comment}**) icon.
+1. By the line you want to comment on, hover over the line number and select **Comment** ({{< icon name="comment" >}}).
+ You can select multiple lines by dragging the **Comment** ({{< icon name="comment" >}}) icon.
1. Enter your comment.
1. To add your comment immediately, select **Add comment now**, or use the keyboard shortcut:
- macOS: <kbd>Shift</kbd> + <kbd>Command</kbd> + <kbd>Enter</kbd>
@@ -117,12 +131,15 @@ The comment displays on the merge request's **Overview** tab.
The comment is not displayed on your project's **Code > Commits** page.
-NOTE:
+{{< alert type="note" >}}
+
When your comment contains a reference to a commit included in the merge request,
it's converted to a link in the context of the merge request.
For example, `28719b171a056960dfdc0012b625d0b47b123196` becomes `28719b17` that links to
`https://gitlab.example.com/example-group/example-project/-/merge_requests/12345/diffs?commit_id=28719b171a056960dfdc0012b625d0b47b123196`.
+{{< /alert >}}
+
## Reply to a comment by sending email
If you have ["reply by email"](../../administration/reply_by_email.md) configured,
@@ -142,7 +159,7 @@ Anyone with at least the Maintainer role can also edit a comment made by someone
To edit a comment:
-1. On the comment, select **Edit comment** (**{pencil}**).
+1. On the comment, select **Edit comment** ({{< icon name="pencil" >}}).
1. Make your edits.
1. Select **Save changes**.
@@ -172,7 +189,7 @@ To lock an issue or merge request:
1. For merge requests, select **Code > Merge requests**, and find your merge request.
1. For issues, select **Plan > Issues**, and find your issue.
1. In the upper-right corner, select **Merge request actions** or **Issue actions**
- (**{ellipsis_v}**), then select **Lock discussion**.
+ ({{< icon name="ellipsis_v" >}}), then select **Lock discussion**.
GitLab adds a system note to the page details.
@@ -181,11 +198,15 @@ reopen the issue or merge request.
## Add an internal note
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87403) from "confidential comments" to "internal notes" in GitLab 15.0.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87383) in GitLab 15.0.
-> - [Feature flag `confidential_notes`](https://gitlab.com/gitlab-org/gitlab/-/issues/362712) removed in GitLab 15.2.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/363045) permissions in GitLab 15.6 to at least the Reporter role. In GitLab 15.5 and earlier, issue or epic authors and assignees could also read and create internal notes.
-> - Internal comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142003) for merge requests in GitLab 16.9.
+{{< history >}}
+
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87403) from "confidential comments" to "internal notes" in GitLab 15.0.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87383) in GitLab 15.0.
+- [Feature flag `confidential_notes`](https://gitlab.com/gitlab-org/gitlab/-/issues/362712) removed in GitLab 15.2.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/363045) permissions in GitLab 15.6 to at least the Reporter role. In GitLab 15.5 and earlier, issue or epic authors and assignees could also read and create internal notes.
+- Internal comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142003) for merge requests in GitLab 16.9.
+
+{{< /history >}}
Use internal notes to protect information added to a _public_ issue, epic, or merge request.
Internal notes differ from public comments:
@@ -238,9 +259,12 @@ To change the activity sort order:
## View description change history
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can see changes to the description listed in the history.
@@ -250,7 +274,7 @@ To compare the changes, select **Compare with previous version**.
You can assign an issue to a user who made a comment.
-1. In the comment, select the **More Actions** (**{ellipsis_v}**) menu.
+1. In the comment, select the **More Actions** ({{< icon name="ellipsis_v" >}}) menu.
1. Select **Assign to commenting user**:
1. To unassign the commenter, select the button again.
@@ -266,7 +290,7 @@ Prerequisites:
To create a thread by replying to a comment:
-1. In the upper-right corner of the comment, select **Reply to comment** (**{reply}**)
+1. In the upper-right corner of the comment, select **Reply to comment** ({{< icon name="reply" >}})
to display the reply section.
1. Enter your reply.
1. Select **Reply** or **Add comment now** (depending on where in the UI you are replying).
@@ -285,7 +309,7 @@ Prerequisites:
To create a thread:
1. Enter a comment.
-1. Below the comment, to the right of **Comment**, select the down arrow (**{chevron-down}**).
+1. Below the comment, to the right of **Comment**, select the down arrow ({{< icon name="chevron-down" >}}).
1. From the list, select **Start thread**.
1. Select **Start thread** again.
@@ -293,11 +317,15 @@ To create a thread:
## Resolve a thread
-> - Resolvable threads for issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `resolvable_issue_threads`. Disabled by default.
-> - Resolvable threads for issues [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.4.
-> - Resolvable threads for issues [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.7. Feature flag `resolvable_issue_threads` removed.
-> - Resolvable threads for tasks, objectives, and key results [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/458818) in GitLab 17.3.
-> - Resolvable threads for epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/458818) in GitLab 17.5. Your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md).
+{{< history >}}
+
+- Resolvable threads for issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `resolvable_issue_threads`. Disabled by default.
+- Resolvable threads for issues [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.4.
+- Resolvable threads for issues [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.7. Feature flag `resolvable_issue_threads` removed.
+- Resolvable threads for tasks, objectives, and key results [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/458818) in GitLab 17.3.
+- Resolvable threads for epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/458818) in GitLab 17.5. Your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md).
+
+{{< /history >}}
You can resolve a thread when you want to finish a conversation.
@@ -310,7 +338,7 @@ To resolve a thread:
1. Go to the thread.
1. Do one of the following:
- - In the upper-right corner of the original comment, select **Resolve thread** (**{check-circle}**).
+ - In the upper-right corner of the original comment, select **Resolve thread** ({{< icon name="check-circle" >}}).
- Below the last reply, in the **Reply** field, select **Resolve thread**.
- Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**.
@@ -322,15 +350,22 @@ such as:
## Summarize issue discussions with Duo Chat
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10344) in GitLab 16.0 as an [experiment](../../policy/development_stages_support.md#experiment).
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/454550) to GitLab Duo and promoted to [beta](../../policy/development_stages_support.md#beta) in GitLab 17.3 [with a flag](../../administration/feature_flags.md) named `summarize_notes_with_duo`. Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162122) in GitLab 17.4.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10344) in GitLab 16.0 as an [experiment](../../policy/development_stages_support.md#experiment).
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/454550) to GitLab Duo and promoted to [beta](../../policy/development_stages_support.md#beta) in GitLab 17.3 [with a flag](../../administration/feature_flags.md) named `summarize_notes_with_duo`. Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162122) in GitLab 17.4.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+{{< /history >}}
Generate a summary of discussions on an issue.
diff --git a/doc/user/duo_amazon_q/_index.md b/doc/user/duo_amazon_q/_index.md
index f936dd308d7d666f3ef8d1231dbe036de8742a2a..e520e5110696276bf3c6c5be61d5e39d66942a15 100644
--- a/doc/user/duo_amazon_q/_index.md
+++ b/doc/user/duo_amazon_q/_index.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Duo with Amazon Q
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Preview/Beta
+{{< details >}}
-> - Introduced as [beta](../../policy/development_stages_support.md#beta) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `amazon_q_integration`. Disabled by default.
-> - Feature flag `amazon_q_integration` removed in GitLab 17.8.
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+- Status: Preview/Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced as [beta](../../policy/development_stages_support.md#beta) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `amazon_q_integration`. Disabled by default.
+- Feature flag `amazon_q_integration` removed in GitLab 17.8.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
If you have a Duo Pro or Duo Enterprise add-on, this feature is not available.
+{{< /alert >}}
+
At Re:Invent 2024, Amazon announced the GitLab Duo with Amazon Q integration.
With this integration, you can automate tasks and increase productivity.
diff --git a/doc/user/duo_amazon_q/setup.md b/doc/user/duo_amazon_q/setup.md
index 19594e24913a8e7e17affa68cd63aef592cac262..5bbd4fd8326280c23125b3f2c33ec98e4ca18539 100644
--- a/doc/user/duo_amazon_q/setup.md
+++ b/doc/user/duo_amazon_q/setup.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Set up GitLab Duo with Amazon Q
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Preview/Beta
+{{< details >}}
-> - Introduced as an [experiment](../../policy/development_stages_support.md#experiment) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `amazon_q_integration`. Disabled by default.
-> - Feature flag `amazon_q_integration` removed in GitLab 17.8.
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+- Status: Preview/Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced as an [experiment](../../policy/development_stages_support.md#experiment) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `amazon_q_integration`. Disabled by default.
+- Feature flag `amazon_q_integration` removed in GitLab 17.8.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
If you have a Duo Pro or Duo Enterprise add-on, this feature is not available.
+{{< /alert >}}
+
To use GitLab Duo with Amazon Q, you can [request access to a lab environment](https://about.gitlab.com/partners/technology-partners/aws/#interest).
If you'd prefer to set up GitLab Duo with Amazon Q on GitLab Self-Managed,
@@ -69,9 +79,12 @@ Now, create an AWS identity provider:
Next, you must create an IAM role that trusts the IAM identity provider and can
access Amazon Q.
-NOTE:
+{{< alert type="note" >}}
+
After you set up the IAM role, you cannot change the AWS account that's associated with the role.
+{{< /alert >}}
+
1. In the AWS IAM console, select **Access Management > Roles > Create role**.
1. Select **Web identity**.
1. For **Web identity**, select the provider URL you entered earlier.
diff --git a/doc/user/duo_workflow/_index.md b/doc/user/duo_workflow/_index.md
index 7606fa9077dc1c9687d9eb91fa6db4c27b2c9a8a..0cc4b10e246cbf0c543918d8c06f73864cd9f3c5 100644
--- a/doc/user/duo_workflow/_index.md
+++ b/doc/user/duo_workflow/_index.md
@@ -5,28 +5,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Duo Workflow
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com
-**Status:** Experiment
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14153) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `duo_workflow`. Enabled for GitLab team members only. This feature is an [experiment](../../policy/development_stages_support.md).
+- Tier: Ultimate
+- Offering: GitLab.com
+- Status: Experiment
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14153) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `duo_workflow`. Enabled for GitLab team members only. This feature is an [experiment](../../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for internal GitLab team members for testing, but not ready for production use.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
This feature is considered [experimental](../../policy/development_stages_support.md) and is not intended for customer usage outside of initial design partners. We expect major changes to this feature.
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be
-subject to change or delay and remain at the sole discretion of GitLab Inc.
+{{< /alert >}}
+
+{{< alert type="disclaimer" />}}
GitLab Duo Workflow is an AI-powered coding agent in the Visual Studio Code (VS Code) IDE.
diff --git a/doc/user/emoji_reactions.md b/doc/user/emoji_reactions.md
index 28d42d0390ccfbfa27f67a444b7f66e65cb77599..d09b34ff95b67fac666addbb3adf2f7973e13f45 100644
--- a/doc/user/emoji_reactions.md
+++ b/doc/user/emoji_reactions.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Emoji reactions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from "award emoji" to "emoji reactions" in GitLab 16.0.
-> - Reacting with emoji on work items (such as tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393599) in GitLab 16.0.
-> - Reacting with emoji on design discussion comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29756) in GitLab 16.2.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from "award emoji" to "emoji reactions" in GitLab 16.0.
+- Reacting with emoji on work items (such as tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393599) in GitLab 16.0.
+- Reacting with emoji on design discussion comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29756) in GitLab 16.2.
+
+{{< /history >}}
When you're collaborating online, you get fewer opportunities for high-fives
and thumbs-ups. React with emoji on:
@@ -40,25 +47,29 @@ celebrate an accomplishment or agree with an opinion.
To add an emoji reaction:
-1. In the upper-right corner of the comment, select the smile (**{slight-smile}**).
+1. In the upper-right corner of the comment, select the smile ({{< icon name="slight-smile" >}}).
1. Select an emoji from the emoji picker.
To remove an emoji reaction, select the emoji again.
## Custom emoji
-> - [Introduced for GraphQL API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../administration/feature_flags.md) named `custom_emoji`. Disabled by default.
-> - Enabled on GitLab.com in GitLab 14.0.
-> - UI to add emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333095) in GitLab 16.2.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138969) in GitLab 16.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 16.9. Feature flag `custom_emoji` removed.
+{{< history >}}
+
+- [Introduced for GraphQL API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../administration/feature_flags.md) named `custom_emoji`. Disabled by default.
+- Enabled on GitLab.com in GitLab 14.0.
+- UI to add emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333095) in GitLab 16.2.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138969) in GitLab 16.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 16.9. Feature flag `custom_emoji` removed.
+
+{{< /history >}}
Custom emoji show in the emoji picker everywhere you can react with emoji.
To add an emoji reaction to a comment or description:
-1. Select **Add reaction** (**{slight-smile}**).
-1. Select the GitLab logo (**{tanuki}**) or scroll down to the **Custom** section.
+1. Select **Add reaction** ({{< icon name="slight-smile" >}}).
+1. Select the GitLab logo ({{< icon name="tanuki" >}}) or scroll down to the **Custom** section.
1. Select an emoji from the emoji picker.
@@ -74,7 +85,11 @@ For a list of custom emoji available for GitLab.com, see
### Upload custom emoji to a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128355) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128355) in GitLab 16.5.
+
+{{< /history >}}
Upload your custom emoji to a group to use them in all its subgroups and projects.
@@ -84,7 +99,7 @@ Prerequisites:
To upload custom emoji:
-1. On a description or a comment, select **Add reaction** (**{slight-smile}**).
+1. On a description or a comment, select **Add reaction** ({{< icon name="slight-smile" >}}).
1. At the bottom of the emoji picker, select **Create new emoji**.
1. Enter a name and URL for the custom emoji.
1. Select **Save**.
diff --git a/doc/user/enterprise_user/_index.md b/doc/user/enterprise_user/_index.md
index 8b153f6f0676a38318cf2b11c73343ee291de2f8..83c1329adad58b83d78a0a3470a8a8f9a4006466 100644
--- a/doc/user/enterprise_user/_index.md
+++ b/doc/user/enterprise_user/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Enterprise users
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Enterprise users have user accounts that are administered by an organization that
has [verified their email domain](#verified-domains-for-groups) and purchased a [GitLab subscription](../../subscriptions/_index.md).
@@ -119,9 +122,12 @@ The custom domain must match the email domain exactly. For example, if your emai
add the certificate and key later.
1. Select **Add Domain**.
-NOTE:
+{{< alert type="note" >}}
+
A valid certificate is not required for domain verification. You can ignore error messages regarding the certificate if you are not using GitLab Pages.
+{{< /alert >}}
+
#### 2. Get a verification code
After you create a new domain, the verification code prompts you. Copy the values from GitLab
@@ -135,13 +141,16 @@ After you have added all the DNS records:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Settings > Domain Verification**.
-1. On the domain table row, Select **Retry verification** (**{retry}**).
+1. On the domain table row, Select **Retry verification** ({{< icon name="retry" >}}).
-WARNING:
+{{< alert type="warning" >}}
+
For GitLab instances with domain verification enabled, if the domain cannot be verified for 7 days, that domain is removed from the GitLab project.
+{{< /alert >}}
+
> **Notes:**
>
> - Domain verification is **required for GitLab.com users** to be marked as enterprise users.
@@ -183,7 +192,11 @@ These enterprise user-specific actions are in addition to the standard
### Disable two-factor authentication
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9484) in GitLab 15.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9484) in GitLab 15.8.
+
+{{< /history >}}
Top-level group Owners can disable two-factor authentication (2FA) for enterprise users.
@@ -192,22 +205,32 @@ To disable 2FA:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Manage > Members**.
1. Find a user with the **Enterprise** and **2FA** badges.
-1. Select **More actions** (**{ellipsis_v}**) and select **Disable two-factor authentication**.
+1. Select **More actions** ({{< icon name="ellipsis_v" >}}) and select **Disable two-factor authentication**.
### Enable the extension marketplace for the Web IDE and workspaces
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161819) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 17.0 [with flags](../../administration/feature_flags.md) named `web_ide_oauth` and `web_ide_extensions_marketplace`. Disabled by default.
-> - Feature flag `web_ide_oauth` [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163181) in GitLab 17.4.
-> - Feature flag `web_ide_extensions_marketplace` [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/459028) in GitLab 17.4.
-> - Feature flag `web_ide_oauth` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167464) in GitLab 17.5.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161819) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 17.0 [with flags](../../administration/feature_flags.md) named `web_ide_oauth` and `web_ide_extensions_marketplace`. Disabled by default.
+- Feature flag `web_ide_oauth` [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163181) in GitLab 17.4.
+- Feature flag `web_ide_extensions_marketplace` [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/459028) in GitLab 17.4.
+- Feature flag `web_ide_oauth` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167464) in GitLab 17.5.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
If you have the Owner role for a top-level group, you can enable the
[extension marketplace](../project/web_ide/_index.md#extension-marketplace) for enterprise users.
diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md
index 28526f6002b4761bd98435ebe70984fbd2015218..fef4aa363c7f43e33f64dcf6d6147e00db5a0615 100644
--- a/doc/user/feature_flags.md
+++ b/doc/user/feature_flags.md
@@ -1,10 +1,10 @@
---
stage: none
group: unassigned
-description: Complete list of flags.
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
-layout: 'feature_flags'
+description: Complete list of flags.
title: All feature flags in GitLab
+layout: feature_flags
---
The following feature flags exist in GitLab. These flags determine the availability of each feature.
diff --git a/doc/user/free_push_limit.md b/doc/user/free_push_limit.md
index 16176e4698d05af894ae10b84f6b3d01e158b5fd..d19f01f35b3be07a191a975a31e6ac3541f5dad2 100644
--- a/doc/user/free_push_limit.md
+++ b/doc/user/free_push_limit.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Free push limit
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
A 100 MiB per-file limit applies when pushing new files to any project in the Free tier.
diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md
index 7a2dc61f5976beee32756e1397fe5655cd95b660..12d5e586faaddc1e67e6c9889928f509ad9cb1a5 100644
--- a/doc/user/free_user_limit.md
+++ b/doc/user/free_user_limit.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Free user limit
---
-DETAILS:
-**Tier:** Free
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free
+- Offering: GitLab.com
+
+{{< /details >}}
You can add up to five users to newly created top-level namespaces with
private visibility on GitLab.com.
diff --git a/doc/user/get_started/get_started_managing_code.md b/doc/user/get_started/get_started_managing_code.md
index 1d2a3041ace5913fd9faaedb1fe4a97303f4e4d6..e14f2fd5c4b875e25280cdc9e616e56f287e19c2 100644
--- a/doc/user/get_started/get_started_managing_code.md
+++ b/doc/user/get_started/get_started_managing_code.md
@@ -1,8 +1,8 @@
---
stage: Create
group: Source Code
-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"
-description: "Learn about the GitLab tools for building, tracking, and delivering the code for your project."
+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
+description: Learn about the GitLab tools for building, tracking, and delivering the code for your project.
title: Get started managing code
---
diff --git a/doc/user/get_started/get_started_managing_infrastructure.md b/doc/user/get_started/get_started_managing_infrastructure.md
index 00c29b8dd119b64ce87be3238c9581a4bb7901a4..91e6ec4f0ca79d087b86ae8ef8fdaacce4584216 100644
--- a/doc/user/get_started/get_started_managing_infrastructure.md
+++ b/doc/user/get_started/get_started_managing_infrastructure.md
@@ -1,8 +1,8 @@
---
stage: Deploy
group: Environments
-description: Terraform and Kubernetes deployments.
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
+description: Terraform and Kubernetes deployments.
title: Get started managing your infrastructure
---
diff --git a/doc/user/get_started/get_started_monitoring.md b/doc/user/get_started/get_started_monitoring.md
index 345432cacb98d4a61901a7e1ca74ebb9be0e32bd..6b9b1215f6da8e06c66135dd685a9e44f8596bf3 100644
--- a/doc/user/get_started/get_started_monitoring.md
+++ b/doc/user/get_started/get_started_monitoring.md
@@ -2,7 +2,7 @@
stage: Monitor
group: Platform Insights
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
-description: "Get Started monitoring your application"
+description: Get Started monitoring your application
title: Get started with monitoring your application in GitLab
---
diff --git a/doc/user/get_started/get_started_planning_work.md b/doc/user/get_started/get_started_planning_work.md
index 7c9101bd38e1b9e2c93fc6417ad6c67826f4dd85..dadaa21e01f89dcf749e987cd26f584f1fad5172 100644
--- a/doc/user/get_started/get_started_planning_work.md
+++ b/doc/user/get_started/get_started_planning_work.md
@@ -1,7 +1,7 @@
---
stage: Plan
group: Project Management
-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"
+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
title: Get started planning work
---
diff --git a/doc/user/get_started/getting_started_gitlab_duo.md b/doc/user/get_started/getting_started_gitlab_duo.md
index f9f39dac190f4e7041de8c686e20ebeb6f1a2fdc..c614e7940e9656dcd0cbe1c304deaa20fcb8121b 100644
--- a/doc/user/get_started/getting_started_gitlab_duo.md
+++ b/doc/user/get_started/getting_started_gitlab_duo.md
@@ -1,8 +1,8 @@
---
stage: AI-powered
group: AI Framework
-description: AI-powered features and functionality.
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
+description: AI-powered features and functionality.
title: Get started with GitLab Duo
---
diff --git a/doc/user/gitlab_com/_index.md b/doc/user/gitlab_com/_index.md
index b15e2811c983f614312450cf576cd99072e9b591..f37d99343de526f969d6410c5c9d5867fe418bc2 100644
--- a/doc/user/gitlab_com/_index.md
+++ b/doc/user/gitlab_com/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab.com settings
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
This page contains information about the settings that are used on GitLab.com, available to
[GitLab SaaS](https://about.gitlab.com/pricing/) customers.
@@ -42,7 +45,7 @@ Go to the current instance configuration to see the SSH host key fingerprints on
GitLab.com.
1. Sign in to GitLab.
-1. On the left sidebar, select **Help** (**{question-o}**) > **Help**.
+1. On the left sidebar, select **Help** ({{< icon name="question-o" >}}) > **Help**.
1. On the Help page, select **Check the current instance configuration**.
In the instance configuration, you see the **SSH host key fingerprints**:
@@ -113,9 +116,12 @@ are included when cloning.
## Delayed group deletion
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
After May 08, 2023, all groups have delayed deletion enabled by default.
@@ -127,9 +133,12 @@ You can [view and restore groups marked for deletion](../group/_index.md#restore
## Delayed project deletion
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
After May 08, 2023, all groups have delayed project deletion enabled by default.
@@ -172,8 +181,8 @@ Some settings for [GitLab Pages](../project/pages/_index.md) differ from the
|:--------------------------------------------------|:-----------------------|
| Domain name | `gitlab.io` |
| IP address | `35.185.44.232` |
-| Support for custom domains | **{check-circle}** Yes |
-| Support for TLS certificates | **{check-circle}** Yes |
+| Support for custom domains | {{< icon name="check-circle" >}} Yes |
+| Support for TLS certificates | {{< icon name="check-circle" >}} Yes |
| Maximum site size | 1 GB |
| Number of custom domains per GitLab Pages website | 150 |
@@ -263,11 +272,14 @@ If you are near or over the repository size limit, you can either:
- [Reduce your repository size with Git](../project/repository/repository_size.md#methods-to-reduce-repository-size).
- [Purchase additional storage](https://about.gitlab.com/pricing/licensing-faq/#can-i-buy-more-storage).
-NOTE:
+{{< alert type="note" >}}
+
`git push` and GitLab project imports are limited to 5 GiB per request through
Cloudflare. Imports other than a file upload are not affected by
this limit. Repository limits apply to both public and private projects.
+{{< /alert >}}
+
## Default import sources
The [import sources](../project/import/_index.md#supported-import-sources) that are available to you by default depend on
@@ -355,8 +367,12 @@ GitLab.com uses the default of 60 seconds for [Puma request timeouts](../../admi
## Maximum number of reviewers and assignees
-> - Maximum assignees [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368936) in GitLab 15.6.
-> - Maximum reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366485) in GitLab 15.9.
+{{< history >}}
+
+- Maximum assignees [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368936) in GitLab 15.6.
+- Maximum reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366485) in GitLab 15.9.
+
+{{< /history >}}
Merge requests enforce these maximums:
@@ -365,10 +381,13 @@ Merge requests enforce these maximums:
## GitLab.com-specific rate limits
-NOTE:
+{{< alert type="note" >}}
+
See [Rate limits](../../security/rate_limits.md) for administrator
documentation.
+{{< /alert >}}
+
When a request is rate limited, GitLab responds with a `429` status
code. The client should wait before attempting the request again. There
are also informational headers with this response detailed in
diff --git a/doc/user/gitlab_duo/_index.md b/doc/user/gitlab_duo/_index.md
index b785a70355dc5825f4cabcf99327c70c7f988cc7..a01cd8752c6fa3e794ce33dd656d4779ef393176 100644
--- a/doc/user/gitlab_duo/_index.md
+++ b/doc/user/gitlab_duo/_index.md
@@ -1,14 +1,18 @@
---
stage: AI-powered
group: AI Framework
-description: AI-powered features and functionality.
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
+description: AI-powered features and functionality.
title: GitLab Duo
---
-> - [First GitLab Duo features introduced](https://about.gitlab.com/blog/2023/05/03/gitlab-ai-assisted-features/) in GitLab 16.0.
-> - [Removed third-party AI setting](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136144) in GitLab 16.6.
-> - [Removed support for OpenAI from all GitLab Duo features](https://gitlab.com/groups/gitlab-org/-/epics/10964) in GitLab 16.6.
+{{< history >}}
+
+- [First GitLab Duo features introduced](https://about.gitlab.com/blog/2023/05/03/gitlab-ai-assisted-features/) in GitLab 16.0.
+- [Removed third-party AI setting](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136144) in GitLab 16.6.
+- [Removed support for OpenAI from all GitLab Duo features](https://gitlab.com/groups/gitlab-org/-/epics/10964) in GitLab 16.6.
+
+{{< /history >}}
GitLab Duo is a suite of AI-powered features that assist you while you work in GitLab.
These features aim to help increase velocity and solve key pain points across the software development lifecycle.
diff --git a/doc/user/gitlab_duo/data_usage.md b/doc/user/gitlab_duo/data_usage.md
index 069bb9197a60bd24ff4b185f206c347846593f7b..05d163b671831c585ef4f3c063f8fa5a0a98180a 100644
--- a/doc/user/gitlab_duo/data_usage.md
+++ b/doc/user/gitlab_duo/data_usage.md
@@ -1,8 +1,8 @@
---
stage: AI-powered
group: AI Model Validation
-description: AI-powered features and functionality.
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
+description: AI-powered features and functionality.
title: GitLab Duo data usage
---
@@ -73,7 +73,11 @@ GitLab is actively iterating on all our AI-assisted capabilities to improve the
## Secret detection and redaction
-> - [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/issues/632) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/issues/632) in GitLab 17.9.
+
+{{< /history >}}
GitLab Duo includes secret detection and redaction, powered by Gitleaks. It automatically
detects and removes sensitive information like API keys, credentials, and tokens from your
diff --git a/doc/user/gitlab_duo/experiments.md b/doc/user/gitlab_duo/experiments.md
index 09f9e95d031884d5dbafd8c3631705db7ace36f2..190028df3799f7fc79ebf009831fc66d92e812ef 100644
--- a/doc/user/gitlab_duo/experiments.md
+++ b/doc/user/gitlab_duo/experiments.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../gitlab_duo/_index.md'
-remove_date: '2025-01-09'
+redirect_to: ../gitlab_duo/_index.md
+remove_date: "2025-01-09"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/gitlab_duo/prompt_guardrails.md b/doc/user/gitlab_duo/prompt_guardrails.md
index 27249d1153e82f87eadb5cc5748a636c76ce2c82..6b8705e995e99208197745773eb334dfcb349972 100644
--- a/doc/user/gitlab_duo/prompt_guardrails.md
+++ b/doc/user/gitlab_duo/prompt_guardrails.md
@@ -1,8 +1,8 @@
---
stage: AI-powered
group: AI Model Validation
-description: AI-powered features and functionality.
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
+description: AI-powered features and functionality.
title: GitLab Duo prompt guardrails
---
@@ -16,10 +16,13 @@ enforced context boundaries, and filtering tools, which help:
These safeguards support compliance with common regulatory standards,
like GDPR, by helping to minimize risks associated with AI-driven workflows.
-NOTE:
+{{< alert type="note" >}}
+
While these guardrails may reduce risks, they do not eliminate all vulnerabilities.
No system can guarantee complete protection against all misuse or sophisticated attacks.
+{{< /alert >}}
+
## General guardrails
The prompts used by GitLab Duo aim to:
diff --git a/doc/user/gitlab_duo/quick_start.md b/doc/user/gitlab_duo/quick_start.md
index 8927a5e1bb47d212dfe6f796de78fb7f972c7ae0..7ab9c40efaefac542ca6e8acd1ea1d3461238c02 100644
--- a/doc/user/gitlab_duo/quick_start.md
+++ b/doc/user/gitlab_duo/quick_start.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../get_started/getting_started_gitlab_duo.md'
-remove_date: '2025-02-21'
+redirect_to: ../get_started/getting_started_gitlab_duo.md
+remove_date: "2025-02-21"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/gitlab_duo/security.md b/doc/user/gitlab_duo/security.md
index a221278c5afba73344508452f0118c4bbaa83004..2ccb10ae5120c99fd275207a75cde3639545cde3 100644
--- a/doc/user/gitlab_duo/security.md
+++ b/doc/user/gitlab_duo/security.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Duo authentication and authorization
---
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/506641) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/506641) in GitLab 17.9.
+
+{{< /history >}}
GitLab Duo with Amazon Q uses a composite identity to authenticate requests.
-NOTE:
+{{< alert type="note" >}}
+
Support for a composite identity in other areas of the product
is proposed in [issue 511373](https://gitlab.com/gitlab-org/gitlab/-/issues/511373).
+{{< /alert >}}
+
The token that authenticates requests is a composite of two identities:
- The primary author, which is the Amazon Q [service account](../profile/service_accounts.md).
diff --git a/doc/user/gitlab_duo/setup.md b/doc/user/gitlab_duo/setup.md
index 3435ce192da42946f4f326e9ca57d9237ed961b2..29cd9b5372ebd61191398a4390b02afc7ad306b7 100644
--- a/doc/user/gitlab_duo/setup.md
+++ b/doc/user/gitlab_duo/setup.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure GitLab Duo on a self-managed instance
---
-DETAILS:
-**Offering:** GitLab Self-Managed, GitLab Dedicated
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Offering: GitLab Self-Managed, GitLab Dedicated
+- Tier: Premium, Ultimate
+
+{{< /details >}}
GitLab Duo is powered by large language models (LLMs), with data sent through an AI gateway.
To use GitLab Duo on a self-managed instance, you can do either of the following:
@@ -16,8 +19,11 @@ To use GitLab Duo on a self-managed instance, you can do either of the following
- [Use LLMs from the supported list and self-host the AI gateway and LLMs](../../administration/gitlab_duo_self_hosted/_index.md).
This option provides full control over your data and security.
- NOTE:
- You must have an Ultimate license with GitLab Duo Enterprise add-on to use GitLab Duo Self-Hosted.
+ {{< alert type="note" >}}
+
+You must have an Ultimate license with GitLab Duo Enterprise add-on to use GitLab Duo Self-Hosted.
+
+ {{< /alert >}}
This page focuses on how to configure a self-managed instance if you're using the default, GitLab-hosted option.
@@ -69,11 +75,18 @@ To resolve this problem, try editing your Apache proxy settings:
## Run a health check for GitLab Duo
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161997) in GitLab 17.3.
+- [Download health check report added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165032) in GitLab 17.5.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161997) in GitLab 17.3.
-> - [Download health check report added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165032) in GitLab 17.5.
+{{< /history >}}
You can determine if your instance meets the requirements to use GitLab Duo.
When the health check completes, it displays a pass or fail result and the types of issues.
diff --git a/doc/user/gitlab_duo/troubleshooting.md b/doc/user/gitlab_duo/troubleshooting.md
index 8753a72e3dd73983f813cf8d37576934882c6aff..bdc88ca32b810f294b5ab2892a8602969d086c41 100644
--- a/doc/user/gitlab_duo/troubleshooting.md
+++ b/doc/user/gitlab_duo/troubleshooting.md
@@ -19,13 +19,15 @@ you can also do the following:
1. As administrator, run a health check for GitLab Duo.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle In 17.5 and later
+ {{< tab title="In 17.5 and later" >}}
In GitLab 17.5 and later, you can use the UI to run health checks and download a detailed report that helps identify and troubleshoot issues.
- :::TabTitle In 17.4
+ {{< /tab >}}
+
+ {{< tab title="In 17.4" >}}
In GitLab 17.4, you can run the health check Rake task to generate a detailed report that helps identify and troubleshoot issues.
@@ -33,7 +35,9 @@ you can also do the following:
sudo gitlab-rails 'cloud_connector:health_check(root,report.json)'
```
- :::TabTitle In 17.3 and earlier
+ {{< /tab >}}
+
+ {{< tab title="In 17.3 and earlier" >}}
In GitLab 17.3 and earlier, you can download and run the `health_check` script to generate a detailed report that helps identify and troubleshoot issues.
@@ -57,7 +61,9 @@ you can also do the following:
--skip [CHECK] Skip specific check (options: access_data, token, license, host, features, end_to_end)
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Verify that the GitLab instance can reach the [required GitLab.com endpoints](setup.md).
You can use command-line tools such as `curl` to verify the connectivity.
diff --git a/doc/user/gitlab_duo/turn_on_off.md b/doc/user/gitlab_duo/turn_on_off.md
index 4302de384307754b87f94f6b91c854bfaa0888b3..23a87159afb4285c8047448bec3949e7f82d6a24 100644
--- a/doc/user/gitlab_duo/turn_on_off.md
+++ b/doc/user/gitlab_duo/turn_on_off.md
@@ -5,8 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Control GitLab Duo availability
---
-> - [Settings to turn off AI features introduced](https://gitlab.com/groups/gitlab-org/-/epics/12404) in GitLab 16.10.
-> - [Settings to turn off AI features added to the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/441489) in GitLab 16.11.
+{{< history >}}
+
+- [Settings to turn off AI features introduced](https://gitlab.com/groups/gitlab-org/-/epics/12404) in GitLab 16.10.
+- [Settings to turn off AI features added to the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/441489) in GitLab 16.11.
+
+{{< /history >}}
GitLab Duo features that are generally available are automatically turned on for all users that have access.
@@ -27,9 +31,9 @@ When GitLab Duo is turned off for a group, project, or instance:
### Turn off for a group
-::Tabs
+{{< tabs >}}
-:::TabTitle In 17.8 and later
+{{< tab title="In 17.8 and later" >}}
In GitLab 17.8 and later, follow these instructions to turn off GitLab Duo
for a group, including its subgroups and projects.
@@ -49,14 +53,19 @@ To turn off GitLab Duo for a group:
- To turn off GitLab Duo for the group, and to prevent other groups or projects from turning it on, select **Always off**.
1. Select **Save changes**.
-:::TabTitle In 17.7
+{{< /tab >}}
+
+{{< tab title="In 17.7" >}}
In GitLab 17.7, follow these instructions to turn off GitLab Duo
for a group, including its subgroups and projects.
-NOTE:
+{{< alert type="note" >}}
+
In GitLab 17.7, you cannot turn off GitLab Duo for groups or subgroups on GitLab Self-Managed, or for subgroups on GitLab.com.
+{{< /alert >}}
+
Prerequisites:
- You must have the Owner role for the group.
@@ -71,7 +80,9 @@ To turn off GitLab Duo for a group:
- To turn off GitLab Duo for the group, and to prevent projects from turning it on, select **Always off**.
1. Select **Save changes**.
-:::TabTitle In 17.4 to 17.6
+{{< /tab >}}
+
+{{< tab title="In 17.4 to 17.6" >}}
In GitLab 17.4 to 17.6, follow these instructions to turn off GitLab Duo
for a group and its subgroups and projects.
@@ -90,7 +101,9 @@ To turn off GitLab Duo for a group:
- To turn off GitLab Duo for the group, and to prevent other groups or projects from turning it on, select **Never on**.
1. Select **Save changes**.
-:::TabTitle In 17.3 and earlier
+{{< /tab >}}
+
+{{< tab title="In 17.3 and earlier" >}}
In GitLab 17.3 and earlier, follow these instructions to turn off GitLab Duo for a group
and its subgroups and projects.
@@ -108,13 +121,15 @@ Prerequisites:
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Turn off for a project
-::Tabs
+{{< tabs >}}
-:::TabTitle In 17.4 and later
+{{< tab title="In 17.4 and later" >}}
In GitLab 17.4 and later, follow these instructions to turn off GitLab Duo for a project.
@@ -130,7 +145,9 @@ To turn off GitLab Duo for a project:
1. Under **GitLab Duo**, turn the toggle off.
1. Select **Save changes**.
-:::TabTitle In 17.3 and earlier
+{{< /tab >}}
+
+{{< tab title="In 17.3 and earlier" >}}
In GitLab 17.3 and earlier, follow these instructions to turn off GitLab Duo for a project.
@@ -141,16 +158,21 @@ In GitLab 17.3 and earlier, follow these instructions to turn off GitLab Duo for
[`duo_features_enabled`](../../api/graphql/getting_started.md#update-project-settings)
setting to `false`. (The default is `true`.)
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Turn off for an instance
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-::Tabs
+{{< tabs >}}
-:::TabTitle In 17.7 and later
+{{< tab title="In 17.7 and later" >}}
In GitLab 17.7 and later, follow these instructions to turn off GitLab Duo for the instance.
@@ -168,7 +190,9 @@ To turn off GitLab Duo for an instance:
- To turn off GitLab Duo for the instance, and to prevent groups or projects from ever turning it on, select **Always off**.
1. Select **Save changes**.
-:::TabTitle In 17.4 to 17.6
+{{< /tab >}}
+
+{{< tab title="In 17.4 to 17.6" >}}
In GitLab 17.4 to 17.6, follow these instructions to turn off GitLab Duo for the instance.
@@ -186,7 +210,9 @@ To turn off GitLab Duo for an instance:
- To turn off GitLab Duo for the instance, and to prevent groups or projects from ever turning it on, select **Never on**.
1. Select **Save changes**.
-:::TabTitle In 17.3 and earlier
+{{< /tab >}}
+
+{{< tab title="In 17.3 and earlier" >}}
In GitLab 17.3 and earlier, follow these instructions to turn off GitLab Duo for an instance.
@@ -203,12 +229,17 @@ To turn off GitLab Duo for an instance:
1. Optional. Select the **Enforce for all subgroups** checkbox to cascade
the setting to all groups in the instance.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
+
+{{< alert type="note" >}}
-NOTE:
An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/441532) to allow administrators
to override the setting for specific groups or projects.
+{{< /alert >}}
+
## Turn on beta and experimental features
GitLab Duo features that are experimental and beta are turned off by default.
@@ -216,13 +247,16 @@ These features are subject to the [Testing Agreement](https://handbook.gitlab.co
### On GitLab.com
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
-::Tabs
+{{< /details >}}
-:::TabTitle In 17.4 and later
+{{< tabs >}}
+
+{{< tab title="In 17.4 and later" >}}
In GitLab 17.4 and later, follow these instructions to
turn on GitLab Duo experimental and beta features for your group on GitLab.com.
@@ -239,7 +273,9 @@ To turn on GitLab Duo experiment and beta features for a top-level group:
1. Under **GitLab Duo preview features**, select **Use experiment and beta GitLab Duo features**.
1. Select **Save changes**.
-:::TabTitle In 17.3 and earlier
+{{< /tab >}}
+
+{{< tab title="In 17.3 and earlier" >}}
In GitLab 17.3 and earlier, follow these instructions to
turn on GitLab Duo experimental and beta features for your group on GitLab.com.
@@ -250,16 +286,18 @@ turn on GitLab Duo experimental and beta features for your group on GitLab.com.
1. Under **GitLab Duo experiment and beta features**, select the **Use experiment and beta GitLab Duo features** checkbox.
1. Select **Save changes**.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
This setting [cascades to all projects](../project/merge_requests/approvals/settings.md#cascade-settings-from-the-instance-or-top-level-group)
that belong to the group.
### On self-managed
-::Tabs
+{{< tabs >}}
-:::TabTitle In 17.4 and later
+{{< tab title="In 17.4 and later" >}}
In GitLab 17.4 and later, follow these instructions to turn on GitLab Duo
experiment and beta features for your GitLab Self-Managed instance.
@@ -276,10 +314,14 @@ To turn on GitLab Duo experiment and beta features for an instance:
1. Under **GitLab Duo preview features**, select **Use experiment and beta GitLab Duo features**.
1. Select **Save changes**.
-:::TabTitle In 17.3 and earlier
+{{< /tab >}}
+
+{{< tab title="In 17.3 and earlier" >}}
To enable GitLab Duo beta and experimental features for GitLab versions
where GitLab Duo Chat is not yet generally available, see the
[GitLab Duo Chat documentation](../gitlab_duo_chat/turn_on_off.md#for-self-managed).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/user/gitlab_duo/use_cases.md b/doc/user/gitlab_duo/use_cases.md
index ce55f50b08937782e5bae9b3718c5e5662228e6e..fc2c7c6235c2b57da73cbc3e56c4dcc577ada824 100644
--- a/doc/user/gitlab_duo/use_cases.md
+++ b/doc/user/gitlab_duo/use_cases.md
@@ -1,8 +1,8 @@
---
stage: AI-powered
group: AI Model Validation
-description: AI-powered features and functionality.
info: This page is maintained by Developer Relations, author @dnsmichi, see https://handbook.gitlab.com/handbook/marketing/developer-relations/developer-advocacy/content/#maintained-documentation
+description: AI-powered features and functionality.
title: GitLab Duo use cases
---
@@ -13,9 +13,12 @@ Learn how to:
- Use GitLab Duo Root Cause Analysis to troubleshoot failed jobs.
- Solve security vulnerabilities.
-NOTE:
+{{< alert type="note" >}}
+
If you have GitLab Self-Managed: GitLab Duo requires GitLab 17.2 and later for the best user experience and results. Earlier versions may continue to work, however the experience may be degraded.
+{{< /alert >}}
+
## Use GitLab Duo to solve development challenges
### Start with a C# application
@@ -452,9 +455,12 @@ fun main() {
### Get Started with PowerShell
-NOTE:
+{{< alert type="note" >}}
+
PowerShell support is [experimental](../project/repository/code_suggestions/supported_extensions.md#add-support-for-more-languages).
+{{< /alert >}}
+
1. Use GitLab Duo Chat to ask how to get started with a PowerShell script that prints the file size of the current directory.
```markdown
diff --git a/doc/user/gitlab_duo_chat/_index.md b/doc/user/gitlab_duo_chat/_index.md
index 6930a398f085ea4899c0d938c9a8093edb02a062..8f95b294b4872333e8d9df7695feb1b3e737be0e 100644
--- a/doc/user/gitlab_duo_chat/_index.md
+++ b/doc/user/gitlab_duo_chat/_index.md
@@ -5,17 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Duo Chat
---
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**LLMs:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet), Anthropic [Claude 3 Haiku](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-haiku), and [Vertex AI Search](https://cloud.google.com/enterprise-search). The LLM depends on the question asked.
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117695) as an [experiment](../../policy/development_stages_support.md#experiment) for SaaS in GitLab 16.0.
-> - Changed to [beta](../../policy/development_stages_support.md#beta) for SaaS in GitLab 16.6.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11251) as a [beta](../../policy/development_stages_support.md#beta) for GitLab Self-Managed in GitLab 16.8.
-> - Changed from Ultimate to [Premium](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142808) tier in GitLab 16.9 while in [beta](../../policy/development_stages_support.md#beta).
-> - [Generally available](../../policy/development_stages_support.md#generally-available) in GitLab 16.11.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+{{< details >}}
+
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- LLMs: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet), Anthropic [Claude 3 Haiku](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-haiku), and [Vertex AI Search](https://cloud.google.com/enterprise-search). The LLM depends on the question asked.
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117695) as an [experiment](../../policy/development_stages_support.md#experiment) for SaaS in GitLab 16.0.
+- Changed to [beta](../../policy/development_stages_support.md#beta) for SaaS in GitLab 16.6.
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11251) as a [beta](../../policy/development_stages_support.md#beta) for GitLab Self-Managed in GitLab 16.8.
+- Changed from Ultimate to [Premium](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142808) tier in GitLab 16.9 while in [beta](../../policy/development_stages_support.md#beta).
+- [Generally available](../../policy/development_stages_support.md#generally-available) in GitLab 16.11.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+
+{{< /history >}}
GitLab Duo Chat is your personal AI-powered assistant for boosting productivity.
It can assist various tasks of your daily work with the AI-generated content.
@@ -30,9 +37,12 @@ You can use GitLab Duo Chat in:
- JetBrains IDEs, with the [GitLab Duo Plugin for JetBrains](https://plugins.jetbrains.com/plugin/22325-gitlab-duo)
- Visual Studio for Windows, with the [GitLab Extension for Visual Studio](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio)
-NOTE:
+{{< alert type="note" >}}
+
If you have GitLab Self-Managed: GitLab Duo requires GitLab 17.2 and later for the best user experience and results. Earlier versions may continue to work, however the experience may be degraded.
+{{< /alert >}}
+
## The context Chat is aware of
GitLab Duo Chat is sometimes aware of the context you're working in.
@@ -107,13 +117,20 @@ This applies to files added via `/include`, and all generation commands.
To ask a new question unrelated to the previous conversation, you might receive better answers
if you clear the context by typing `/reset` or `/clear` and selecting **Send**.
-NOTE:
+{{< alert type="note" >}}
+
Only the last 50 messages are retained in the chat history. The chat history expires 3 days after last use.
+{{< /alert >}}
+
## Use GitLab Duo Chat in the Web IDE
-> - Introduced in GitLab 16.6 as an [experiment](../../policy/development_stages_support.md#experiment).
-> - Changed to generally available in GitLab 16.11.
+{{< history >}}
+
+- Introduced in GitLab 16.6 as an [experiment](../../policy/development_stages_support.md#experiment).
+- Changed to generally available in GitLab 16.11.
+
+{{< /history >}}
To use GitLab Duo Chat in the Web IDE on GitLab:
@@ -132,9 +149,13 @@ If you have selected code in the editor, this selection is sent along with your
## Use GitLab Duo Chat in VS Code
-> - Introduced in GitLab 16.6 as an [experiment](../../policy/development_stages_support.md#experiment).
-> - Changed to generally available in GitLab 16.11.
-> - Status [added](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues/1712) in the GitLab Workflow extension for VS Code 5.29.0.
+{{< history >}}
+
+- Introduced in GitLab 16.6 as an [experiment](../../policy/development_stages_support.md#experiment).
+- Changed to generally available in GitLab 16.11.
+- Status [added](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues/1712) in the GitLab Workflow extension for VS Code 5.29.0.
+
+{{< /history >}}
Prerequisites:
@@ -143,7 +164,7 @@ Prerequisites:
To use GitLab Duo Chat in GitLab Workflow extension for VS Code:
1. In VS Code, open a file. The file does not need to be a file in a Git repository.
-1. On the left sidebar, select **GitLab Duo Chat** (**{duo-chat}**).
+1. On the left sidebar, select **GitLab Duo Chat** ({{< icon name="duo-chat" >}}).
1. In the message box, enter your question and press **Enter** or select **Send**.
1. In the chat pane, on the top right corner, select **Show Status** to show information
in the Command Palette.
@@ -161,14 +182,18 @@ You can interact with Duo Chat while you're working with a subset of code.
To close Duo Chat:
-- For Duo Chat on the left sidebar, select **GitLab Duo Chat** (**{duo-chat}**).
+- For Duo Chat on the left sidebar, select **GitLab Duo Chat** ({{< icon name="duo-chat" >}}).
- For the quick chat window that's embedded in your file, in the upper-right corner,
- select **Collapse** (**{chevron-lg-up}**).
+ select **Collapse** ({{< icon name="chevron-lg-up" >}}).
### In the editor window
-> - Introduced as [generally available](https://gitlab.com/groups/gitlab-org/-/epics/15218) in the GitLab Workflow extension for VS Code 5.15.0.
-> - Insert Snippet [added](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/merge_requests/2150) in the GitLab Workflow extension for VS Code 5.25.0.
+{{< history >}}
+
+- Introduced as [generally available](https://gitlab.com/groups/gitlab-org/-/epics/15218) in the GitLab Workflow extension for VS Code 5.15.0.
+- Insert Snippet [added](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/merge_requests/2150) in the GitLab Workflow extension for VS Code 5.25.0.
+
+{{< /history >}}
To open GitLab Duo Chat in the editor window, use any of these methods:
@@ -209,7 +234,11 @@ If you have selected code in the editor, this selection is sent along with your
## Use GitLab Duo Chat in JetBrains IDEs
-> - Introduced as generally available in GitLab 16.11.
+{{< history >}}
+
+- Introduced as generally available in GitLab 16.11.
+
+{{< /history >}}
Prerequisites:
@@ -245,7 +274,11 @@ After GitLab Duo Chat opens:
### In GitLab Duo Quick Chat in the editor view
-> - Introduced as generally available in the [GitLab Duo plugin for JetBrains 3.0.0](https://gitlab.com/groups/gitlab-org/editor-extensions/-/epics/80) and [GitLab Workflow extension for VS Code 5.14.0](https://gitlab.com/groups/gitlab-org/-/epics/15218).
+{{< history >}}
+
+- Introduced as generally available in the [GitLab Duo plugin for JetBrains 3.0.0](https://gitlab.com/groups/gitlab-org/editor-extensions/-/epics/80) and [GitLab Workflow extension for VS Code 5.14.0](https://gitlab.com/groups/gitlab-org/-/epics/15218).
+
+{{< /history >}}
To open GitLab Duo Chat Quick Chat in the editor window, use any of these methods:
@@ -253,7 +286,7 @@ To open GitLab Duo Chat Quick Chat in the editor window, use any of these method
- MacOS: <kbd>Option</kbd> + <kbd>c</kbd>
- Windows and Linux: <kbd>ALT</kbd> + <kbd>c</kbd>
- In the currently open file in your IDE, by selecting some code,
- then, in the floating toolbar, selecting **GitLab Duo Quick Chat** (**{tanuki-ai}**).
+ then, in the floating toolbar, selecting **GitLab Duo Quick Chat** ({{< icon name="tanuki-ai" >}}).
- Right-clicking, then selecting **GitLab Duo Chat > Open Quick Chat**.
After Quick Chat opens:
diff --git a/doc/user/gitlab_duo_chat/examples.md b/doc/user/gitlab_duo_chat/examples.md
index 5409f1ca7170c32d0f4d8257bebc0933fa676b13..e1577c95a9063c36f4be561df07e9b109074d7e8 100644
--- a/doc/user/gitlab_duo_chat/examples.md
+++ b/doc/user/gitlab_duo_chat/examples.md
@@ -10,22 +10,32 @@ represent some of the areas where GitLab Duo Chat can be the most helpful.
For additional practical examples, see the [GitLab Duo use cases](../gitlab_duo/use_cases.md).
-NOTE:
+{{< alert type="note" >}}
+
The example questions on this page, including the [slash commands](#gitlab-duo-chat-slash-commands), are deliberately generic. You might receive more useful responses from Chat by asking questions that are specific to your current goal. For example, "How does the `clean_missing_data` function in `data_cleaning.py` decide which rows to drop?".
+{{< /alert >}}
+
## Ask about GitLab
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI, Web IDE, VS Code, and JetBrains IDEs
-**LLMs:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet), [Vertex AI Search](https://cloud.google.com/enterprise-search)
+{{< details >}}
+
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI, Web IDE, VS Code, and JetBrains IDEs
+- LLMs: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet), [Vertex AI Search](https://cloud.google.com/enterprise-search)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117695) for GitLab.com in GitLab 16.0.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451215) ability to ask doc-related questions on GitLab Self-Managed in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `ai_gateway_docs_search`. Enabled by default.
+- [Generally available and feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/154876) in GitLab 17.1.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117695) for GitLab.com in GitLab 16.0.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/451215) ability to ask doc-related questions on GitLab Self-Managed in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `ai_gateway_docs_search`. Enabled by default.
-> - [Generally available and feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/154876) in GitLab 17.1.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+{{< /history >}}
You can ask questions about how GitLab works. Things like:
@@ -41,16 +51,23 @@ To keep Chat up to date with the documentation, its knowledge base is updated da
## Ask about a specific issue
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI, Web IDE, VS Code, JetBrains IDEs
-**LLM:** Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/models-overview#claude-3-a-new-generation-of-ai)
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for GitLab.com in GitLab 16.0.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI, Web IDE, VS Code, JetBrains IDEs
+- LLM: Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/models-overview#claude-3-a-new-generation-of-ai)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for GitLab.com in GitLab 16.0.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+
+{{< /history >}}
You can ask about a specific GitLab issue. For example:
@@ -58,25 +75,35 @@ You can ask about a specific GitLab issue. For example:
- When you are viewing an issue in GitLab, you can ask `Generate a concise summary of the current issue.`
- `How can I improve the description of <link to your issue> so that readers understand the value and problems to be solved?`
-NOTE:
+{{< alert type="note" >}}
+
If the issue contains a large amount of text (more than 40,000 words), GitLab Duo Chat might not be able to consider every word. The AI model has a limit to the amount of input it can process at one time.
+{{< /alert >}}
+
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For tips on how GitLab Duo Chat can improve your productivity with issues and epics, see [Boost your productivity with GitLab Duo Chat](https://youtu.be/RJezT5_V6dI).
<!-- Video published on 2024-04-17 -->
## Ask about a specific epic
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI, Web IDE, VS Code, JetBrains IDEs
-**LLM:** Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/models-overview#claude-3-a-new-generation-of-ai)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI, Web IDE, VS Code, JetBrains IDEs
+- LLM: Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/models-overview#claude-3-a-new-generation-of-ai)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128487) for GitLab.com in GitLab 16.3.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128487) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128487) for GitLab.com in GitLab 16.3.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128487) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+{{< /history >}}
You can ask about a specific GitLab epic. For example:
@@ -84,19 +111,29 @@ You can ask about a specific GitLab epic. For example:
- When you are viewing an epic in GitLab, you can ask `Generate a concise summary of the opened epic.`
- `What are the unique use cases raised by commenters in <link to your epic>?`
-NOTE:
+{{< alert type="note" >}}
+
If the epic contains a large amount of text (more than 40,000 words), GitLab Duo Chat might not be able to consider every word. The AI model has a limit to the amount of input it can process at one time.
+{{< /alert >}}
+
## Ask about a specific merge request
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464587) in GitLab 17.5.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464587) in GitLab 17.5.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+
+{{< /history >}}
You can ask GitLab about the merge request you're viewing. You can ask about:
@@ -114,13 +151,20 @@ While in the merge request, open Chat and type your question. For example:
## Ask about a specific commit
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468460) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468460) in GitLab 17.6.
+
+{{< /history >}}
You can ask about a specific GitLab commit. For example:
@@ -130,13 +174,20 @@ You can ask about a specific GitLab commit. For example:
## Ask about a specific pipeline job
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468461) in GitLab 17.6.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/468461) in GitLab 17.6.
+
+{{< /history >}}
You can ask about a specific GitLab pipeline job. For example:
@@ -147,16 +198,23 @@ You can ask about a specific GitLab pipeline job. For example:
## Explain selected code
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI, Web IDE, VS Code, JetBrains IDEs
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI, Web IDE, VS Code, JetBrains IDEs
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab.com in GitLab 16.7.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab.com in GitLab 16.7.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+
+{{< /history >}}
You can ask GitLab Duo Chat to explain selected code:
@@ -185,16 +243,23 @@ In the GitLab UI, you can also explain code in:
## Ask about or generate code
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI, Web IDE, VS Code, JetBrains IDEs
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI, Web IDE, VS Code, JetBrains IDEs
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for GitLab.com in GitLab 16.1.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for GitLab.com in GitLab 16.1.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122235) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+
+{{< /history >}}
You can ask GitLab Duo Chat questions about code by pasting that code into
the Chat window. For example:
@@ -215,7 +280,11 @@ You can also ask Chat to generate code. For example:
## Ask follow up questions
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+{{< history >}}
+
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+
+{{< /history >}}
You can ask follow-up questions to delve deeper into the topic or task at hand.
This helps you get more detailed and precise responses tailored to your specific needs,
@@ -231,7 +300,11 @@ A follow-up to the question `How to start a C# project?` could be:
## Ask about errors
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+{{< history >}}
+
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+
+{{< /history >}}
Programming languages that require compiling the source code may throw cryptic error messages. Similarly, a script or a web application could throw a stack trace. You can ask GitLab Duo Chat by prefixing the copied error message with, for example, `Please explain this error message:`. Add the specific context, like the programming language.
@@ -243,21 +316,31 @@ Programming languages that require compiling the source code may throw cryptic e
## Ask about specific files
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** VS Code, JetBrains IDEs
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/477258) in GitLab 17.7 [with flags](../../administration/feature_flags.md) named `duo_additional_context` and `duo_include_context_file`. Disabled by default.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
-> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/groups/gitlab-org/-/epics/15183) in GitLab 17.9.
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: VS Code, JetBrains IDEs
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/477258) in GitLab 17.7 [with flags](../../administration/feature_flags.md) named `duo_additional_context` and `duo_include_context_file`. Disabled by default.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/groups/gitlab-org/-/epics/15183) in GitLab 17.9.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
GitLab.com customers must contact their Customer Success Manager to enable this feature.
+{{< /alert >}}
+
Add repository files to your Duo Chat conversations in VS Code or JetBrains IDEs by
typing `/include` and choosing the files.
@@ -278,21 +361,31 @@ For example, if you are developing an e-commerce app, you can add the `cart_serv
- `How does checkout_flow.js interact with cart_service.py? Please generate a sequence diagram using Mermaid.`
- `Thanks, that helps. I want to extend the checkout process by showing products related to the ones in the user's cart. I want to move the checkout logic to the backend before proceeding. Generate the Python backend code and change the frontend code to work with the new backend.`
-NOTE:
+{{< alert type="note" >}}
+
You cannot use [Quick Chat](_index.md#in-gitlab-duo-quick-chat-in-the-editor-view) to add files or ask questions about files added for Chat's context.
+{{< /alert >}}
+
## Refactor code in the IDE
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** Web IDE, VS Code, JetBrains IDEs
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: Web IDE, VS Code, JetBrains IDEs
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab.com in GitLab 16.7.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab.com in GitLab 16.7.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+
+{{< /history >}}
You can ask GitLab Duo Chat to refactor selected code:
@@ -310,15 +403,22 @@ You can include additional instructions to be considered. For example:
## Fix code in the IDE
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** Web IDE, VS Code, JetBrains IDEs
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: Web IDE, VS Code, JetBrains IDEs
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab.com, GitLab Self-Managed and GitLab Dedicated in GitLab 17.3.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab.com, GitLab Self-Managed and GitLab Dedicated in GitLab 17.3.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+{{< /history >}}
You can ask GitLab Duo Chat to fix selected code:
@@ -335,16 +435,23 @@ You can include additional instructions to be considered. For example:
## Write tests in the IDE
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** Web IDE, VS Code, JetBrains IDEs
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab.com in GitLab 16.7.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: Web IDE, VS Code, JetBrains IDEs
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab.com in GitLab 16.7.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+
+{{< /history >}}
You can ask GitLab Duo Chat to create tests for the selected code:
@@ -362,18 +469,25 @@ For more information, see [Use GitLab Duo Chat in VS Code](_index.md#use-gitlab-
## Ask about CI/CD
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI, Web IDE, VS Code, JetBrains IDEs
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI, Web IDE, VS Code, JetBrains IDEs
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423524) for GitLab.com in GitLab 16.7.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423524) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
-> - [Updated LLM](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149619) from Claude 2.1 to Claude 3 Sonnet in GitLab 17.2.
-> - [Updated LLM](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157696) from Claude 3 Sonnet to Claude 3.5 Sonnet in GitLab 17.2.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423524) for GitLab.com in GitLab 16.7.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423524) for GitLab Self-Managed and GitLab Dedicated in GitLab 16.8.
+- [Updated LLM](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149619) from Claude 2.1 to Claude 3 Sonnet in GitLab 17.2.
+- [Updated LLM](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157696) from Claude 3 Sonnet to Claude 3.5 Sonnet in GitLab 17.2.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+
+{{< /history >}}
You can ask GitLab Duo Chat to create a CI/CD configuration:
@@ -392,16 +506,23 @@ Alternatively, you can use GitLab Duo Root Cause Analysis to [troubleshoot faile
## Troubleshoot failed CI/CD jobs with Root Cause Analysis
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123692) in GitLab 16.2 as an [experiment](../../policy/development_stages_support.md#experiment) on GitLab.com.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/441681) and moved to GitLab Duo Chat in GitLab 17.3.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
-> - Failed jobs widget for merge requests [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174586) in GitLab 17.7.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123692) in GitLab 16.2 as an [experiment](../../policy/development_stages_support.md#experiment) on GitLab.com.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/441681) and moved to GitLab Duo Chat in GitLab 17.3.
+- Changed to require GitLab Duo add-on in GitLab 17.6.
+- Failed jobs widget for merge requests [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174586) in GitLab 17.7.
+
+{{< /history >}}
You can use GitLab Duo Root Cause Analysis in GitLab Duo Chat to quickly identify and fix CI/CD job failures.
It analyzes the last 100,000 characters of the job log to determine the cause of failure and provides an example fix.
@@ -444,13 +565,20 @@ To troubleshoot a failed CI/CD job from the job log:
## Explain a vulnerability
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI
-**LLM:** Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/about-claude/models#claude-3-a-new-generation-of-ai)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI
+- LLM: Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/about-claude/models#claude-3-a-new-generation-of-ai)
+
+{{< /details >}}
+
+{{< history >}}
+
+- Changed to require GitLab Duo add-on in GitLab 17.6.
-> - Changed to require GitLab Duo add-on in GitLab 17.6.
+{{< /history >}}
You can ask GitLab Duo Chat to explain a vulnerability when you are viewing a SAST vulnerability report.
@@ -477,12 +605,19 @@ Use the commands to quickly accomplish specific tasks.
### Universal
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI, Web IDE, VS Code, JetBrains IDEs
+{{< details >}}
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI, Web IDE, VS Code, JetBrains IDEs
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+
+{{< /history >}}
These commands work in Duo Chat in all IDEs and in the GitLab UI:
@@ -494,10 +629,13 @@ These commands work in Duo Chat in all IDEs and in the GitLab UI:
### GitLab UI
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise- [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** GitLab UI
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise- [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: GitLab UI
+
+{{< /details >}}
These commands are dynamic and are available only in the GitLab UI when using Duo Chat:
@@ -509,12 +647,19 @@ These commands are dynamic and are available only in the GitLab UI when using Du
### IDE
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Editors:** Web IDE, VS Code, JetBrains IDEs
+{{< details >}}
+
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Editors: Web IDE, VS Code, JetBrains IDEs
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
-> - [Enabled](https://gitlab.com/groups/gitlab-org/-/epics/15227) for [self-hosted model configuration](../../administration/gitlab_duo_self_hosted/_index.md#self-hosted-ai-gateway-and-llms) as well as the [default GitLab external AI vendor configuration](../../administration/gitlab_duo_self_hosted/_index.md#gitlabcom-ai-gateway-with-default-gitlab-external-vendor-llms) in GitLab 17.9.
+{{< /history >}}
These commands work only when using Duo Chat in supported IDEs:
diff --git a/doc/user/gitlab_duo_chat/turn_on_off.md b/doc/user/gitlab_duo_chat/turn_on_off.md
index 9ae42a78784e031f9be50ab4eeadbeab7e66d026..834c191f5f69a56bfcb2431c3c9a7b808d466b6d 100644
--- a/doc/user/gitlab_duo_chat/turn_on_off.md
+++ b/doc/user/gitlab_duo_chat/turn_on_off.md
@@ -50,10 +50,13 @@ In GitLab 16.8, 16.9, and 16.10, GitLab Duo Chat is available in beta. To enable
1. To make sure GitLab Duo Chat works immediately, you must
[manually synchronize your subscription](#manually-synchronize-your-subscription).
-NOTE:
+{{< alert type="note" >}}
+
Usage of GitLab Duo Chat beta is governed by the [GitLab Testing Agreement](https://handbook.gitlab.com/handbook/legal/testing-agreement/).
Learn about [data usage when using GitLab Duo Chat](../gitlab_duo/data_usage.md).
+{{< /alert >}}
+
### Manually synchronize your subscription
You can [manually synchronize your subscription](../../subscriptions/self_managed/_index.md#manually-synchronize-subscription-data) if either:
diff --git a/doc/user/gitlab_duo_chat_enable.md b/doc/user/gitlab_duo_chat_enable.md
index fabc4f497ca4d94d5706dd6dcd3c203ab87419d6..cc1698455af8d7133c235e961765d67e6e286964 100644
--- a/doc/user/gitlab_duo_chat_enable.md
+++ b/doc/user/gitlab_duo_chat_enable.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../user/gitlab_duo_chat/turn_on_off.md'
-remove_date: '2025-06-11'
+redirect_to: ../user/gitlab_duo_chat/turn_on_off.md
+remove_date: "2025-06-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/gitlab_duo_chat_examples.md b/doc/user/gitlab_duo_chat_examples.md
index 1fb557ac83ad6ef8e4768d8f23224be5293cd75d..0174595093465e1d821c6278d22920896bcf7942 100644
--- a/doc/user/gitlab_duo_chat_examples.md
+++ b/doc/user/gitlab_duo_chat_examples.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../user/gitlab_duo_chat/examples.md'
-remove_date: '2025-06-11'
+redirect_to: ../user/gitlab_duo_chat/examples.md
+remove_date: "2025-06-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/gitlab_duo_chat_troubleshooting.md b/doc/user/gitlab_duo_chat_troubleshooting.md
index 9bd9de91fd7301f0020f54feb28407d114b51c8b..557e54996a610077827b8effc0be5bf40d409037 100644
--- a/doc/user/gitlab_duo_chat_troubleshooting.md
+++ b/doc/user/gitlab_duo_chat_troubleshooting.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../user/gitlab_duo_chat/troubleshooting.md'
-remove_date: '2025-06-11'
+redirect_to: ../user/gitlab_duo_chat/troubleshooting.md
+remove_date: "2025-06-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/gitlab_duo_examples.md b/doc/user/gitlab_duo_examples.md
index cba1b98a73cf57d99d395670c2c5a0b2445d80ae..5153a2599fcb244ee1beb0d7d4e181089e28098b 100644
--- a/doc/user/gitlab_duo_examples.md
+++ b/doc/user/gitlab_duo_examples.md
@@ -1,6 +1,6 @@
---
-redirect_to: '../user/gitlab_duo/use_cases.md'
-remove_date: '2025-06-11'
+redirect_to: ../user/gitlab_duo/use_cases.md
+remove_date: "2025-06-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/glql/_index.md b/doc/user/glql/_index.md
index a662b8018d1177680e697eb2c2b2490ea2c8c251..4576c4acc95a27a3c0b429a9c411aa4b244ef3e2 100644
--- a/doc/user/glql/_index.md
+++ b/doc/user/glql/_index.md
@@ -5,20 +5,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Query Language (GLQL)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14767) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `glql_integration`. Disabled by default.
-> - Enabled on GitLab.com in GitLab 17.4 for a subset of groups and projects.
-> - `iteration` and `cadence` fields [introduced](https://gitlab.com/gitlab-org/gitlab-query-language/gitlab-query-language/-/issues/74) in GitLab 17.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14767) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `glql_integration`. Disabled by default.
+- Enabled on GitLab.com in GitLab 17.4 for a subset of groups and projects.
+- `iteration` and `cadence` fields [introduced](https://gitlab.com/gitlab-org/gitlab-query-language/gitlab-query-language/-/issues/74) in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
GitLab Query Language (GLQL) is an [experimental](../../policy/development_stages_support.md) attempt
to create a single query language for all of GitLab.
Use it to filter and embed content from anywhere in the platform, using familiar syntax.
@@ -55,8 +65,8 @@ For a full list of supported fields, supported operators, and value types, see [
| `=` | Equals / Includes all in list | `is` (equal to) |
| `!=` | Doesn't equal / Isn't contained in list | `is not` (equal to) |
| `in` | Contained in list | `or` / `is one of` |
-| `>` | Greater than | **{dotted-circle}** No |
-| `<` | Less than | **{dotted-circle}** No |
+| `>` | Greater than | {{< icon name="dotted-circle" >}} No |
+| `<` | Less than | {{< icon name="dotted-circle" >}} No |
**Logical operators**: Only `and` is supported.
`or` is indirectly supported for some fields by using the `in` comparison operator.
@@ -78,7 +88,11 @@ Values can include:
## GLQL views
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/508956) in GitLab 17.7: Configuring the presentation layer using YAML front matter is deprecated.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/508956) in GitLab 17.7: Configuring the presentation layer using YAML front matter is deprecated.
+
+{{< /history >}}
A view created with GLQL is a display representation of a query that executes to
fetch the desired results.
diff --git a/doc/user/glql/fields.md b/doc/user/glql/fields.md
index 91af588e1c5620adfcdcb00a6d0b58780ba1fd61..c9569ec00b8df8d089af2950950c9a4a1d7fbb46 100644
--- a/doc/user/glql/fields.md
+++ b/doc/user/glql/fields.md
@@ -5,20 +5,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GLQL fields
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14767) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `glql_integration`. Disabled by default.
-> - Enabled on GitLab.com in GitLab 17.4 for a subset of groups and projects.
-> - `iteration` and `cadence` fields [introduced](https://gitlab.com/gitlab-org/gitlab-query-language/gitlab-query-language/-/issues/74) in GitLab 17.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14767) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `glql_integration`. Disabled by default.
+- Enabled on GitLab.com in GitLab 17.4 for a subset of groups and projects.
+- `iteration` and `cadence` fields [introduced](https://gitlab.com/gitlab-org/gitlab-query-language/gitlab-query-language/-/issues/74) in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
In a GitLab Query Language (GLQL) [query](_index.md#query-syntax), a field is the leftmost part
of the expression.
In queries, fields follow the syntax of `<field> <operator> <value> and ...`,
diff --git a/doc/user/glql/functions.md b/doc/user/glql/functions.md
index 3ecd6559931a01d0aeeb15d8d1e8629098c473c6..49b484995fda12c82ff4bcf2eb0cf70581ec80e2 100644
--- a/doc/user/glql/functions.md
+++ b/doc/user/glql/functions.md
@@ -5,20 +5,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GLQL functions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14767) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `glql_integration`. Disabled by default.
-> - Enabled on GitLab.com in GitLab 17.4 for a subset of groups and projects.
-> - `iteration` and `cadence` fields [introduced](https://gitlab.com/gitlab-org/gitlab-query-language/gitlab-query-language/-/issues/74) in GitLab 17.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14767) in GitLab 17.4 [with a flag](../../administration/feature_flags.md) named `glql_integration`. Disabled by default.
+- Enabled on GitLab.com in GitLab 17.4 for a subset of groups and projects.
+- `iteration` and `cadence` fields [introduced](https://gitlab.com/gitlab-org/gitlab-query-language/gitlab-query-language/-/issues/74) in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Use functions with [GitLab Query Language (GLQL)](_index.md) to create dynamic queries.
## Functions inside query
diff --git a/doc/user/group/_index.md b/doc/user/group/_index.md
index cbc59a2f125e7defdb5f050659b6e6b5e31be4ff..f12babc0a0f73e7f776ed8871fc4a46b55f22fc7 100644
--- a/doc/user/group/_index.md
+++ b/doc/user/group/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Groups
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In GitLab, you use groups to manage one or more related projects at the same time.
@@ -65,7 +68,8 @@ The following table describes the most common models of structuring groups.
<!-- vale gitlab_base.Simplicity = YES -->
-NOTE:
+{{< alert type="note" >}}
+
On GitLab Self-Managed, if you want to see an overview of your entire organization, you should create one top-level group.
For more information about efforts to create an organization view of all groups,
[see epic 9266](https://gitlab.com/groups/gitlab-org/-/epics/9266).
@@ -75,6 +79,8 @@ A top-level group offers insights in your entire organization through a complete
[compliance center](../compliance/compliance_center/_index.md), and
[value stream analytics](value_stream_analytics/_index.md).
+{{< /alert >}}
+
## Group visibility
Like projects, a group can be configured to be visible to:
@@ -146,7 +152,11 @@ To view the activity of a group:
### Access a group by using the group ID
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165889) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165889) in GitLab 17.5.
+
+{{< /history >}}
You can access a group by using its ID instead of its name at `https://gitlab.example.com/-/g/<id>`.
For example, if your group `example-group` has an ID `123456`, you can access the group either at
@@ -157,7 +167,7 @@ You might need the group ID if you want to interact with it using the [GitLab AP
To copy the Group ID:
1. On the left sidebar, select **Search or go to** and find your Group.
-1. On the Group overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**).
+1. On the Group overview page, in the upper-right corner, select **Actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Copy Group ID**.
## Create a group
@@ -166,7 +176,7 @@ To create a group:
<!-- vale gitlab_base.FutureTense = NO -->
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. Select **Create group**.
1. In the **Group name** text box, enter the name of the group. For a list of words that cannot be used as group names, see
[reserved names](../reserved_names.md).
@@ -203,7 +213,11 @@ To edit group details:
## Leave a group
-> - The button to leave a group [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7.
+{{< history >}}
+
+- The button to leave a group [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7.
+
+{{< /history >}}
When you leave a group:
@@ -218,7 +232,11 @@ To leave a group:
## Delete a group
-> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+{{< history >}}
+
+- Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+
+{{< /history >}}
To delete a group and its contents:
@@ -232,7 +250,7 @@ You can also delete a group from the groups dashboard:
1. On the left sidebar, select **Search or go to**.
1. Select **View all my groups**.
-1. Select (**{ellipsis_v}**) for the group you want to delete.
+1. Select ({{< icon name="ellipsis_v" >}}) for the group you want to delete.
1. Select **Delete**.
1. In the **Delete group** section, select **Delete group**.
1. On the confirmation dialog, type the group name and select **Confirm**.
@@ -242,14 +260,20 @@ On GitLab [Premium](https://about.gitlab.com/pricing/premium/) and [Ultimate](ht
If the user who scheduled the group deletion loses access to the group (for example, by leaving the group, having their role downgraded, or being banned from the group) before the deletion occurs,
the deletion job will instead restore and unarchive the group, so the group will no longer be scheduled for deletion.
- WARNING:
+ {{< alert type="warning" >}}
+
If the user who scheduled the group deletion regains Owner role or administrator access before the job runs, then the job removes the group permanently.
+ {{< /alert >}}
+
### View groups pending deletion
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To view a list of the subgroups that are pending deletion in a group:
@@ -260,11 +284,18 @@ Groups that are marked for deletion are labeled **Pending deletion**.
## Delete a group immediately
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+- Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+
+{{< /history >}}
If you don't want to wait, you can delete a group immediately.
@@ -285,9 +316,12 @@ This action deletes the group, its subgroups, projects, and all related resource
## Restore a group
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To restore a group that is marked for deletion:
@@ -333,10 +367,13 @@ A table displays the member's:
- **Expiration** date of their group membership.
- **Activity** related to their account.
-NOTE:
+{{< alert type="note" >}}
+
The display of group members' **Source** might be inconsistent.
For more information, see [issue 23020](https://gitlab.com/gitlab-org/gitlab/-/issues/23020).
+{{< /alert >}}
+
To view all namespace members (and their respective occupied seats), in the top-level namespace, [view the **Usage Quotas** page](../../subscriptions/gitlab_com/_index.md#view-seat-usage).
## Filter and sort members in a group
@@ -367,7 +404,7 @@ You can search for members by name, username, or [public email](../profile/_inde
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Manage > Members**.
1. Above the list of members, in the **Filter members** box, enter search criteria.
-1. To the right of the **Filter members** box, select the magnifying glass (**{search}**).
+1. To the right of the **Filter members** box, select the magnifying glass ({{< icon name="search" >}}).
### Sort members in a group
@@ -378,12 +415,16 @@ You can sort members by **Account**, **Access granted**, **Role**, or **Last sig
1. Above the list of members, in the upper-right corner, from the **Account** list, select
the criteria to filter by.
1. To switch the sort between ascending and descending, to the right of the **Account** list, select the
- arrow (**{sort-lowest}** or **{sort-highest}**).
+ arrow ({{< icon name="sort-lowest" >}} or {{< icon name="sort-highest" >}}).
## Add users to a group
-> - Expiring access email notification [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.2.
-> - Access expiration date for direct members of subgroups and projects [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471051) in GitLab 17.4.
+{{< history >}}
+
+- Expiring access email notification [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.2.
+- Access expiration date for direct members of subgroups and projects [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471051) in GitLab 17.4.
+
+{{< /history >}}
You can give a user access to all projects in a group.
@@ -408,10 +449,13 @@ Prerequisites:
If you enter an access expiration date, the group member gets an email notification
seven days before their access expires.
- WARNING:
+ {{< alert type="warning" >}}
+
Maintainers have full permissions until their role expires, including the ability to
extend their own access expiration date.
+ {{< /alert >}}
+
1. Select **Invite**.
If you invite the user by their:
@@ -452,7 +496,7 @@ To remove a member from a group:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Manage > Members**.
-1. Next to the member you want to remove, select the vertical ellipsis (**{ellipsis_v}**).
+1. Next to the member you want to remove, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. Select **Remove member**.
1. Optional. On the **Remove member** confirmation dialog, select one or both checkboxes:
- **Also remove direct user membership from subgroups and projects**
diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md
index 804adbe7c4b6020b78f18c4ef16fe466d31288e6..616101c6ab9ba4345dbd75aa38d3db53ecdd30d7 100644
--- a/doc/user/group/access_and_permissions.md
+++ b/doc/user/group/access_and_permissions.md
@@ -10,11 +10,18 @@ For more information, see also [Sharing projects and groups](../project/members/
## Group push rules
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Moved to Settings/Repository](https://gitlab.com/gitlab-org/gitlab/-/issues/220365) in GitLab 15.4.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Moved to Settings/Repository](https://gitlab.com/gitlab-org/gitlab/-/issues/220365) in GitLab 15.4.
+
+{{< /history >}}
Group push rules allow group maintainers to set
[push rules](../project/repository/push_rules.md) for newly created projects in the specific group.
@@ -39,8 +46,12 @@ The group's new subgroups have push rules set for them based on either:
## Restrict Git access protocols
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365601) in GitLab 15.1.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/365357) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365601) in GitLab 15.1.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/365357) in GitLab 16.0.
+
+{{< /history >}}
You can set the permitted protocols used to access a group's repositories to either SSH, HTTPS, or both. This setting
is disabled when the [instance setting](../../administration/settings/visibility_and_access_controls.md#configure-enabled-git-access-protocols) is
@@ -56,9 +67,12 @@ To change the permitted Git access protocols for a group:
## Restrict group access by IP address
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To ensure only people from your organization can access particular resources, you can restrict access to groups by IP
address. This top-level group setting applies to:
@@ -117,11 +131,18 @@ To allow runner downloading, add the [outbound runner CIDR ranges](../gitlab_com
## Restrict group access by domain
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Support for restricting group memberships to groups with a subset of the allowed email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/354791) in GitLab 15.1.1
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Support for restricting group memberships to groups with a subset of the allowed email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/354791) in GitLab 15.1.1
+
+{{< /history >}}
You can define an email domain allowlist at the top-level namespace to restrict which users can
access a group and its projects. A user's primary email domain must match an entry in the allowlist
@@ -148,11 +169,14 @@ You cannot restrict the most popular public email domains, such as:
When you share a group, both the source and target namespaces must allow the domains of the members' email addresses.
-NOTE:
+{{< alert type="note" >}}
+
Removing a domain from the **Restrict membership by email** list does not remove existing users with that domain from the group or its projects.
Also, if you share a group or project with another group, the target group can add more email domains to its list that are not in the list of the source group.
Hence, this feature does not ensure that the current members always conform to the **Restrict membership by email** list.
+{{< /alert >}}
+
## Prevent users from requesting access to a group
As a group Owner, you can prevent non-members from requesting access to
@@ -166,17 +190,23 @@ your group.
## Prevent project forking outside group
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
By default, projects in a group can be forked.
However, you can prevent the projects in a group from being forked outside of the current top-level group.
-NOTE:
+{{< alert type="note" >}}
+
Prevent forking outside the top-level group when possible to reduce potential avenues for bad actors.
However, if you expect a lot of external collaboration, allowing forks outside the top-level group might be unavoidable.
+{{< /alert >}}
+
Prerequisites:
- This setting is enabled on the top-level group only.
@@ -195,9 +225,12 @@ Existing forks are not removed.
## Prevent members from being added to projects in a group
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
As a group Owner, you can prevent any new project membership for all
projects in a group, allowing tighter control over project membership.
@@ -227,11 +260,18 @@ After you lock the membership for a group:
## Manage group memberships with LDAP
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- Support for custom roles for users synced in groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435229) in GitLab 17.2.
-> - Support for custom roles for users synced in groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435229) in GitLab 17.2.
+{{< /history >}}
Group syncing allows LDAP groups to be mapped to GitLab groups. This provides more control over per-group user management. To configure group syncing, edit the `group_base` **DN** (`'OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org'`). This **OU** contains all groups that are associated with GitLab groups.
@@ -250,16 +290,22 @@ For example:
For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/ldap_synchronization.md#group-sync).
-NOTE:
+{{< alert type="note" >}}
+
When you add LDAP group syncing, if an LDAP user is a group member and they are not part of the LDAP group, they are removed from the group.
+{{< /alert >}}
+
You can use a workaround to [manage project access through LDAP groups](../project/working_with_projects.md#manage-project-access-through-ldap-groups).
### Create group links with a CN
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To create group links with LDAP group CN:
@@ -275,9 +321,12 @@ To create group links with LDAP group CN:
### Create group links with a filter
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To create group links with an LDAP user filter:
@@ -289,9 +338,12 @@ To create group links with an LDAP user filter:
### Override user permissions
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
LDAP user permissions can be manually overridden by an administrator. To override a user's permissions:
@@ -305,7 +357,7 @@ LDAP user permissions can be manually overridden by an administrator. To overrid
1. Optional. If the user you want to edit is displayed as having inherited membership,
[filter the subgroup to show direct members](_index.md#filter-a-group) before
overriding LDAP user permissions.
-1. In the row for the user you are editing, select the pencil (**{pencil}**) icon.
+1. In the row for the user you are editing, select the pencil ({{< icon name="pencil" >}}) icon.
1. Select **Edit permissions** in the dialog.
Now you can edit the user's permissions from the **Members** page.
diff --git a/doc/user/group/clusters/_index.md b/doc/user/group/clusters/_index.md
index 0d571cbb6a58656adedf79b03762c6a503edfd12..832398cb24d43a5c438cf0105aaa9cb8ec030bd9 100644
--- a/doc/user/group/clusters/_index.md
+++ b/doc/user/group/clusters/_index.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group-level Kubernetes clusters (certificate-based) (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab,
use the [GitLab agent](../../clusters/agent/_index.md).
+{{< /alert >}}
+
Similar to [project-level](../../project/clusters/_index.md) and
[instance-level](../../instance/clusters/_index.md) Kubernetes clusters,
group-level Kubernetes clusters allow you to connect a Kubernetes cluster to
@@ -95,9 +101,12 @@ The domain should have a wildcard DNS configured to the Ingress IP address. [Mor
## Environment scopes
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When adding more than one Kubernetes cluster to your project, you need to differentiate
them with an environment scope. The environment scope associates clusters with
@@ -155,9 +164,12 @@ The result is:
## Cluster environments
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
For a consolidated view of which CI [environments](../../../ci/environments/_index.md)
are deployed to the Kubernetes cluster, see the documentation for
diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md
index fb7272e6d872b931c38061c1c5dcf3d217c60e4d..e6cd990c3ef6c94590b66deb3bef23dceb53006f 100644
--- a/doc/user/group/compliance_frameworks.md
+++ b/doc/user/group/compliance_frameworks.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Compliance frameworks
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can create a compliance framework that is a label to identify that your project has certain compliance
requirements or needs additional oversight.
@@ -52,7 +55,11 @@ or deleted at the subgroup or project level. Project owners can choose a framewo
## Apply a compliance framework to a project
-> - Assigning multiple compliance frameworks [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13294) in GitLab 17.3.
+{{< history >}}
+
+- Assigning multiple compliance frameworks [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13294) in GitLab 17.3.
+
+{{< /history >}}
You can apply multiple compliance frameworks to a project but cannot apply compliance frameworks to projects in personal namespaces.
@@ -67,7 +74,11 @@ has the correct permissions. The GitLab UI presents a read-only view to discoura
## Default compliance frameworks
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375036) in GitLab 15.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375036) in GitLab 15.6.
+
+{{< /history >}}
Group owners can set a default compliance framework. The default framework is applied to all the new and imported
projects that are created in that group. It does not affect the framework applied to the existing projects. The
diff --git a/doc/user/group/compliance_pipelines.md b/doc/user/group/compliance_pipelines.md
index ba642cc81a7fcff8b4e4d2feac26fcfc15aac3f9..59372d7a79d6f8dcf1a113a5ff3a4791ef26cc7f 100644
--- a/doc/user/group/compliance_pipelines.md
+++ b/doc/user/group/compliance_pipelines.md
@@ -7,15 +7,21 @@ title: Compliance pipelines (deprecated)
<!--- start_remove The following content will be removed on remove_date: '2025-08-15' -->
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/159841) in GitLab 17.3
and is planned for removal in 19.0. Use [pipeline execution policy type](../application_security/policies/pipeline_execution_policies.md) instead.
This change is a breaking change. For more information, see the [migration guide](#pipeline-execution-policies-migration).
+{{< /alert >}}
+
Group owners can configure a compliance pipeline in a project separate to other projects. By default, the compliance
pipeline configuration (for example, `.compliance-gitlab-ci.yml`) is run instead of the pipeline configuration (for example, `.gitlab-ci.yml`) of labeled
projects.
@@ -27,10 +33,13 @@ However, the compliance pipeline configuration can reference the `.gitlab-ci.yml
- Jobs and variables defined in the compliance pipeline can't be changed by variables in the labeled project's
`.gitlab-ci.yml` file.
-NOTE:
+{{< alert type="note" >}}
+
Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/414004), project pipelines must be included first at the top of compliance pipeline configuration
to prevent projects overriding settings downstream.
+{{< /alert >}}
+
For more information, see:
- [Example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from
@@ -90,7 +99,11 @@ To ensure that the correct compliance pipeline is included in a project:
## Configure a compliance pipeline
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11, compliance frameworks moved to compliance center.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11, compliance frameworks moved to compliance center.
+
+{{< /history >}}
To configure a compliance pipeline:
diff --git a/doc/user/group/contribution_analytics/_index.md b/doc/user/group/contribution_analytics/_index.md
index 45b9bd7cd26cdcc49bffc973429f9102127c8707..6911bea246987fb0cb45af55327325366999d9c4 100644
--- a/doc/user/group/contribution_analytics/_index.md
+++ b/doc/user/group/contribution_analytics/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Contribution analytics
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Contribution analytics provide an overview of the
[contribution events](../../profile/contributions_calendar.md#user-contribution-events) made by your group's members.
@@ -49,15 +52,15 @@ To do this, hover over the bar with the member's name.
You can zoom in on a bar chart to display only a subset of group members.
-To do this, select the sliders (**{status-paused}**) below the chart and slide them along the axis.
+To do this, select the sliders ({{< icon name="status-paused" >}}) below the chart and slide them along the axis.
### Sort contributions
Contributions per group member are also displayed in tabular format.
The table columns include the members' names and the number of contributions for different events.
-To sort the table by a column, select the column header or the chevron (**{chevron-lg-down}**
-for descending order, **{chevron-lg-up}** for ascending order).
+To sort the table by a column, select the column header or the chevron ({{< icon name="chevron-lg-down" >}}
+for descending order, {{< icon name="chevron-lg-up" >}} for ascending order).
## Change the time period
diff --git a/doc/user/group/credentials_inventory.md b/doc/user/group/credentials_inventory.md
index a34c71088422e96c7a8c4246a27e35ee2506fc27..97c6c2966b3f421103207e683f632d50e3dbf3f4 100644
--- a/doc/user/group/credentials_inventory.md
+++ b/doc/user/group/credentials_inventory.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Credentials inventory for GitLab.com
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297441) on GitLab.com in GitLab 17.5.
+- Tier: Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297441) on GitLab.com in GitLab 17.5.
+
+{{< /history >}}
As a GitLab.com top-level group owner, you are responsible for the overall security of your groups and projects.
To assist, GitLab provides an inventory of all the credentials that can be used to access your groups and projects.
diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md
index 2e84b31c707ca4fb84a6c0dace19e6caff10d95f..fb9493763ffaa43712acd355873f8864088d6e4c 100644
--- a/doc/user/group/custom_project_templates.md
+++ b/doc/user/group/custom_project_templates.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "To speed up project creation in your group, build custom project templates and share them with your group."
+description: To speed up project creation in your group, build custom project templates and share them with your group.
title: Custom group-level project templates
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you create a project, you can [choose from a list of templates](../project/_index.md).
These templates, for things like GitLab Pages or Ruby, populate the new project with a copy of the files contained in the
diff --git a/doc/user/group/devops_adoption/_index.md b/doc/user/group/devops_adoption/_index.md
index e54d776f4a05b7efef5abb487bc4cf1f7af4eae4..17983d28cf833fea0282fa10f85aeacd8405875d 100644
--- a/doc/user/group/devops_adoption/_index.md
+++ b/doc/user/group/devops_adoption/_index.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: DevOps adoption by group
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/367093) to the [Registration Features Program](../../../administration/settings/usage_statistics.md#registration-features-program) in GitLab 16.6.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/367093) to the [Registration Features Program](../../../administration/settings/usage_statistics.md#registration-features-program) in GitLab 16.6.
+
+{{< /history >}}
DevOps adoption shows you how groups in your organization adopt and use GitLab features.
This information is available for groups and [instances](../../../administration/analytics/dev_ops_reports.md).
@@ -100,4 +107,4 @@ To remove a subgroup from the DevOps adoption report:
- From the **Add or remove subgroups** dropdown list, clear the subgroup you want to remove.
- From the **Adoption by subgroup** table, in the row of the group you want to remove, select
-**Remove Group from the table** (**{remove}**).
+**Remove Group from the table** ({{< icon name="remove" >}}).
diff --git a/doc/user/group/epics/_index.md b/doc/user/group/epics/_index.md
index 72697b0c8fd6f211719e12840aeb5cb3969962e3..c7d459f0eeba2f1078b069774e38daa5f87be8d8 100644
--- a/doc/user/group/epics/_index.md
+++ b/doc/user/group/epics/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Epics
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
An epic in GitLab represents a significant body of work that can be broken down into smaller,
manageable parts.
@@ -82,9 +85,13 @@ graph TD
### Child issues from different group hierarchies
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371081) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `epic_issues_from_different_hierarchies`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/373304) in GitLab 15.5.
-> - Feature flag `epic_issues_from_different_hierarchies` removed in GitLab 15.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371081) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `epic_issues_from_different_hierarchies`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/373304) in GitLab 15.5.
+- Feature flag `epic_issues_from_different_hierarchies` removed in GitLab 15.6.
+
+{{< /history >}}
You can add issues from a different group hierarchy to an epic.
To do it, paste the issue URL when
@@ -92,9 +99,12 @@ To do it, paste the issue URL when
## Roadmap in epics
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that
have a start or due date, you can go to a [roadmap](../roadmap/_index.md)
@@ -106,7 +116,7 @@ of the child epics from the epic.
If your administrator [enabled the new look for epics](epic_work_items.md):
-- On the **Child items** section header, select **More actions** (**{ellipsis_v}**) **> View on a roadmap**.
+- On the **Child items** section header, select **More actions** ({{< icon name="ellipsis_v" >}}) **> View on a roadmap**.
A roadmap filtered for the parent epic opens.
diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md
index c9295834ad8cde4de9c6141a002627a8ce7937bf..2119981a9379436f8db59b8caf54747bb0f39bba 100644
--- a/doc/user/group/epics/epic_boards.md
+++ b/doc/user/group/epics/epic_boards.md
@@ -5,18 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Epic boards
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Displaying total weight on the top of lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364503) in GitLab 15.11.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Displaying total weight on the top of lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364503) in GitLab 15.11.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Epic boards build on the existing [epic tracking functionality](_index.md) and
[labels](../../project/labels.md). Your epics appear as cards in vertical lists, organized by their assigned
labels.
-On the top of each list, you can see the number of epics in the list (**{epic}**) and the total weight of all its epics (**{weight}**).
+On the top of each list, you can see the number of epics in the list ({{< icon name="epic" >}}) and the total weight of all its epics ({{< icon name="weight" >}}).
<div class="video-fallback">
See the video: <a href="https://www.youtube.com/watch?v=eQUnHwbKEkY">Epics and Issue Boards - Project Management</a>.
@@ -81,7 +88,11 @@ To delete the active epic board:
### Create a new list
-> - Creating a list between existing lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462515) in GitLab 17.5.
+{{< history >}}
+
+- Creating a list between existing lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462515) in GitLab 17.5.
+
+{{< /history >}}
Prerequisites:
@@ -119,7 +130,7 @@ Prerequisites:
To remove a list from an epic board:
-1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**).
+1. On the top of the list you want to remove, select the **List settings** icon ({{< icon name="settings" >}}).
The list settings sidebar opens on the right.
1. Select **Remove list**.
1. On the confirmation dialog, select **OK**.
@@ -133,7 +144,7 @@ Prerequisites:
To create an epic from a list in epic board:
-1. On the top of a list, select the **New epic** (**{plus}**) icon.
+1. On the top of a list, select the **New epic** ({{< icon name="plus" >}}) icon.
1. Enter the new epic's title.
1. Select **Create epic**.
@@ -162,8 +173,8 @@ You can filter by the following:
Epics on an epic board show a summary of their issues, weight, and progress.
To see the number of open and closed issues and the completed and incomplete
-weight, hover over the issues icon **{issues}**, weight icon **{weight}**, or
-progress icon **{progress}**.
+weight, hover over the issues icon {{< icon name="issues" >}}, weight icon {{< icon name="weight" >}}, or
+progress icon {{< icon name="progress" >}}.
### Move epics and lists
@@ -181,7 +192,11 @@ You can't move the **Open** and **Closed** lists, but you can hide them when edi
#### Move an epic to the start of the list
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4.
+
+{{< /history >}}
When you have many epics, it's inconvenient to manually drag an epic from the bottom of a board list all
the way to the top. You can move epics to the top of the list with a menu shortcut.
@@ -195,11 +210,15 @@ Prerequisites:
To move an epic to the start of the list:
1. In an epic board, hover over the card of the epic you want to move.
-1. Select **Card options** (**{ellipsis_v}**), then **Move to start of list**.
+1. Select **Card options** ({{< icon name="ellipsis_v" >}}), then **Move to start of list**.
#### Move an epic to the end of the list
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4.
+
+{{< /history >}}
When you have many epics, it's inconvenient to manually drag an epic from the top of a board list all
the way to the bottom. You can move epics to the bottom of the list with a menu shortcut.
@@ -213,7 +232,7 @@ Prerequisites:
To move an epic to the end of the list:
1. In an epic board, hover over the card of the epic you want to move.
-1. Select **Card options** (**{ellipsis_v}**), then **Move to end of list**.
+1. Select **Card options** ({{< icon name="ellipsis_v" >}}), then **Move to end of list**.
#### Dragging epics between lists
@@ -234,7 +253,7 @@ Prerequisites:
To edit the scope of an epic board:
-1. In the upper-right corner, select **Configure board** (**{settings}**).
+1. In the upper-right corner, select **Configure board** ({{< icon name="settings" >}}).
1. Optional:
- Edit the board's title.
- Show or hide the Open and Closed columns.
diff --git a/doc/user/group/epics/epic_work_items.md b/doc/user/group/epics/epic_work_items.md
index 217ead6585e0f708fba263d98b11498f8b9606da..3762465707770b214378ae852197b3bc0d5bcbfa 100644
--- a/doc/user/group/epics/epic_work_items.md
+++ b/doc/user/group/epics/epic_work_items.md
@@ -5,20 +5,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Test a new look for epics
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9290) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `work_item_epics`. Disabled by default. This feature is in [beta](../../../policy/development_stages_support.md#beta).
-> - Listing epics using the [GraphQL API](../../../api/graphql/reference/_index.md) [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12852) in GitLab 17.4.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/470685) in GitLab 17.6.
-> - [Enabled by default on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/468310) in GitLab 17.7.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9290) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `work_item_epics`. Disabled by default. This feature is in [beta](../../../policy/development_stages_support.md#beta).
+- Listing epics using the [GraphQL API](../../../api/graphql/reference/_index.md) [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12852) in GitLab 17.4.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/470685) in GitLab 17.6.
+- [Enabled by default on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/468310) in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
<!-- When epics as work items are generally available and `work_item_epics` flag is removed,
incorporate this content into epics/index.md and redirect this page there -->
@@ -44,8 +54,11 @@ between old and new experience to provide details while opening support request.
### Disable the new experience
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
We don't recommend disabling this change, because we'd like your feedback on what you don't like about it.
If you have to disable the new experience to unblock your workflow, disable the `work_item_epics`
diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md
index 2daa2badeee73710a1d2cfc01274bfbd981dc256..1e8445d380670c2c09f2cecd37e4ece537437e56 100644
--- a/doc/user/group/epics/linked_epics.md
+++ b/doc/user/group/epics/linked_epics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Linked epics
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Linked epics are a bi-directional relationship between any two epics and appear in a block below
the epic description. You can link epics in different groups.
@@ -99,7 +102,11 @@ When you link epics for planning:
## Add a linked epic
-> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8.
+{{< history >}}
+
+- Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8.
+
+{{< /history >}}
Prerequisites:
@@ -110,7 +117,7 @@ Prerequisites:
To link one epic to another:
1. In the **Linked epics** section of an epic,
- select the add linked epic button (**{plus}**).
+ select the add linked epic button ({{< icon name="plus" >}}).
1. Select the relationship between the two epics. Either:
- **relates to**
@@ -142,7 +149,11 @@ The linked epics are then displayed on the epic grouped by relationship.
## Remove a linked epic
-> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8.
+{{< history >}}
+
+- Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8.
+
+{{< /history >}}
Prerequisites:
@@ -150,7 +161,7 @@ Prerequisites:
To remove a linked epic:
-- In the **Linked epics** section of an epic, next to each epic, select **Remove** (**{close}**).
+- In the **Linked epics** section of an epic, next to each epic, select **Remove** ({{< icon name="close" >}}).
The relationship is removed from both epics.
@@ -165,7 +176,11 @@ If you try to close a blocked epic using the "Close epic" button, a confirmation
## When using the new look for epics
-> - Linking epics to issues, tasks, and OKRs [introduced](https://gitlab.com/groups/gitlab-org/-/epics/9290) in GitLab 17.5. Your administrator must have [enabled the new look for epics](epic_work_items.md).
+{{< history >}}
+
+- Linking epics to issues, tasks, and OKRs [introduced](https://gitlab.com/groups/gitlab-org/-/epics/9290) in GitLab 17.5. Your administrator must have [enabled the new look for epics](epic_work_items.md).
+
+{{< /history >}}
<!-- When epics as work items are GA, integrate this and below sections with the ones above. -->
@@ -232,6 +247,6 @@ Prerequisites:
To remove a linked item:
-- In the **Linked items** section of an epic, next to each item, select **Remove** (**{close}**).
+- In the **Linked items** section of an epic, next to each item, select **Remove** ({{< icon name="close" >}}).
The relationship is removed from both items.
diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md
index 31f47aada0046793dfeb54a2767cdbcf87960e87..1c02cbc8c5bd7e19c7cdeebbbc8c60a54d7210e8 100644
--- a/doc/user/group/epics/manage_epics.md
+++ b/doc/user/group/epics/manage_epics.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Manage epics
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page collects instructions for all the things you can do with [epics](_index.md) or in relation
to them.
## Create an epic
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -24,8 +31,8 @@ To create an epic in the group you're in:
1. Get to the New Epic form:
- Go to your group and from the left sidebar select **Epics**. Then select **New epic**.
- - From an epic in your group, select **Epic actions** (**{ellipsis_v}**). Then select **New epic**.
- - From anywhere, in the top menu, select **New** (**{plus-square}**). Then select **New epic**.
+ - From an epic in your group, select **Epic actions** ({{< icon name="ellipsis_v" >}}). Then select **New epic**.
+ - From anywhere, in the top menu, select **New** ({{< icon name="plus-square" >}}). Then select **New epic**.
- In an empty [roadmap](../roadmap/_index.md), select **New epic**.
1. Enter a title.
@@ -63,7 +70,11 @@ The parent epic's start date then reflects this change and propagates upwards to
## Edit an epic
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
After you create an epic, you can edit the following details:
@@ -91,8 +102,12 @@ To edit an epic's start date, due date, or labels:
### Reorder list items in the epic description
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.1.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.1.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
When you view an epic that has a list in the description, you can also reorder the list items.
@@ -105,14 +120,18 @@ Prerequisites:
To reorder list items, when viewing an epic:
-1. Hover over the list item row to make the grip icon (**{grip}**) visible.
+1. Hover over the list item row to make the grip icon ({{< icon name="grip" >}}) visible.
1. Select and hold the grip icon.
1. Drag the row to the new position in the list.
1. Release the grip icon.
### Bulk edit epics
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Users with at least the Planner role can manage epics.
@@ -132,17 +151,27 @@ To update multiple epics at the same time:
### Open epics in a drawer
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464063) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `issues_list_drawer`. Disabled by default.
-> - Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170066) from `issues_list_drawer` to `epics_list_drawer` in GitLab 17.6.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464063) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `issues_list_drawer`. Disabled by default.
+- Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/170066) from `issues_list_drawer` to `epics_list_drawer` in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
When this feature is enabled, when you select an epic from the list or epic board, it opens in a drawer.
You can then edit the epic or create comments.
@@ -157,17 +186,27 @@ To open the epic in full view, either:
## Assignees
-DETAILS:
-**Status:** Beta
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Status: Beta
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4231) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `work_items_beta`. Disabled by default. This feature is in [beta](../../../policy/development_stages_support.md#beta).
+
+{{< /history >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4231) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `work_items_beta`. Disabled by default. This feature is in [beta](../../../policy/development_stages_support.md#beta).
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
If your administrator [enabled the new look for epics](epic_work_items.md),
an epic can be assigned to one or more users.
@@ -183,7 +222,11 @@ If you find a bug, use the
### Change assignee on an epic
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -202,12 +245,19 @@ The assignee is changed without having to refresh the page.
## Epic color
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79940) in GitLab 14.9 [with a flag](../../../administration/feature_flags.md) named `epic_color_highlight`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365336) in GitLab 16.11. Feature flag `epic_color_highlight` removed.
-> - Customizable color [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394864) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79940) in GitLab 14.9 [with a flag](../../../administration/feature_flags.md) named `epic_color_highlight`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365336) in GitLab 16.11. Feature flag `epic_color_highlight` removed.
+- Customizable color [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394864) in GitLab 17.5.
+
+{{< /history >}}
You can set a color for an epic to categorize and prioritize tasks visually.
Use colors to:
@@ -228,7 +278,11 @@ On epic boards, the color shows on the epic's card accent:
### Change an epic's color
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -247,8 +301,12 @@ The epic's color is updated.
## Delete an epic
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/452189) in GitLab 16.11. In GitLab 16.10 and earlier, if you delete an epic, all its child epics and their descendants are deleted as well. If needed, you can [remove child epics](#remove-a-child-epic-from-a-parent-epic) from the parent epic before you delete it.
-> - [Allowed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) Planner role to delete an epic in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/452189) in GitLab 16.11. In GitLab 16.10 and earlier, if you delete an epic, all its child epics and their descendants are deleted as well. If needed, you can [remove child epics](#remove-a-child-epic-from-a-parent-epic) from the parent epic before you delete it.
+- [Allowed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) Planner role to delete an epic in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -256,14 +314,18 @@ Prerequisites:
To delete an epic:
-1. Select **Epic actions** (**{ellipsis_v}**), then **Delete epic**.
+1. Select **Epic actions** ({{< icon name="ellipsis_v" >}}), then **Delete epic**.
1. Select **Delete**. On the confirmation dialog, select **Delete epic**.
Deleting an epic releases all existing issues from their associated epic in the system.
## Close an epic
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -271,13 +333,17 @@ Prerequisites:
To close an epic:
-- In the upper-right corner, select **Epic actions** (**{ellipsis_v}**), then **Close epic**.
+- In the upper-right corner, select **Epic actions** ({{< icon name="ellipsis_v" >}}), then **Close epic**.
You can also use the `/close` [quick action](../../project/quick_actions.md).
## Reopen a closed epic
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can reopen an epic that was closed.
@@ -287,7 +353,7 @@ Prerequisites:
To do so, either:
-- In the upper-right corner, select **Epic actions** (**{ellipsis_v}**) and then **Reopen epic**.
+- In the upper-right corner, select **Epic actions** ({{< icon name="ellipsis_v" >}}) and then **Reopen epic**.
- Use the `/reopen` [quick action](../../project/quick_actions.md).
You can also create an epic by
@@ -320,7 +386,11 @@ To view epics in a group:
### Who can view an epic
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Whether you can view an epic depends on the [group visibility level](../../public_access.md) and
the epic's [confidentiality status](#make-an-epic-confidential):
@@ -337,7 +407,11 @@ than 1000. The cached value is rounded to thousands or millions and updated ever
## Filter the list of epics
-> - Filtering by group was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385191) in GitLab 15.9.
+{{< history >}}
+
+- Filtering by group was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385191) in GitLab 15.9.
+
+{{< /history >}}
You can filter the list of epics by:
@@ -361,9 +435,13 @@ To filter:
### Filter with the OR operator
-> - OR filtering for labels and authors was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382969) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104292) in GitLab 15.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/296031) in GitLab 17.0. Feature flag `or_issuable_queries` removed.
+{{< history >}}
+
+- OR filtering for labels and authors was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382969) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104292) in GitLab 15.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/296031) in GitLab 17.0. Feature flag `or_issuable_queries` removed.
+
+{{< /history >}}
You can use the OR operator (**is one of: `||`**) when you [filter the list of epics](#filter-the-list-of-epics) by:
@@ -400,16 +478,23 @@ or newest items to be shown first.
## Make an epic confidential
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
If you're working on items that contain private information, you can make an epic confidential.
-NOTE:
+{{< alert type="note" >}}
+
A confidential epic can only contain [confidential issues](../../project/issues/confidential_issues.md)
and confidential child epics. However, merge requests are public, if created in a public project.
Read [Merge requests for confidential issues](../../project/merge_requests/confidential.md)
to learn how to create a confidential merge request.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Planner role for the epic's group.
@@ -465,7 +550,11 @@ Tasks are not included in these counts.
### View epic progress
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5163) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5163) in GitLab 17.1.
+
+{{< /history >}}
On the **Child issues and epics** section header, the epic progress percentage is displayed.
@@ -485,10 +574,17 @@ Tasks are not included in this calculation.
### Health status
-DETAILS:
-**Tier:** Ultimate
+{{< details >}}
+
+- Tier: Ultimate
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9002) in GitLab 17.5.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9002) in GitLab 17.5.
+{{< /history >}}
Use health status on epics to gain quick insight into project progress.
Health status helps you communicate and manage potential issues proactively.
@@ -509,7 +605,11 @@ To address risks to timely delivery of your planned work, incorporate a review o
#### Change health status of an epic
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -530,7 +630,11 @@ You can also set and clear health statuses using the `/health_status` and `/clea
### Add an issue to an epic
-> - Maximum number of child issues and epics [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/452111) to 5000 in GitLab 17.1.
+{{< history >}}
+
+- Maximum number of child issues and epics [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/452111) to 5000 in GitLab 17.1.
+
+{{< /history >}}
Add an existing issue to an epic, or create a new issue that's automatically
added to the epic.
@@ -539,7 +643,11 @@ The maximum number of direct child issues and epics is 5000.
#### Add an existing issue to an epic
-> - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+{{< history >}}
+
+- Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+
+{{< /history >}}
You can add existing issues to an epic, including issues in a project from a [different group hierarchy](_index.md#child-issues-from-different-group-hierarchies).
Newly added issues appear at the top of the list of issues in the **Child issues and epics** section.
@@ -573,7 +681,11 @@ If your administrator [enabled the new look for epics](epic_work_items.md), this
#### Create an issue from an epic
-> - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+{{< history >}}
+
+- Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+
+{{< /history >}}
Creating an issue from an epic enables you to maintain focus on the broader context of the epic
while dividing work into smaller parts.
@@ -606,7 +718,11 @@ If your administrator [enabled the new look for epics](epic_work_items.md), this
### Remove an issue from an epic
-> - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+{{< history >}}
+
+- Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+
+{{< /history >}}
You can remove issues from an epic when you're on the epic's details page.
After you remove an issue from an epic, the issue is no longer associated with this epic.
@@ -617,7 +733,7 @@ Prerequisites:
To remove an issue from an epic:
-1. Next to the issue you want to remove, select **Remove** (**{close}**).
+1. Next to the issue you want to remove, select **Remove** ({{< icon name="close" >}}).
The **Remove issue** warning appears.
1. Select **Remove**.
@@ -625,7 +741,11 @@ To remove an issue from an epic:
### Reorder issues assigned to an epic
-> - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+{{< history >}}
+
+- Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+
+{{< /history >}}
New issues show at the top of the list in the **Child issues and epics** section.
You can reorder the list of issues by dragging them.
@@ -647,11 +767,18 @@ If your administrator [enabled the new look for epics](epic_work_items.md), this
### Move issues between epics
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+- Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8.
+
+{{< /history >}}
New issues appear at the top of the list in the **Child issues and epics**
tab. You can move issues from one epic to another.
@@ -682,9 +809,12 @@ For more on epic templates, see [Epic Templates - Repeatable sets of issues](htt
## Multi-level child epics
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can add any epic that belongs to a group or subgroup of the parent epic's group.
New child epics appear at the top of the list of epics in the **Child issues and epics** section.
@@ -699,7 +829,11 @@ Epics can contain multiple nested child epics, up to a total of 7 levels deep.
### Add a parent epic to an epic
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 17.5.
+
+{{< /history >}}
To create a hierarchy of epics, add a parent epic to an existing epic.
This helps organize and track related work across multiple epics.
@@ -723,10 +857,14 @@ The parent epic is added.
### Child epics from other groups
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8502) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `child_epics_from_different_hierarchies`. Disabled by default.
-> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
-> - Cross-group child epics [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375622) in GitLab 15.9. Enabled by default.
-> - [Feature flag `child_epics_from_different_hierarchies`](https://gitlab.com/gitlab-org/gitlab/-/issues/382719) removed in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8502) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `child_epics_from_different_hierarchies`. Disabled by default.
+- Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
+- Cross-group child epics [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375622) in GitLab 15.9. Enabled by default.
+- [Feature flag `child_epics_from_different_hierarchies`](https://gitlab.com/gitlab-org/gitlab/-/issues/382719) removed in GitLab 15.10.
+
+{{< /history >}}
Add a child epic that belongs to a group that is different from the parent epic's group.
@@ -757,7 +895,11 @@ If your administrator [enabled the new look for epics](epic_work_items.md), this
### Add a child epic to an epic
-> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
+{{< history >}}
+
+- Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
+
+{{< /history >}}
Prerequisites:
@@ -798,7 +940,11 @@ If your administrator [enabled the new look for epics](epic_work_items.md), this
### Move child epics between epics
-> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
+{{< history >}}
+
+- Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
+
+{{< /history >}}
New child epics appear at the top of the list in the **Child issues and epics** section.
You can move child epics from one epic to another.
@@ -822,7 +968,11 @@ If your administrator [enabled the new look for epics](epic_work_items.md), this
### Reorder child epics assigned to an epic
-> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
+{{< history >}}
+
+- Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
+
+{{< /history >}}
New child epics appear at the top of the list in the **Child issues and epics** section.
You can reorder the list of child epics.
@@ -844,7 +994,11 @@ If your administrator [enabled the new look for epics](epic_work_items.md), this
### Remove a child epic from a parent epic
-> - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
+{{< history >}}
+
+- Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7.
+
+{{< /history >}}
Prerequisites:
@@ -852,6 +1006,6 @@ Prerequisites:
To remove a child epic from a parent epic:
-1. Select **Remove** (**{close}**) in the parent epic's list of epics.
+1. Select **Remove** ({{< icon name="close" >}}) in the parent epic's list of epics.
The **Remove epic** warning appears.
1. Select **Remove**.
diff --git a/doc/user/group/import/_index.md b/doc/user/group/import/_index.md
index b5fa9e7c5a1346f7eee28166fe51fd9193d47ddf..4391110e13e56d342f6e0b6710506e4f039eb413 100644
--- a/doc/user/group/import/_index.md
+++ b/doc/user/group/import/_index.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating GitLab by using direct transfer
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6.
-> - New application setting `bulk_import_enabled` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. `bulk_import` feature flag removed.
-> - `bulk_import_projects` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.10.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6.
+- New application setting `bulk_import_enabled` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. `bulk_import` feature flag removed.
+- `bulk_import_projects` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.10.
+
+{{< /history >}}
You can migrate GitLab groups:
@@ -54,10 +61,13 @@ Not all group and project resources are copied. See list of copied resources bel
After you start a migration, you should not make any changes to imported groups or projects
on the source instance because these changes might not be copied to the destination instance.
-WARNING:
+{{< alert type="warning" >}}
+
Importing groups with projects is in [beta](../../../policy/development_stages_support.md#beta). This feature is not
ready for production use.
+{{< /alert >}}
+
We invite you to leave your feedback about migrating by direct transfer in
[the feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495).
@@ -165,7 +175,11 @@ The GitLab UI can only migrate top-level groups. Using the API, you can also mig
## Limits
-> - Eight hour time limit on migrations [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/429867) in GitLab 16.7.
+{{< history >}}
+
+- Eight hour time limit on migrations [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/429867) in GitLab 16.7.
+
+{{< /history >}}
Hardcoded limits apply on migration by direct transfer.
diff --git a/doc/user/group/import/direct_transfer_migrations.md b/doc/user/group/import/direct_transfer_migrations.md
index 57def3bbbfb7303bd0082ff1fe1e371124ad08e3..6466cbd1567140711de392cda186dcc3c89aad4e 100644
--- a/doc/user/group/import/direct_transfer_migrations.md
+++ b/doc/user/group/import/direct_transfer_migrations.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrate groups and projects by using direct transfer
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To migrate GitLab groups and projects by using direct transfer, you:
@@ -23,7 +26,11 @@ If there are any problems, you can:
## Prerequisites
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
Before migrating by using direct transfer, see the following prerequisites.
@@ -73,14 +80,21 @@ GitLab 16.8.
## User contribution and membership mapping
-DETAILS:
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Offering: GitLab Self-Managed, GitLab Dedicated
-> - Mapping of shared and inherited shared members as direct members was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129017) in GitLab 16.3.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148220) in GitLab 16.11, shared and inherited shared members are no longer mapped as direct members if they are already shared or inherited shared members of the imported group or project.
-> - Full support for mapping inherited membership [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/458834) in GitLab 17.1.
-> - Removed from direct transfer on GitLab.com in GitLab 17.5 in favor of [the alternative](../../project/import/_index.md#user-contribution-and-membership-mapping).
-> - Removed as the default direct transfer method on GitLab Self-Managed and GitLab Dedicated in GitLab 17.7 in favor of [the alternative](../../project/import/_index.md#user-contribution-and-membership-mapping).
+{{< /details >}}
+
+{{< history >}}
+
+- Mapping of shared and inherited shared members as direct members was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129017) in GitLab 16.3.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148220) in GitLab 16.11, shared and inherited shared members are no longer mapped as direct members if they are already shared or inherited shared members of the imported group or project.
+- Full support for mapping inherited membership [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/458834) in GitLab 17.1.
+- Removed from direct transfer on GitLab.com in GitLab 17.5 in favor of [the alternative](../../project/import/_index.md#user-contribution-and-membership-mapping).
+- Removed as the default direct transfer method on GitLab Self-Managed and GitLab Dedicated in GitLab 17.7 in favor of [the alternative](../../project/import/_index.md#user-contribution-and-membership-mapping).
+
+{{< /history >}}
This method of user contribution and membership mapping is available for
GitLab Self-Managed when `importer_user_mapping` and `bulk_import_importer_user_mapping` are disabled.
@@ -103,9 +117,12 @@ has an existing membership in the destination namespace with a [higher role](../
the one being mapped, the membership is mapped as a direct membership instead. This ensures the member does not get
elevated permissions.
-NOTE:
+{{< alert type="note" >}}
+
There is a [known issue](_index.md#known-issues) affecting the mapping of shared memberships.
+{{< /alert >}}
+
### Configure users on destination instance
To ensure GitLab maps users and their contributions correctly between the source and destination instances:
@@ -130,18 +147,22 @@ a lot of user accounts to have public email addresses, see
On the destination GitLab instance, create the group you want to import to and connect the source GitLab instance:
1. Create either:
- - A new group. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**. Then select **Import group**.
+ - A new group. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**. Then select **Import group**.
- A new subgroup. On existing group's page, either:
- Select **New subgroup**.
- - On the left sidebar, at the top, select **Create new** (**{plus}**) and **New subgroup**. Then select the **import an existing group** link.
+ - On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New subgroup**. Then select the **import an existing group** link.
1. Enter the base URL of a GitLab instance.
1. Enter the [personal access token](../../profile/personal_access_tokens.md) for your source GitLab instance.
1. Select **Connect instance**.
## Select the groups and projects to import
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385689) in GitLab 15.8, option to import groups with or without projects.
-> - **Import user memberships** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/477734) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385689) in GitLab 15.8, option to import groups with or without projects.
+- **Import user memberships** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/477734) in GitLab 17.6.
+
+{{< /history >}}
After you have authorized access to the source GitLab instance, you are redirected to the GitLab group importer page. Here you can see a list of the top-level groups on the connected source instance where you have the Owner role.
@@ -154,12 +175,19 @@ If you do not want to import all user memberships from the source instance, ensu
1. The **Status** column shows the import status of each group. If you leave the page open, it updates in real-time.
1. After a group has been imported, select its GitLab path to open its GitLab URL.
-WARNING:
+{{< alert type="warning" >}}
+
Importing groups with projects is in [beta](../../../policy/development_stages_support.md#beta). This feature is not ready for production use.
+{{< /alert >}}
+
## Group import history
-> - **Partially completed** status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394727) in GitLab 16.7.
+{{< history >}}
+
+- **Partially completed** status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394727) in GitLab 16.7.
+
+{{< /history >}}
You can view all groups migrated by you by direct transfer listed on the group import history page. This list includes:
@@ -172,17 +200,21 @@ You can view all groups migrated by you by direct transfer listed on the group i
To view group import history:
1. Sign in to GitLab.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. Select **Import group**.
1. In the upper-right corner, select **History**.
1. If there are any errors for a particular import, select **Show errors** to see their details.
## Review results of the import
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429109) in GitLab 16.6 [with a flag](../../feature_flags.md) named `bulk_import_details_page`. Enabled by default.
-> - Feature flag `bulk_import_details_page` removed in GitLab 16.8.
-> - Details for partially completed and completed imports [added](https://gitlab.com/gitlab-org/gitlab/-/issues/437874) in GitLab 16.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443492) in GitLab 17.0, an **Imported** badge to indicate that designs, epics, issues, merge requests, notes (system notes and comments), snippets, and user profile activity were imported.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429109) in GitLab 16.6 [with a flag](../../feature_flags.md) named `bulk_import_details_page`. Enabled by default.
+- Feature flag `bulk_import_details_page` removed in GitLab 16.8.
+- Details for partially completed and completed imports [added](https://gitlab.com/gitlab-org/gitlab/-/issues/437874) in GitLab 16.9.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443492) in GitLab 17.0, an **Imported** badge to indicate that designs, epics, issues, merge requests, notes (system notes and comments), snippets, and user profile activity were imported.
+
+{{< /history >}}
To review the results of an import:
diff --git a/doc/user/group/import/migrated_items.md b/doc/user/group/import/migrated_items.md
index 653a3282d4a4aced643c50d16457b31819c868ab..97250031d92e3eac621a36fd61c2b4044ba928db 100644
--- a/doc/user/group/import/migrated_items.md
+++ b/doc/user/group/import/migrated_items.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Items migrated when using direct transfer
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Many items are migrated when using the direct transfer method, and some are excluded.
@@ -76,12 +79,19 @@ Some group items are excluded from migration because they:
## Migrated project items
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6.
-> - `bulk_import_projects` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.10.
-> - Project-only migrations using API [added](https://gitlab.com/gitlab-org/gitlab/-/issues/390515) in GitLab 15.11.
+{{< history >}}
+
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6.
+- `bulk_import_projects` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.10.
+- Project-only migrations using API [added](https://gitlab.com/gitlab-org/gitlab/-/issues/390515) in GitLab 15.11.
+
+{{< /history >}}
If you choose to migrate projects when you [select groups to migrate](direct_transfer_migrations.md#select-the-groups-and-projects-to-import),
project items are migrated with the projects.
@@ -221,9 +231,12 @@ Some project items are excluded from migration because they:
- Agents
- Merge request approval rules
- NOTE:
+ {{< alert type="note" >}}
+
Approval rules related to project settings are imported.
+ {{< /alert >}}
+
- Container registry
- Environments
- Feature flags
diff --git a/doc/user/group/import/troubleshooting.md b/doc/user/group/import/troubleshooting.md
index 8f0535ed728bd90202d544cd5bd1a29578f21a2c..2a1b3aa3d5cc2fbc4563d9d40ead1d63849cc5ec 100644
--- a/doc/user/group/import/troubleshooting.md
+++ b/doc/user/group/import/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting direct transfer migrations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In a [rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session),
you can find the failure or error messages for the group import attempt using:
diff --git a/doc/user/group/issues_analytics/_index.md b/doc/user/group/issues_analytics/_index.md
index ade1de490ce6323600bc8521f6965e673fd1eeb5..5c81b20cd99ca9848afe69cec349c3cd18ace20a 100644
--- a/doc/user/group/issues_analytics/_index.md
+++ b/doc/user/group/issues_analytics/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Issue analytics
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Issue analytics provide insights into the issues created each month in a group or project.
A bar chart illustrates the number of issues opened and closed each month.
@@ -48,13 +51,20 @@ You can also access issue analytics from the [Value Streams Dashboard](../../ana
### Enhanced issue analytics
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233905/) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `issues_completed_analytics_feature_flag`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/437542) in GitLab 16.8.
+- [Feature flag `issues_completed_analytics_feature_flag`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146766) removed in GitLab 16.10.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233905/) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `issues_completed_analytics_feature_flag`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/437542) in GitLab 16.8.
-> - [Feature flag `issues_completed_analytics_feature_flag`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146766) removed in GitLab 16.10.
+{{< /history >}}
Enhanced issue analytics display the additional metric `Issues closed`, which represents the total number of resolved issues in your group over a selected period.
You can use this metric to improve the overall turn-around time and value delivered to your customers.
diff --git a/doc/user/group/iterations/_index.md b/doc/user/group/iterations/_index.md
index f96c68305f86063776fffe2615740a566fd63263..07f422f24de5fae477663222a01649eeb77866e2 100644
--- a/doc/user/group/iterations/_index.md
+++ b/doc/user/group/iterations/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Iterations
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
An iteration in GitLab refers to a time-boxed workflow that groups issues to be worked on during
a specific period of time, usually lasting 1-3 weeks.
@@ -89,11 +92,15 @@ When you use iterations for rapid cycles:
## Iteration cadences
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1 [with a flag](../../../administration/feature_flags.md), named `iteration_cadences`. Disabled by default.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/354977) in GitLab 15.0: All scheduled iterations must start on the same day of the week as the cadence start day. Start date of cadence cannot be edited after the first iteration starts.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/367493) in GitLab 15.4: A new automation start date can be selected for cadence. Upcoming iterations are scheduled to start on the same day of the week as the changed start date. Iteration cadences can be manually managed by turning off the automatic scheduling feature.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.5. Feature flag `iteration_cadences` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1 [with a flag](../../../administration/feature_flags.md), named `iteration_cadences`. Disabled by default.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/354977) in GitLab 15.0: All scheduled iterations must start on the same day of the week as the cadence start day. Start date of cadence cannot be edited after the first iteration starts.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/367493) in GitLab 15.4: A new automation start date can be selected for cadence. Upcoming iterations are scheduled to start on the same day of the week as the changed start date. Iteration cadences can be manually managed by turning off the automatic scheduling feature.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.5. Feature flag `iteration_cadences` removed.
+
+{{< /history >}}
Iteration cadences are containers for iterations and can be used to automate iteration scheduling.
You can use them to automate creating iterations every 1, 2, 3, or 4 weeks. You can also
@@ -101,8 +108,12 @@ configure iteration cadences to automatically roll over incomplete issues to the
### Create an iteration cadence
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -139,13 +150,16 @@ To manually manage the created cadence, see [Create an iteration manually](#crea
To view all the iterations in a cadence, ordered by descending date, select that iteration cadence.
From there you can create a new iteration or select an iteration to get a more detailed view.
-NOTE:
+{{< alert type="note" >}}
+
If a project has issue tracking
[turned off](../../project/settings/_index.md#configure-project-features-and-permissions),
to view the iterations list, enter its URL. To do so, add: `/-/cadences` to your project or group URL.
For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/cadences`.
[Issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009) tracks improving this.
+{{< /alert >}}
+
### Edit an iteration cadence
Prerequisites:
@@ -156,7 +170,7 @@ To edit an iteration cadence:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Iterations**.
-1. To the right of the cadence you want to edit, select the vertical ellipsis (**{ellipsis_v}**) and
+1. To the right of the cadence you want to edit, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and
then select **Edit cadence**.
1. Edit the fields.
- When you use automatic scheduling and edit the **Automation start date** field,
@@ -172,7 +186,7 @@ To edit an iteration cadence:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Iterations**.
1. To the right of the cadence for which you want to turn on or off automatic scheduling, select the
- vertical ellipsis (**{ellipsis_v}**) and then select **Edit cadence**.
+ vertical ellipsis ({{< icon name="ellipsis_v" >}}) and then select **Edit cadence**.
1. Select or clear the **Enable automatic scheduling** checkbox.
1. If you're turning on automatic scheduling,
complete the required fields **Automation start date**, **Duration**, and **Upcoming iterations**.
@@ -209,8 +223,12 @@ to satisfy the requirement that there are at least two upcoming iterations sched
### Delete an iteration cadence
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -222,7 +240,7 @@ To delete an iteration cadence:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Iterations**.
-1. To the right of the cadence you want to delete, select the vertical ellipsis (**{ellipsis_v}**) and then select **Delete cadence**.
+1. To the right of the cadence you want to delete, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and then select **Delete cadence**.
1. Select **Delete cadence**.
### GitLab Automation Bot user
@@ -239,8 +257,12 @@ On GitLab.com, this is the `automation-bot1` user.
## Create an iteration manually
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
When an iteration cadence has automatic scheduling enabled, iterations are created on schedule.
If you disable that option, you can create iterations manually.
@@ -256,14 +278,18 @@ To create an iteration:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Iterations**.
1. To the right of the cadence in which you want create an iteration, select the vertical ellipsis
- (**{ellipsis_v}**) and then select **Add iteration**.
+ ({{< icon name="ellipsis_v" >}}) and then select **Add iteration**.
1. Complete the fields.
1. Select **Create iteration**. The iteration details page opens.
## Edit an iteration
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -274,15 +300,19 @@ To edit an iteration:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Iterations** and select an iteration cadence.
1. Select the iteration you want edit. The iteration details page opens.
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**) and then select **Edit**.
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and then select **Edit**.
1. Edit the fields:
- You can edit **Title**, **Start date**, and **Due date** only if [automatic scheduling is disabled](#turn-on-and-off-automatic-scheduling-for-an-iteration-cadence) for the iteration cadence.
1. Select **Save changes**.
## Delete an iteration
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -294,7 +324,7 @@ To delete an iteration:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Iterations** and select an iteration cadence.
1. Select the iteration you want edit. The iteration details page opens.
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**) and then select **Delete**.
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and then select **Delete**.
1. Select **Delete**.
## Iteration report
diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md
index 00b567595a0c28520852a553507e9cc147ba6a3d..8cd715d4bccb295c0ffffbc6777a02bf86cea8f5 100644
--- a/doc/user/group/manage.md
+++ b/doc/user/group/manage.md
@@ -7,7 +7,8 @@ title: Manage groups
Use groups to manage one or more related projects at the same time.
-NOTE:
+{{< alert type="note" >}}
+
On GitLab Self-Managed, if you want to see an overview of your entire organization, you should create one top-level group.
For more information about efforts to create an organization view of all groups,
[see epic 9266](https://gitlab.com/groups/gitlab-org/-/epics/9266).
@@ -17,6 +18,8 @@ A top-level group offers insights in your entire organization through a complete
[compliance center](../compliance/compliance_center/_index.md), and
[value stream analytics](value_stream_analytics/_index.md).
+{{< /alert >}}
+
## Add a group README
You can add a README file to provide information about your team and invite users to contribute to your projects.
@@ -72,15 +75,20 @@ To change your group path (group URL):
1. Under **Change group URL**, enter a new name.
1. Select **Change group URL**.
-WARNING:
+{{< alert type="warning" >}}
+
It is not possible to rename a namespace if it contains a
project with [Container Registry](../packages/container_registry/_index.md) tags,
because the project cannot be moved.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
To ensure that groups with thousands of subgroups get processed correctly, you should test the path change in a test environment.
Consider increasing the [Puma worker timeout](../../administration/operations/puma.md#change-the-worker-timeout) temporarily.
For more information about our solution to mitigate this timeout risk, see [issue 432065](https://gitlab.com/gitlab-org/gitlab/-/issues/432065).
+{{< /alert >}}
## Change the default branch protection of a group
@@ -147,8 +155,12 @@ To disable email notifications:
### Disable diff previews in email notifications
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24733) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `diff_preview_in_email`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/382055) in GitLab 17.1. Feature flag `diff_preview_in_email` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24733) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `diff_preview_in_email`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/382055) in GitLab 17.1. Feature flag `diff_preview_in_email` removed.
+
+{{< /history >}}
When you comment on code in a merge request, GitLab
includes a few lines of the diff in the email notification to participants.
@@ -170,11 +182,18 @@ To disable diff previews for all projects in a group:
## Expiry emails for group and project access tokens
-> - Notifications to inherited group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+{{< history >}}
+
+- Notifications to inherited group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of emails to inherited project and group members is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
The following group and project members receive notification emails about access tokens that are expiring soon:
- For group access tokens:
@@ -200,11 +219,18 @@ For more information, see:
## Add additional webhook triggers for group access token expiration
-> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) 60 day and 30 days triggers to project and group access tokens webhooks in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+{{< history >}}
+
+- [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) 60 day and 30 days triggers to project and group access tokens webhooks in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
GitLab sends multiple [expiry emails](../group/settings/group_access_tokens.md#group-access-token-expiry-emails) and triggers a related [webhook](../project/integrations/webhook_events.md#project-and-group-access-token-events) before a group token expires. By default, GitLab only triggers these webhooks 7 days before the token expires. When this feature is enabled, GitLab also can trigger these webhooks 60 days and 30 days before the token expires.
To enable additional triggers for these webhooks:
@@ -235,9 +261,12 @@ To disable group mentions:
## Export members as CSV
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can export a list of members in a group or subgroup as a CSV.
@@ -252,12 +281,19 @@ For members with `Minimal Access` in the selected group, their `Max Role` and `S
## Turn on restricted access
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442718) in GitLab 17.5.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442718) in GitLab 17.5.
+
+{{< /history >}}
Use restricted access to prevent overage fees.
Overage fees occur when you exceed the number of seats in your subscription,
@@ -300,8 +336,12 @@ Additionally, restricted access might block the standard non-overage flows:
## User cap for groups
-> - [Enabled on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/9263) in GitLab 16.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/421693) in GitLab 17.1 Feature flag `saas_user_caps` removed.
+{{< history >}}
+
+- [Enabled on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/9263) in GitLab 16.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/421693) in GitLab 17.1 Feature flag `saas_user_caps` removed.
+
+{{< /history >}}
For more information about user caps for GitLab Self-Managed, see [User cap](../../administration/settings/sign_up_restrictions.md#user-cap).
@@ -378,9 +418,12 @@ GitLab.com Ultimate has a [known issue](https://gitlab.com/gitlab-org/gitlab/-/i
## Group file templates
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use group file templates to share a set of templates for common file
types with every project in a group. It is analogous to the
@@ -404,9 +447,12 @@ For more information, see [group-level project templates](custom_project_templat
### Enable group file template
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To enable group file templates:
@@ -418,12 +464,19 @@ To enable group file templates:
## Group merge checks settings
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372040) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) name `support_group_level_merge_checks_setting`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142708) in GitLab 16.9. Feature flag `support_group_level_merge_checks_setting` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372040) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) name `support_group_level_merge_checks_setting`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142708) in GitLab 16.9. Feature flag `support_group_level_merge_checks_setting` removed.
+
+{{< /history >}}
Group Owners can set up merge request checks on a top-level group, which apply to all subgroups and projects.
@@ -488,9 +541,12 @@ To enable this setting:
## Group merge request approval settings
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Group approval settings manage [project merge request approval settings](../project/merge_requests/approvals/settings.md)
for all projects in a top-level group. These settings [cascade to all projects](../project/merge_requests/approvals/settings.md#cascade-settings-from-the-instance-or-top-level-group)
@@ -510,9 +566,12 @@ for the ability to set merge request approval rules for groups is tracked in
## Group activity analytics
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
For a group, you can view how many merge requests, issues, and members were created in the last 90 days.
@@ -526,4 +585,4 @@ You can view the most recent actions taken in a group, either in your browser or
1. Select **Manage > Activity**.
To view the activity feed in Atom format, select the
-**RSS** (**{rss}**) icon.
+**RSS** ({{< icon name="rss" >}}) icon.
diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md
index ba3bbb06bbc5289d3a0cabdcdb4da64c2f6d4396..0dabcdbedcb5b95935e748b842d2ebab0b102cf8 100644
--- a/doc/user/group/moderate_users.md
+++ b/doc/user/group/moderate_users.md
@@ -7,16 +7,26 @@ title: Moderate users
If you are assigned the Owner role for a group, you can [approve](manage.md#user-cap-for-groups), ban, or automatically remove dormant members.
-NOTE:
+{{< alert type="note" >}}
+
This topic is specifically related to user moderation in groups. For information related to GitLab Self-Managed, see the [administration documentation](../../administration/moderate_users.md).
+{{< /alert >}}
+
## Ban and unban users
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default.
+{{< /history >}}
A group Owner can moderate user access by banning and unbanning users.
You should ban a user when you want to block them from the group.
@@ -41,7 +51,7 @@ To manually ban a user:
1. Go to the top-level group.
1. On the left sidebar, select **Manage > Members**.
-1. Next to the member you want to ban, select the vertical ellipsis (**{ellipsis_v}**).
+1. Next to the member you want to ban, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. From the dropdown list, select **Ban member**.
### Unban a user
@@ -64,19 +74,25 @@ To unban a user:
## Automatically remove dormant members
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
-**Status:** Beta
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+- Status: Beta
+
+{{< /details >}}
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461339) in GitLab 17.1 [with a flag](../../administration/feature_flags.md) named `group_remove_dormant_members`. Disabled by default.
> [Released](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178851) as a [beta](../../policy/development_stages_support.md#beta) feature in GitLab 17.9.
-FLAG:
+{{< alert type="flag" >}}
+
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Prerequisites:
- You must have the Owner role for the group.
@@ -88,9 +104,12 @@ The following actions count as activity:
- Visiting pages in GitLab, such as dashboards, projects, issues, merge requests, or settings.
- Using the REST or GraphQL API in the scope of the group.
-NOTE:
+{{< alert type="note" >}}
+
Activity has not been recorded for members added before 2025-01-22. These members will not be removed until 2025-04-22, even if they have been dormant for over 90 days.
+{{< /alert >}}
+
To turn on automatic dormant member removal:
1. On the left sidebar, select **Search or go to** and find your group.
diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md
index d4ad3cecc7ca560f5412440cd1d83a89f13a247a..1589e96ea01558af2c2e653a9652c51450269430 100644
--- a/doc/user/group/reporting/git_abuse_rate_limit.md
+++ b/doc/user/group/reporting/git_abuse_rate_limit.md
@@ -5,16 +5,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Git abuse rate limit
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
This is the group-level documentation. For self-managed instances, see the [administration documentation](../../../administration/reporting/git_abuse_rate_limit.md).
Git abuse rate limiting is a feature to automatically ban users who download, clone, pull, fetch, or fork more than a specified number of repositories of a group in a given time frame. Banned users cannot access the top-level group or any of its non-public subgroups through HTTP or SSH. The rate limit also applies to users who authenticate with [personal](../../profile/personal_access_tokens.md) or [group access tokens](../settings/group_access_tokens.md), as well as [CI/CD job tokens](../../../ci/jobs/ci_job_token.md). Access to unrelated groups is unaffected.
diff --git a/doc/user/group/repositories_analytics/_index.md b/doc/user/group/repositories_analytics/_index.md
index e31c8ef5a0ef030322cc15a7c8faf33267d73f99..8e01970ef7a28941c8d93860ab741d98c122de1b 100644
--- a/doc/user/group/repositories_analytics/_index.md
+++ b/doc/user/group/repositories_analytics/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Repository analytics for groups
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Repositories analytics for groups provides information about test coverage for all projects in a group. An
[issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/273527) to also extend support for all projects in
@@ -62,9 +65,12 @@ For each day that a coverage report was generated by a job in a project's pipeli
If the project's code coverage was calculated more than once in a day, the last value from that day is used.
-NOTE:
+{{< alert type="note" >}}
+
Group code coverage data is taken from the configured [default branch](../../project/repository/branches/default.md).
+{{< /alert >}}
+
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/user/group/roadmap/_index.md b/doc/user/group/roadmap/_index.md
index 8164fdd33d51bbec685fd204c19293c598ee618e..8925fe5da807e50c24b9d839250ccb5f05da1af6 100644
--- a/doc/user/group/roadmap/_index.md
+++ b/doc/user/group/roadmap/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Roadmap
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Epics in a group containing a start date or due date can be visualized in a form
of a timeline.
@@ -39,12 +42,12 @@ When you hover over an epic bar, a popover appears with the epic's title, start
weight completed.
You can expand epics that contain child epics to show their child epics in the roadmap.
-You can select the chevron (**{chevron-down}**) next to the epic title to expand and collapse the
+You can select the chevron ({{< icon name="chevron-down" >}}) next to the epic title to expand and collapse the
child epics.
On top of the milestone bars, you can see their title. When you point to a
milestone bar or title, a popover appears with its title, start date, and due
-date. You can also select the chevron (**{chevron-down}**) next to the **Milestones**
+date. You can also select the chevron ({{< icon name="chevron-down" >}}) next to the **Milestones**
heading to toggle the list of the milestone bars.
@@ -53,12 +56,19 @@ From an epic, you can also [view the roadmap filtered to this epic's descendants
## Sort and filter the roadmap
-> - Filtering by group was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385191) in GitLab 15.9.
-> - Sorting by title, created date, and last updated date [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460492) in GitLab 17.0.
+{{< history >}}
+
+- Filtering by group was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385191) in GitLab 15.9.
+- Sorting by title, created date, and last updated date [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460492) in GitLab 17.0.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
Filtering roadmaps by milestone might not be available to you. Be sure to review this section's history for details.
+{{< /alert >}}
+
When you want to explore a roadmap, there are several ways to make it easier by sorting epics or
filtering them by what's important for you.
@@ -102,7 +112,11 @@ In the future, you can quickly load the filtered roadmap using the bookmark.
### Roadmap settings
-> - Labels visible on roadmaps [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385231) in GitLab 15.9.
+{{< history >}}
+
+- Labels visible on roadmaps [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385231) in GitLab 15.9.
+
+{{< /history >}}
When you enable the roadmap settings sidebar, you can use it to refine epics shown in the roadmap.
@@ -121,7 +135,11 @@ shared using URL parameters.
## Timeline duration
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/198062) from GitLab Ultimate to GitLab Premium in 12.9.
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/198062) from GitLab Ultimate to GitLab Premium in 12.9.
+
+{{< /history >}}
### Date range presets
@@ -177,15 +195,22 @@ due dates.
## Blocked epics
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33587) in GitLab 15.5: View blocking epics when hovering over the "blocked" icon.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33587) in GitLab 15.5: View blocking epics when hovering over the "blocked" icon.
+{{< /history >}}
If an epic is [blocked by another epic](../epics/linked_epics.md#blocking-epics), an icon appears next to its title to indicate its blocked status.
-When you hover over the blocked icon (**{entity-blocked}**), a detailed information popover is displayed.
+When you hover over the blocked icon ({{< icon name="entity-blocked" >}}), a detailed information popover is displayed.
diff --git a/doc/user/group/saml_sso/_index.md b/doc/user/group/saml_sso/_index.md
index 0912251271c44dc53025faa131cb08c0b7f7cf2d..5413652eec189ccb73227d6304382ce0637a5d96 100644
--- a/doc/user/group/saml_sso/_index.md
+++ b/doc/user/group/saml_sso/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: SAML SSO for GitLab.com groups
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Users can sign in to GitLab through their SAML identity provider.
@@ -181,9 +184,12 @@ For more information, see the [OneLogin configuration example](example_saml_conf
### Configure assertions
-NOTE:
+{{< alert type="note" >}}
+
These attributes are case-insensitive.
+{{< /alert >}}
+
At minimum, you must configure the following assertions:
1. [NameID](#manage-user-saml-identity).
@@ -238,7 +244,11 @@ If the **NameID** is configured with the email address, [change the **NameID** f
## Configure GitLab
-> - Ability to set a custom role as the default membership role [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417285) in GitLab 16.7.
+{{< history >}}
+
+- Ability to set a custom role as the default membership role [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417285) in GitLab 16.7.
+
+{{< /history >}}
After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication:
@@ -268,9 +278,12 @@ After you set up your identity provider to work with GitLab, you must configure
For more information, see the [SSO enforcement documentation](#sso-enforcement).
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
The certificate [fingerprint algorithm](../../../integration/saml.md#configure-saml-on-your-idp) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#google-workspace)), use a secure signature algorithm.
+{{< /alert >}}
+
If you are having issues configuring GitLab, see the [troubleshooting documentation](#troubleshooting).
## User access and management
@@ -288,11 +301,18 @@ When a user tries to sign in with Group SSO, GitLab attempts to find or create a
### Link SAML to your existing GitLab.com account
-> - **Remember me** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121569) in GitLab 15.7.
+{{< history >}}
+
+- **Remember me** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121569) in GitLab 15.7.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
If the user is an [enterprise user](../../enterprise_user/_index.md) of that group, the following steps do not apply. The enterprise user must instead [sign in with a SAML account that has the same email as the GitLab account](#returning-users-automatic-identity-relinking). This allows GitLab to link the SAML account to the existing account.
+{{< /alert >}}
+
To link SAML to your existing GitLab.com account:
1. Sign in to your GitLab.com account. [Reset your password](https://gitlab.com/users/password/new)
@@ -322,7 +342,11 @@ are then redirected to sign in through the identity provider.
### Manage user SAML identity
-> - Update of SAML identities using the SAML API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
+{{< history >}}
+
+- Update of SAML identities using the SAML API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
+
+{{< /history >}}
GitLab.com uses the SAML **NameID** to identify users. The **NameID** is:
@@ -357,16 +381,23 @@ Alternatively, ask the users to reconnect their SAML account.
1. Ask relevant users to [unlink their account from the group](#unlink-accounts).
1. Ask relevant users to [link their account to the new SAML app](#link-saml-to-your-existing-gitlabcom-account).
-WARNING:
+{{< alert type="warning" >}}
+
After users have signed into GitLab using SSO SAML, changing the **NameID** value
breaks the configuration and could lock users out of the GitLab group.
+{{< /alert >}}
+
For more information on the recommended value and format for specific identity
providers, see [set up your identity provider](#set-up-your-identity-provider).
### Configure enterprise user settings from SAML response
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/412898) to configure only enterprise user settings in GitLab 16.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/412898) to configure only enterprise user settings in GitLab 16.7.
+
+{{< /history >}}
GitLab allows setting certain user attributes based on values from the SAML response.
An existing user's attributes are updated from the SAML response values if that
@@ -411,7 +442,11 @@ convert the information to XML. An example SAML response is shown here.
### Bypass user email confirmation with verified domains
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4.
+
+{{< /history >}}
By default, users provisioned with SAML or SCIM are sent a verification email to verify their identity. Instead, you can
[configure GitLab with a custom domain](../../enterprise_user/_index.md#set-up-a-verified-domain) and GitLab
@@ -423,7 +458,11 @@ automatically confirms user accounts. Users still receive an
### Disable password authentication for enterprise users
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373718) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373718) in GitLab 17.4.
+
+{{< /history >}}
Prerequisites:
@@ -467,10 +506,13 @@ Users can unlink SAML for a group from their profile page. This can be helpful i
- You no longer want a group to be able to sign you in to GitLab.com.
- Your SAML **NameID** has changed and so GitLab can no longer find your user.
-WARNING:
+{{< alert type="warning" >}}
+
Unlinking an account removes all roles assigned to that user in the group.
If a user re-links their account, roles need to be reassigned.
+{{< /alert >}}
+
Groups require at least one owner. If your account is the only owner in the
group, you are not allowed to unlink the account. In that case, set up another user as a
group owner, and then you can unlink the account.
@@ -484,9 +526,13 @@ For example, to unlink the `MyOrg` account:
## SSO enforcement
-> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/215155) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `transparent_sso_enforcement` to include transparent enforcement even when SSO enforcement is not enabled. Disabled on GitLab.com.
-> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) in GitLab 15.8 by enabling transparent SSO by default on GitLab.com.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389562) in GitLab 15.10. Feature flag `transparent_sso_enforcement` removed.
+{{< history >}}
+
+- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/215155) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `transparent_sso_enforcement` to include transparent enforcement even when SSO enforcement is not enabled. Disabled on GitLab.com.
+- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) in GitLab 15.8 by enabling transparent SSO by default on GitLab.com.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389562) in GitLab 15.10. Feature flag `transparent_sso_enforcement` removed.
+
+{{< /history >}}
On GitLab.com, SSO is enforced:
diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md
index afb2300a904b79114eb5fb17152f4b60ca71b464..f775eca24a8dce56b9bae5ef6f821efd39d4a811 100644
--- a/doc/user/group/saml_sso/example_saml_config.md
+++ b/doc/user/group/saml_sso/example_saml_config.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Example group SAML and SCIM configurations
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
These are notes and screenshots regarding Group SAML and SCIM that the GitLab Support Team sometimes uses while troubleshooting, but which do not fit into the official documentation. GitLab is making this public, so that anyone can make use of the Support team's collected knowledge.
@@ -26,9 +29,12 @@ This section includes relevant screenshots of the following example configuratio
- [Okta](#okta)
- [OneLogin](#onelogin)
-WARNING:
+{{< alert type="warning" >}}
+
These screenshots are updated only as needed by GitLab Support. They are **not** official documentation.
+{{< /alert >}}
+
If you are currently having an issue with GitLab, you may want to check your [support options](https://about.gitlab.com/support/).
## Azure Active Directory
@@ -79,10 +85,13 @@ If available, you can add user-friendly group names instead. When setting up Azu
### IdP links and certificate
-NOTE:
+{{< alert type="note" >}}
+
Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint required by GitLab for configuring SAML, download the certificate and calculate the SHA1 certificate
fingerprint.
+{{< /alert >}}
+
## Okta
diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md
index d10d59b8dd419af39de070c03239f3db40252706..7449365ca91295cc66e5fece51403c8fbd6c4a4a 100644
--- a/doc/user/group/saml_sso/group_sync.md
+++ b/doc/user/group/saml_sso/group_sync.md
@@ -5,19 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: SAML Group Sync
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363084) for GitLab Self-Managed instances in GitLab 15.1.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363084) for GitLab Self-Managed instances in GitLab 15.1.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
Adding or changing Group Sync configuration can remove users from the mapped GitLab group.
Removal happens if there is any mismatch between the group names and the list of `groups` in the SAML response.
Before making changes, ensure either the SAML response includes the `groups` attribute
and the `AttributeValue` value matches the **SAML Group Name** in GitLab,
or that all groups are removed from GitLab to disable Group Sync.
+{{< /alert >}}
+
SAML group sync allows users to be assigned to pre-existing GitLab groups with specific permissions based on the user's group assignment in the SAML identity provider (IdP). This feature allows you to create a many-to-many mapping between SAML IdP groups and GitLab groups. For example, if the user `@amelia` is assigned to the `security` group in the SAML IdP, SAML group sync allows you to assign `@amelia` to the `security-gitlab` and `vulnerability` GitLab groups with `maintainer` and `reporter` permissions, respectively. SAML group sync does not create groups. You [create groups separately](../_index.md#create-a-group), and then create the mapping.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
@@ -57,11 +67,18 @@ To link the SAML groups:
### GitLab Duo seat assignment
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/480766) for GitLab.com in GitLab 17.8 [with a flag](../../../administration/feature_flags.md) named `saml_groups_duo_pro_add_on_assignment`. Disabled by default.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/480766) for GitLab.com in GitLab 17.8 [with a flag](../../../administration/feature_flags.md) named `saml_groups_duo_pro_add_on_assignment`. Disabled by default.
+
+{{< /history >}}
Prerequisites:
@@ -125,19 +142,29 @@ Users granted:
### Use the API
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.
+
+{{< /history >}}
You can use the GitLab API to [list, add, and delete](../../../api/saml.md#saml-group-links) SAML group links.
## Configure SAML Group Sync
-NOTE:
+{{< alert type="note" >}}
+
You must include the SAML configuration block on all Sidekiq nodes in addition to Rails application nodes if you use SAML Group Sync and have multiple GitLab nodes, for example in a distributed or highly available architecture.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
To prevent users being accidentally removed from the GitLab group, follow these instructions closely before
enabling Group Sync in GitLab.
+{{< /alert >}}
+
To configure SAML Group Sync for GitLab Self-Managed:
1. Configure the [SAML OmniAuth Provider](../../../integration/saml.md).
@@ -165,10 +192,13 @@ To configure SAML Group Sync for **GitLab.com instances**:
1. See [SAML SSO for GitLab.com groups](_index.md).
1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`.
-NOTE:
+{{< alert type="note" >}}
+
The value for `Groups` or `groups` in the SAML response may be either the group name or an ID.
For example, Azure AD sends the Azure Group Object ID instead of the name. Use the ID value when configuring [SAML Group Links](#configure-saml-group-links).
+{{< /alert >}}
+
```xml
<saml:AttributeStatement>
<saml:Attribute Name="Groups">
@@ -187,11 +217,18 @@ example configurations for [Azure AD](example_saml_config.md#group-sync) and [Ok
## Microsoft Azure Active Directory integration
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10507) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10507) in GitLab 16.3.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
Microsoft has [announced](https://azure.microsoft.com/en-us/updates/azure-ad-is-becoming-microsoft-entra-id/) that Azure Active Directory (AD) is being renamed to Entra ID.
+{{< /alert >}}
+
Azure AD sends up to 150 groups in the groups claim. When users are members of more than 150 groups Azure AD sends a
group overage claim attribute in the SAML response. Then group memberships must be obtained using the Microsoft Graph API.
@@ -266,11 +303,18 @@ Then the GitLab Group membership is updated according to SAML Group Links.
## Global SAML group memberships lock
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386390) in GitLab 15.10.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386390) in GitLab 15.10.
+
+{{< /history >}}
GitLab administrators can use the global SAML group memberships lock to prevent group members from inviting new members to subgroups that have their membership synchronized with SAML Group Links.
@@ -283,10 +327,13 @@ When global group memberships lock is enabled:
- Users cannot:
- Share a project with other groups.
- NOTE:
+ {{< alert type="note" >}}
+
You cannot set groups or subgroups as [Code Owners](../../project/codeowners/_index.md).
The Code Owners feature requires direct group memberships, which are not possible when this lock is enabled.
+ {{< /alert >}}
+
- Invite members to a project created in a group.
To enable global group memberships lock:
diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md
index 57c8777c4eee97882438b6d71e114f7744d92f5c..0caf791d58b91752a05332fa5c497b26c2c95c89 100644
--- a/doc/user/group/saml_sso/scim_setup.md
+++ b/doc/user/group/saml_sso/scim_setup.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure SCIM for GitLab.com groups
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically:
@@ -46,12 +49,19 @@ You can configure one of the following as an identity provider:
- [Azure Active Directory](#configure-microsoft-entra-id-formerly-azure-active-directory).
- [Okta](#configure-okta).
-NOTE:
+{{< alert type="note" >}}
+
Other providers can work with GitLab but they have not been tested and are not supported. You should contact the provider for support. GitLab support can assist by reviewing related log entries.
+{{< /alert >}}
+
### Configure Microsoft Entra ID (formerly Azure Active Directory)
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143146) to Microsoft Entra ID terminology in GitLab 16.10.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143146) to Microsoft Entra ID terminology in GitLab 16.10.
+
+{{< /history >}}
Prerequisites:
@@ -62,10 +72,13 @@ The SAML application created during [single sign-on](_index.md) set up for
[Azure Active Directory](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/view-applications-portal)
must be set up for SCIM. For an example, see [example configuration](example_saml_config.md#scim-mapping).
-NOTE:
+{{< alert type="note" >}}
+
You must configure SCIM provisioning exactly as detailed in the following instructions. If misconfigured, you will encounter issues with user provisioning
and sign in, which require a lot of effort to resolve. If you have any trouble or questions with any step, contact GitLab support.
+{{< /alert >}}
+
To configure Microsoft Entra ID for SCIM:
1. In your app, go to the **Provisioning** tab and select **Get started**.
@@ -88,8 +101,11 @@ Under the **Mappings** section, first provision the groups:
GitLab. Leaving group provisioning enabled does not break the SCIM user provisioning, but it causes errors in the
Entra ID SCIM provisioning log that may be confusing and misleading.
- NOTE:
- Even when **Provision Microsoft Entra ID Groups** is disabled, the mappings section may display "Enabled: Yes". This behavior is a display bug that you can safely ignore.
+ {{< alert type="note" >}}
+
+Even when **Provision Microsoft Entra ID Groups** is disabled, the mappings section may display "Enabled: Yes". This behavior is a display bug that you can safely ignore.
+
+ {{< /alert >}}
1. Select **Save**.
@@ -125,16 +141,22 @@ Under the **Settings** section:
After you have configured the mappings and the settings, return to the app overview page and select **Start provisioning** to start automatic SCIM provisioning of users in GitLab.
-WARNING:
+{{< alert type="warning" >}}
+
Once synchronized, changing the field mapped to `id` and `externalId` may cause errors. These include
provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group.
+{{< /alert >}}
+
#### Configure attribute mappings
-NOTE:
+{{< alert type="note" >}}
+
While Microsoft transitions from Azure Active Directory to Entra ID naming schemes, you might notice inconsistencies in
your user interface. If you're having trouble, you can view an older version of this document or contact GitLab Support.
+{{< /alert >}}
+
While [configuring Entra ID for SCIM](#configure-microsoft-entra-id-formerly-azure-active-directory), you configure
attribute mappings. For an example, see [example configuration](example_saml_config.md#scim-mapping).
@@ -278,9 +300,12 @@ the user's membership is revoked and they lose access.
When you enable SCIM, this does not automatically remove existing users who do
not have a SAML identity.
-NOTE:
+{{< alert type="note" >}}
+
Deprovisioning does not delete the GitLab user account.
+{{< /alert >}}
+
```mermaid
%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
@@ -294,8 +319,12 @@ accDescr: How removing users from your SCIM app removes them from GitLab groups.
### Reactivate access
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379149) in GitLab 16.0 [with a flag](../../feature_flags.md) named `skip_saml_identity_destroy_during_scim_deprovision`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121226) in GitLab 16.4. Feature flag `skip_saml_identity_destroy_during_scim_deprovision` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379149) in GitLab 16.0 [with a flag](../../feature_flags.md) named `skip_saml_identity_destroy_during_scim_deprovision`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121226) in GitLab 16.4. Feature flag `skip_saml_identity_destroy_during_scim_deprovision` removed.
+
+{{< /history >}}
After a user is removed or deactivated through SCIM, you can reactivate that user by
adding them to the SCIM identity provider.
diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md
index b4b005c8d2142bf7660a1b772774072765219770..f65d3e93667b18108c713802658312374aabc06c 100644
--- a/doc/user/group/saml_sso/troubleshooting.md
+++ b/doc/user/group/saml_sso/troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting SAML
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page contains possible solutions for problems you might encounter when using:
@@ -74,9 +77,12 @@ Regardless of what browser you use, the process is similar to the following:
## Search Rails logs for a SAML sign-in
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can find detailed information about a SAML sign-in in the [`audit_json.log` file](../../../administration/logs/_index.md#audit_jsonlog).
@@ -340,9 +346,12 @@ initiated by the service provider and not only the identity provider.
### Message: `There is already a GitLab account associated with this email address.`
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
A user can see this message when they are trying to [manually link SAML to their existing GitLab.com account](_index.md#link-saml-to-your-existing-gitlabcom-account):
@@ -359,9 +368,12 @@ to [reset their password](https://gitlab.com/users/password/new) if both:
### Message: "SAML Name ID and email address do not match your user account"
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Users might get an error that states "SAML Name ID and email address do not match your user account. Contact an administrator."
This means:
@@ -406,9 +418,12 @@ For GitLab.com, alternatively, when users need to [link SAML to their existing G
### Users receive a 404
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
If the user receives a `404` after signing in successfully, check if you have IP restrictions configured. IP restriction settings are configured:
@@ -461,9 +476,12 @@ If a subset of users are receiving a `404` after signing in to the IdP, first ve
### 500 error after login
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you see a "500 error" in GitLab when you are redirected back from the SAML
sign-in page, this could indicate that:
@@ -475,9 +493,12 @@ sign-in page, this could indicate that:
### 422 error after login
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you see a "422 error" in GitLab when you are redirected from the SAML
sign-in page, you might have an incorrectly configured Assertion Consumer
@@ -505,9 +526,12 @@ To implement this workaround:
### User is blocked when signing in through SAML
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The following are the most likely reasons that a user is blocked when signing in through SAML:
@@ -524,9 +548,12 @@ Pay particular attention to the following 403 errors:
## Message: "The member's email address is not linked to a SAML account"
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
This error appears when you try to invite a user to a GitLab.com group (or subgroup or project within a group) that has [SAML SSO enforcement](_index.md#sso-enforcement) enabled.
diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md
index 3979d2c49be7aea98501ffb1ef49da08a8d200d8..6db2b1592186d6a1993a20aeccad17c8b1046d8b 100644
--- a/doc/user/group/saml_sso/troubleshooting_scim.md
+++ b/doc/user/group/saml_sso/troubleshooting_scim.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting SCIM
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This section contains possible solutions for problems you might encounter.
@@ -82,11 +85,14 @@ To change the identifier values to match, you can do one of the following:
section.
- Unlink all users simultaneously by removing all users from the SCIM app while provisioning is turned on.
- WARNING:
+ {{< alert type="warning" >}}
+
This resets all users' roles in the top-level group and subgroups to the [configured default membership role](_index.md#configure-gitlab).
- Use the [SAML API](../../../api/saml.md) or [SCIM API](../../../api/scim.md) to manually correct the `extern_uid` stored for users to match the SAML
`NameId` or SCIM `externalId`.
+ {{< /alert >}}
+
You must not:
- Update these to incorrect values because this causes users to be unable to sign in.
@@ -107,9 +113,12 @@ When the SCIM app changes:
## SCIM app returns `"User has already been taken","status":409` error
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
Changing the SAML or SCIM configuration or provider can cause the following problems:
@@ -143,9 +152,12 @@ To resolve this issue, you can do either of the following:
## Search Rails logs for SCIM requests
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
GitLab.com administrators can search for SCIM requests in the `api_json.log` using the `pubsub-rails-inf-gprd-*` index in
[Kibana](https://handbook.gitlab.com/handbook/support/workflows/kibana/#using-kibana). Use the following filters based
diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md
index 096548b414a71c961b9c91ebc252595028568406..ea51c0682e063c786cb2215ee0263332f4968115 100644
--- a/doc/user/group/settings/group_access_tokens.md
+++ b/doc/user/group/settings/group_access_tokens.md
@@ -1,13 +1,16 @@
---
stage: Software Supply Chain Security
group: Authentication
-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"
+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
title: Group access tokens
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With group access tokens, you can use a single token to:
@@ -43,18 +46,28 @@ configured for personal access tokens.
## Create a group access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days and default role of Guest is populated in the UI.
-> - Ability to create non-expiring group access tokens [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0.
-> - Maximum allowable lifetime limit [extended to 400 days](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) in GitLab 17.6 [with a flag](../../../administration/feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
-> - Group access token description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443819) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days and default role of Guest is populated in the UI.
+- Ability to create non-expiring group access tokens [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0.
+- Maximum allowable lifetime limit [extended to 400 days](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) in GitLab 17.6 [with a flag](../../../administration/feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+- Group access token description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443819) in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the extended maximum allowable lifetime limit is controlled by a feature flag.
For more information, see the history.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The ability to create group access tokens without an expiry date was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0. For more information on expiry dates added to existing tokens, see the documentation on [access token expiration](#access-token-expiration).
+{{< /alert >}}
+
### With the UI
To create a group access token:
@@ -76,11 +89,14 @@ To create a group access token:
A group access token is displayed. Save the group access token somewhere safe. After you leave or refresh the page, you can't view it again.
-WARNING:
+{{< alert type="warning" >}}
+
Group access tokens are treated as [internal users](../../../administration/internal_users.md).
If an internal user creates a group access token, that token is able to access
all projects that have visibility level set to [Internal](../../public_access.md).
+{{< /alert >}}
+
### With the Rails console
If you are an administrator, you can create group access tokens in the Rails console:
@@ -125,8 +141,12 @@ If you are an administrator, you can create group access tokens in the Rails con
## Revoke or rotate a group access token
-> - Ability to view expired and revoked tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `retain_resource_access_token_user_after_revoke`. Disabled by default.
-> - Ability to view expired and revoked tokens limited to 30 days and [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/471683) in GitLab 17.9. Feature flag `retain_resource_access_token_user_after_revoke` removed.
+{{< history >}}
+
+- Ability to view expired and revoked tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `retain_resource_access_token_user_after_revoke`. Disabled by default.
+- Ability to view expired and revoked tokens limited to 30 days and [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/471683) in GitLab 17.9. Feature flag `retain_resource_access_token_user_after_revoke` removed.
+
+{{< /history >}}
In GitLab 17.9 and later, you can view both active and inactive group
access tokens on the access tokens page.
@@ -139,14 +159,18 @@ To revoke or rotate a group access token:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Settings > Access tokens**.
-1. For the relevant token, select **Revoke** (**{remove}**) or **Rotate** (**{retry}**).
+1. For the relevant token, select **Revoke** ({{< icon name="remove" >}}) or **Rotate** ({{< icon name="retry" >}}).
1. On the confirmation dialog, select **Revoke** or **Rotate**.
## Scopes for a group access token
-> - `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default.
-> - Feature flag `k8s_proxy_pat` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131518) in GitLab 16.5.
-> - `self_rotate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178111) in GitLab 17.9. Enabled by default.
+{{< history >}}
+
+- `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default.
+- Feature flag `k8s_proxy_pat` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131518) in GitLab 16.5.
+- `self_rotate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178111) in GitLab 17.9. Enabled by default.
+
+{{< /history >}}
The scope determines the actions you can perform when you authenticate with a group access token.
@@ -213,13 +237,20 @@ automatically applied:
### Group access token expiry emails
-> - Sixty and thirty day expiry notification emails [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464040) in GitLab 17.6 [with a flag](../../../administration/feature_flags.md) named `expiring_pats_30d_60d_notifications`. Disabled by default.
-> - Sixty and thirty day notification emails [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173792) in GitLab 17.7. Feature flag `expiring_pats_30d_60d_notifications` removed.
-> - Notifications to inherited group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+{{< history >}}
+
+- Sixty and thirty day expiry notification emails [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464040) in GitLab 17.6 [with a flag](../../../administration/feature_flags.md) named `expiring_pats_30d_60d_notifications`. Disabled by default.
+- Sixty and thirty day notification emails [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173792) in GitLab 17.7. Feature flag `expiring_pats_30d_60d_notifications` removed.
+- Notifications to inherited group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the sixty and thirty day expiry notification emails is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
GitLab runs a check every day at 1:00 AM UTC to identify group access tokens that are expiring in the near future. Members of the group with the Owner role are notified by email when these tokens expire in a certain number of days. The number of days differs depending on the version of GitLab:
- In GitLab 17.6 and later, group Owners are notified by email when the check identifies their group access tokens as expiring in the next sixty days. An additional email is sent when the check identifies their group access tokens as expiring in the next thirty days.
diff --git a/doc/user/group/ssh_certificates.md b/doc/user/group/ssh_certificates.md
index 88d12639926a5043537e13403591d55f382463fa..6f465ec48c412c9d6a1d41fbb332ae246a6bb9b4 100644
--- a/doc/user/group/ssh_certificates.md
+++ b/doc/user/group/ssh_certificates.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Manage Git access to projects by adding CA certificates to your top-level group, instead of individual groups."
+description: Manage Git access to projects by adding CA certificates to your top-level group, instead of individual groups.
title: Manage group SSH certificates
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
You can control and manage Git access to your projects and groups with SSH certificates.
@@ -68,9 +71,13 @@ allowing repository access.
## Add a CA certificate to a top-level group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.4 [with a flag](../feature_flags.md) named `ssh_certificates_rest_endpoints`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/424501) in GitLab 16.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/424501) in GitLab 17.7. Feature flag `ssh_certificates_rest_endpoints` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.4 [with a flag](../feature_flags.md) named `ssh_certificates_rest_endpoints`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/424501) in GitLab 16.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/424501) in GitLab 17.7. Feature flag `ssh_certificates_rest_endpoints` removed.
+
+{{< /history >}}
Prerequisites:
@@ -113,9 +120,13 @@ The user certificates can only be used to access the projects in the top-level g
## Enforce SSH certificates
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.7 [with a flag](../feature_flags.md) named `enforce_ssh_certificates_via_settings`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/426235) in GitLab 16.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/488635) in GitLab 17.7. Feature flag `enforce_ssh_certificates_via_settings` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.7 [with a flag](../feature_flags.md) named `enforce_ssh_certificates_via_settings`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/426235) in GitLab 16.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/488635) in GitLab 17.7. Feature flag `enforce_ssh_certificates_via_settings` removed.
+
+{{< /history >}}
You can enforce the usage of SSH certificates and restrict users from authenticating using SSH
keys and access tokens.
@@ -126,9 +137,12 @@ When SSH certificates are enforced:
- It does not apply to service accounts, deploy keys, and other types of internal accounts.
- Only SSH certificates added to the group by Owners are used to authenticate repository access.
-NOTE:
+{{< alert type="note" >}}
+
Enforcing SSH certificates disables HTTPS access for regular users.
+{{< /alert >}}
+
Prerequisites:
- You must have the Owner role for the group.
diff --git a/doc/user/group/subgroups/_index.md b/doc/user/group/subgroups/_index.md
index 3c75db9bbe3ac9dee227390d746de9cb59ee8e5d..303e5e89619ae7a4471260a302d1d89e33748375 100644
--- a/doc/user/group/subgroups/_index.md
+++ b/doc/user/group/subgroups/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Subgroups
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can organize GitLab [groups](../_index.md) into subgroups. You can use subgroups to:
@@ -64,12 +67,12 @@ To view the subgroups of a group:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select the **Subgroups and projects** tab.
1. Select the subgroup you want to view.
- To view nested subgroups, expand (**{chevron-down}**) a subgroup.
+ To view nested subgroups, expand ({{< icon name="chevron-down" >}}) a subgroup.
### Private subgroups in public parent groups
-In the hierarchy list, public groups with private subgroups have an expand option (**{chevron-down}**),
-which indicates the group has nested subgroups. All users can view the expand option (**{chevron-down}**), but only direct or inherited members of the private subgroup can view the private group.
+In the hierarchy list, public groups with private subgroups have an expand option ({{< icon name="chevron-down" >}}),
+which indicates the group has nested subgroups. All users can view the expand option ({{< icon name="chevron-down" >}}), but only direct or inherited members of the private subgroup can view the private group.
If you prefer to keep information about the presence of nested subgroups private,
you should add private subgroups only to private parent groups.
@@ -84,9 +87,12 @@ Prerequisites:
subgroups even if group creation is
[disabled by an Administrator](../../../administration/admin_area.md#prevent-a-user-from-creating-top-level-groups) in the user's settings.
-NOTE:
+{{< alert type="note" >}}
+
You cannot host a GitLab Pages subgroup website with a top-level domain name. For example, `subgroupname.example.io`.
+{{< /alert >}}
+
To create a subgroup:
1. On the left sidebar, select **Search or go to** and find the group you want to create the subgroup in.
@@ -119,9 +125,13 @@ For more information, view the [permissions table](../../permissions.md#group-me
## Subgroup membership
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to display invited group members on the Members tab of the Members page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
-> - Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to display invited group members on the Members tab of the Members page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
+- Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+
+{{< /history >}}
When you add a member to a group, that member is also added to all subgroups of that group.
The member's permissions are inherited from the group into all subgroups.
diff --git a/doc/user/group/troubleshooting.md b/doc/user/group/troubleshooting.md
index 0b3b1e086d3db57e602ed46b898bf0b006e58e01..0a2b29fcf8189384fded0a6dc0ef90560f6bcb2b 100644
--- a/doc/user/group/troubleshooting.md
+++ b/doc/user/group/troubleshooting.md
@@ -29,9 +29,12 @@ Group.find_by_sql("SELECT * FROM namespaces WHERE name LIKE '%oup'")
If transferring a group doesn't work through the UI or API, you may want to attempt the transfer in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session):
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
user = User.find_by_username('<username>')
group = Group.find_by_name("<group_name>")
@@ -60,9 +63,12 @@ end
At times, a group deletion may get stuck. If needed, in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session),
you can attempt to delete a group using the following command:
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
GroupDestroyWorker.new.perform(group_id, user_id)
```
diff --git a/doc/user/group/value_stream_analytics/_index.md b/doc/user/group/value_stream_analytics/_index.md
index ee8a58c8a9149d2cf89ba1213c7181efedf291c5..8e527d33fb7274ec15fbd24a7837a86b3e64d32d 100644
--- a/doc/user/group/value_stream_analytics/_index.md
+++ b/doc/user/group/value_stream_analytics/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Value stream analytics
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Value stream analytics measures the time it takes to go from an idea to production.
@@ -55,9 +58,12 @@ Value stream analytics offers different features at the project and group level
|Date filter behavior|Filters items [finished within the date range](https://gitlab.com/groups/gitlab-org/-/epics/6046)|Filters items by creation date.|Filters items by creation date.|
|Authorization|At least reporter|At least reporter|Can be public|
-NOTE:
+{{< alert type="note" >}}
+
Feature parity of project-level with group-level value stream analytics is achieved by using the new record `ProjectNamespace`. For details about this consolidation initiative, see the [Organization documentation](../../../development/organization/_index.md).
+{{< /alert >}}
+
## How value stream analytics works
Value stream analytics calculates the duration of every stage of your software development process.
@@ -78,7 +84,11 @@ Value streams are container objects for the stages. You can have multiple value
### Value stream stage events
-> - Merge request first reviewer assigned event [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/466383) in GitLab 17.2. Reviewer assignment events in merge requests created or updated prior to GitLab 17.2 are not available for reporting.
+{{< history >}}
+
+- Merge request first reviewer assigned event [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/466383) in GitLab 17.2. Reviewer assignment events in merge requests created or updated prior to GitLab 17.2 are not available for reporting.
+
+{{< /history >}}
Events are the smallest building blocks of the value stream analytics feature. A stage consists of a start event and an end event.
@@ -111,11 +121,18 @@ To learn what start and end events can be paired, see [Validating start and end
### How value stream analytics aggregates data
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - Enable filtering by stop date [added](https://gitlab.com/gitlab-org/gitlab/-/issues/355000) in GitLab 15.0
+{{< history >}}
+
+- Enable filtering by stop date [added](https://gitlab.com/gitlab-org/gitlab/-/issues/355000) in GitLab 15.0
+
+{{< /history >}}
Value stream analytics uses a backend process to collect and aggregate stage-level data, which
ensures it can scale for large groups with a high number of issues and merge requests. Due to this process,
@@ -155,9 +172,12 @@ The following table gives an overview of the pre-defined stages in value stream
| Review | The median time taken to review a merge request that has a closing issue pattern, between its creation and until it's merged. |
| Staging | The median time between merging a merge request that has a closing issue pattern until the very first deployment to a [production environment](#how-value-stream-analytics-identifies-the-production-environment). If there isn't a production environment, this is not tracked. |
-NOTE:
+{{< alert type="note" >}}
+
Value stream analytics works on timestamp data and aggregates only the final start and stop events of the stage. For items that move back and forth between stages multiple times, the stage time is calculated solely from the final events' timestamps.
+{{< /alert >}}
+
For information about how value stream analytics calculates each stage, see the [Value stream analytics development guide](../../../development/value_stream_analytics.md).
#### Example workflow
@@ -202,9 +222,13 @@ Keep in mind the following observations related to this example:
#### Cumulative label event duration
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432576) in GitLab 16.9 [with flags](../../../administration/feature_flags.md) named `enable_vsa_cumulative_label_duration_calculation` and `vsa_duration_from_db`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/17476) in GitLab 16.10. Feature flag `vsa_duration_from_db` removed.
-> - Feature flag `enable_vsa_cumulative_label_duration_calculation` [removed](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/17478) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432576) in GitLab 16.9 [with flags](../../../administration/feature_flags.md) named `enable_vsa_cumulative_label_duration_calculation` and `vsa_duration_from_db`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/17476) in GitLab 16.10. Feature flag `vsa_duration_from_db` removed.
+- Feature flag `enable_vsa_cumulative_label_duration_calculation` [removed](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/17478) in GitLab 17.0.
+
+{{< /history >}}
With this feature, value stream analytics measures the duration of repetitive events for label-based stages. You should configure label removal or addition events for both start and end events.
@@ -218,13 +242,19 @@ For example, a stage tracks when the `in progress` label is added and removed, w
With the original calculation method, the duration is five hours (from 9:00 to 14:00).
With cumulative label event duration calculation enabled, the duration is three hours (9:00 to 10:00 and 12:00 to 14:00).
-NOTE:
+{{< alert type="note" >}}
+
When you upgrade your GitLab version to 16.10 (or to a higher version), existing label-based value stream analytics stages are automatically reaggregated using the background aggregation process.
+{{< /alert >}}
+
##### Reaggregate data after upgrade
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
On large instances, when you upgrade the GitLab version and especially if several minor versions are skipped, the background aggregation processes might last longer. This delay can result in outdated data on the Value Stream Analytics page.
To speed up the aggregation process and avoid outdated data, in the [rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) you can invoke the synchronous aggregation snippet for a given group:
@@ -280,9 +310,13 @@ You can change the name of a project environment in your GitLab CI/CD configurat
## View value stream analytics
-> - Predefined date ranges dropdown list [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408656/) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `vsa_predefined_date_ranges`. Disabled by default.
-> - Predefined date ranges dropdown list [enabled on GitLab Self-Managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/433149) in GitLab 16.7.
-> - Predefined date ranges dropdown list [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/438051) in GitLab 16.9. Feature flag `vsa_predefined_date_ranges` removed.
+{{< history >}}
+
+- Predefined date ranges dropdown list [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408656/) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `vsa_predefined_date_ranges`. Disabled by default.
+- Predefined date ranges dropdown list [enabled on GitLab Self-Managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/433149) in GitLab 16.7.
+- Predefined date ranges dropdown list [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/438051) in GitLab 16.9. Feature flag `vsa_predefined_date_ranges` removed.
+
+{{< /history >}}
Prerequisites:
@@ -316,9 +350,12 @@ The table shows a list of related workflow items for the selected stage. Based o
- Issues
- Merge requests
-NOTE:
+{{< alert type="note" >}}
+
The end date for each predefined date range is the current day, and is included in the number of days selected. For example, the start date for `Last 30 days` is 29 days prior to the current day for a total of 30 days.
+{{< /alert >}}
+
### Data filters
You can filter value stream analytics to view data that matches specific criteria. The following filters are supported:
@@ -330,9 +367,12 @@ You can filter value stream analytics to view data that matches specific criteri
- Milestone
- Label
-NOTE:
+{{< alert type="note" >}}
+
For the "Tasks by type" chart, only the Date range and Project selector filters are available. Labels and other filters are not applied, and you need to select labels separately from the dropdown list next to the chart.
+{{< /alert >}}
+
## Value stream analytics metrics
The **Overview** page in value stream analytics displays key metrics of the DevSecOps lifecycle performance for projects and groups.
@@ -350,12 +390,19 @@ Value stream analytics includes the following lifecycle metrics:
### DORA metrics
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355304) time to restore service tile in GitLab 15.0.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357071) change failure rate tile in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355304) time to restore service tile in GitLab 15.0.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357071) change failure rate tile in GitLab 15.0.
+
+{{< /history >}}
Value stream analytics includes the following [DORA](../../analytics/dora_metrics.md) metrics:
@@ -418,15 +465,21 @@ To view the median time spent in each stage by a group:
- In the **To** field, select an end date.
1. To view the metrics for each stage, above the **Filter results** text box, hover over a stage.
-NOTE:
+{{< alert type="note" >}}
+
The date range selector filters items by the event time. The event time is when the
selected stage finished for the given item.
+{{< /alert >}}
+
## View tasks by type
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The **Tasks by type** chart displays the cumulative number of issues and merge requests per day for your group.
@@ -438,19 +491,26 @@ To view tasks by type:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Analyze > Value stream analytics**.
1. Below the **Filter results** text box, select **Overview**. The **Tasks by type** chart displays below the **Total time** chart.
-1. To switch between the task type, select the **Settings** (**{settings}**) dropdown list
+1. To switch between the task type, select the **Settings** ({{< icon name="settings" >}}) dropdown list
and select **Issues** or **Merge Requests**.
-1. To add or remove labels, select the **Settings** (**{settings}**) dropdown list
+1. To add or remove labels, select the **Settings** ({{< icon name="settings" >}}) dropdown list
and select or search for a label. By default the top group-level labels (maximum 10) are selected. You can select a maximum of 15 labels.
## Create a value stream
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
-> - **New value stream** [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381002) from a dialog to a page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `vsa_standalone_settings_page`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171856) in GitLab 17.7. Feature flag `vsa_standalone_settings_page` removed.
+{{< /details >}}
+
+{{< history >}}
+
+- **New value stream** [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381002) from a dialog to a page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `vsa_standalone_settings_page`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171856) in GitLab 17.7. Feature flag `vsa_standalone_settings_page` removed.
+
+{{< /history >}}
### Create a value stream with GitLab default stages
@@ -464,15 +524,18 @@ create custom stages in addition to those provided in the default template.
1. Select **Create from default template**.
1. Customize the default stages:
- To re-order stages, select the up or down arrows.
- - To hide a stage, select **Hide** (**{eye-slash}**).
+ - To hide a stage, select **Hide** ({{< icon name="eye-slash" >}}).
1. To add a custom stage, select **Add a stage**.
- Enter a name for the stage.
- Select a **Start event** and a **Stop event**.
1. Select **New value stream**.
-NOTE:
+{{< alert type="note" >}}
+
If you have recently upgraded to GitLab Premium, it can take up to 30 minutes for data to collect and display.
+{{< /alert >}}
+
### Create a value stream with custom stages
When you create a value stream, you can create and add custom stages that align with your own development workflows.
@@ -518,12 +581,19 @@ The first value stream uses standard timestamp-based events for defining the sta
## Edit a value stream
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - **Edit value stream** [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381002) from a dialog to a page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `vsa_standalone_settings_page`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171856) in GitLab 17.7. Feature flag `vsa_standalone_settings_page` removed.
+- **Edit value stream** [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381002) from a dialog to a page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `vsa_standalone_settings_page`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171856) in GitLab 17.7. Feature flag `vsa_standalone_settings_page` removed.
+
+{{< /history >}}
After you create a value stream, you can customize it to suit your purposes. To edit a value stream:
@@ -542,9 +612,12 @@ After you create a value stream, you can customize it to suit your purposes. To
## Delete a value stream
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To delete a custom value stream:
@@ -555,9 +628,12 @@ To delete a custom value stream:
## View number of days for a cycle to complete
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The **Total time chart** shows the average number of days it takes for development cycles to complete.
The chart shows data for the last 500 workflow items.
@@ -587,11 +663,18 @@ Access permissions for value stream analytics depend on the project type.
## Value Stream Analytics GraphQL API
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - Loading stage metrics through GraphQL [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/410327) in GitLab 17.0.
+{{< history >}}
+
+- Loading stage metrics through GraphQL [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/410327) in GitLab 17.0.
+
+{{< /history >}}
With the VSA GraphQL API, you can request metrics from your configured value streams and value stream stages. This can be useful if you want to export VSA data to an external system or for a report.
@@ -652,10 +735,13 @@ group(fullPath: "your-group-path") {
Depending how you want to consume the data, you can request metrics for one specific stage or all stages in your value stream.
-NOTE:
+{{< alert type="note" >}}
+
Requesting metrics for all stages might be too slow for some installations.
The recommended approach is to request metrics stage by stage.
+{{< /alert >}}
+
Requesting metrics for the stage:
```graphql
@@ -685,10 +771,13 @@ group(fullPath: "your-group-path") {
}
```
-NOTE:
+{{< alert type="note" >}}
+
You should always request metrics with a given time frame.
The longest supported time frame is 180 days.
+{{< /alert >}}
+
The `metrics` node supports additional filtering options:
- Assignee usernames
@@ -738,12 +827,19 @@ group(fullPath: "your-group-path") {
## Forecast deployment frequency with Value Stream Forecasting
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10228) in GitLab 16.2 as an [experiment](../../../policy/development_stages_support.md#experiment).
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10228) in GitLab 16.2 as an [experiment](../../../policy/development_stages_support.md#experiment).
+{{< /history >}}
Improve your planning and decision-making by predicting productivity metrics and
identifying anomalies across your software development lifecycle.
diff --git a/doc/user/infrastructure/_index.md b/doc/user/infrastructure/_index.md
index abcc3e3bceb18627db64adc49aa2053723215728..bf580e67a275b690b7da58f83dd3fbd921c0b867 100644
--- a/doc/user/infrastructure/_index.md
+++ b/doc/user/infrastructure/_index.md
@@ -1,8 +1,8 @@
---
stage: Deploy
group: Environments
-description: Terraform and Kubernetes deployments.
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
+description: Terraform and Kubernetes deployments.
title: Manage your infrastructure
---
diff --git a/doc/user/infrastructure/clusters/_index.md b/doc/user/infrastructure/clusters/_index.md
index 677e3dfc35f4da1d3a832002888b71f636f50930..48fc7257d7fa5070a91a6e56d11ecca58d1217ba 100644
--- a/doc/user/infrastructure/clusters/_index.md
+++ b/doc/user/infrastructure/clusters/_index.md
@@ -5,15 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Kubernetes clusters
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To connect clusters to GitLab, use the [GitLab agent](../../clusters/agent/_index.md).
## Certificate-based Kubernetes integration (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
In GitLab 14.5, the certificate-based method to connect Kubernetes clusters
to GitLab was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8),
as well as its related [features](#deprecated-features). In GitLab Self-Managed 17.0 and later,
@@ -21,6 +25,8 @@ this feature is disabled by default. For GitLab SaaS users, this feature is avai
GitLab 15.9 for users who have at least one certificate-based cluster enabled in their namespace hierarchy.
For GitLab SaaS users that never used this feature previously, it is no longer available.
+{{< /alert >}}
+
The certificate-based Kubernetes integration with GitLab is deprecated.
It had the following issues:
diff --git a/doc/user/infrastructure/clusters/connect/_index.md b/doc/user/infrastructure/clusters/connect/_index.md
index f00c513a61cbf942830c21574baa124468d8570a..a4b06fc404f07fb611820aa9706cd4309d30d0d6 100644
--- a/doc/user/infrastructure/clusters/connect/_index.md
+++ b/doc/user/infrastructure/clusters/connect/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Connect a cluster to GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The [certificate-based Kubernetes integration with GitLab](../_index.md)
was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8)
@@ -15,12 +18,19 @@ in GitLab 14.5. To connect your clusters, use the [GitLab agent](../../../cluste
## Cluster levels (deprecated)
-> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
The [concept of cluster levels was deprecated](../_index.md#cluster-levels)
in GitLab 14.5.
+{{< /alert >}}
+
Choose your cluster's level according to its purpose:
| Level | Purpose |
@@ -52,12 +62,19 @@ your cluster's level.
## Security implications for clusters connected with certificates
-> - Connecting clusters to GitLab through cluster certificates was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< history >}}
+
+- Connecting clusters to GitLab through cluster certificates was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
The whole cluster security is based on a model where [developers](../../../permissions.md)
are trusted, so **only trusted users should be allowed to control your clusters**.
+{{< /alert >}}
+
The use of cluster certificates to connect your cluster grants
access to a wide set of functionalities needed to successfully
build and deploy a containerized application. Bear in mind that
diff --git a/doc/user/infrastructure/clusters/connect/new_aks_cluster.md b/doc/user/infrastructure/clusters/connect/new_aks_cluster.md
index a206bec4bbe6664a821259ebe07e31c5c510711b..2b9af9efa26a68b4cb2fcb4d89a7eccd692088ed 100644
--- a/doc/user/infrastructure/clusters/connect/new_aks_cluster.md
+++ b/doc/user/infrastructure/clusters/connect/new_aks_cluster.md
@@ -33,7 +33,7 @@ Start by [importing the example project by URL](../../../project/import/repo_by_
To import the project:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Import project**.
1. Select **Repository by URL**.
1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/ci-cd/deploy-stage/environments-group/examples/gitlab-terraform-aks.git`.
@@ -87,7 +87,7 @@ See the [Azure Terraform provider](https://registry.terraform.io/providers/hashi
After configuring your project, manually trigger the provisioning of your cluster. In GitLab:
1. On the left sidebar, select **Build > Pipelines**.
-1. Next to **Play** (**{play}**), select the dropdown list icon (**{chevron-lg-down}**).
+1. Next to **Play** ({{< icon name="play" >}}), select the dropdown list icon ({{< icon name="chevron-lg-down" >}}).
1. Select **Deploy** to manually trigger the deployment job.
When the pipeline finishes successfully, you can view the new cluster:
@@ -128,4 +128,4 @@ To remove all resources:
```
1. On the left sidebar, select **Build > Pipelines** and select the most recent pipeline.
-1. For the `destroy` job, select **Play** (**{play}**).
+1. For the `destroy` job, select **Play** ({{< icon name="play" >}}).
diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md
index 7c357a7130860a61db50f62128f9b9dfe05ca1d9..2e07905f54da55376f98c839a4d666d0e9f09c30 100644
--- a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md
+++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md
@@ -93,7 +93,7 @@ After configuring your project, manually trigger the provisioning of your cluste
1. On the left sidebar, select **Build > Pipelines**.
1. Select **New pipeline**.
1. Select **Run pipeline**, and then select the newly created pipeline from the list.
-1. Next to the **deploy** job, select **Manual action** (**{status_manual}**).
+1. Next to the **deploy** job, select **Manual action** ({{< icon name="status_manual" >}}).
When the pipeline finishes successfully, you can see your new cluster:
@@ -118,7 +118,7 @@ A cleanup job is included in your pipeline by default.
To remove all created resources:
1. On the left sidebar, select **Build > Pipelines**, and then select the most recent pipeline.
-1. Next to the **destroy-environment** job, select **Manual action** (**{status_manual}**).
+1. Next to the **destroy-environment** job, select **Manual action** ({{< icon name="status_manual" >}}).
## Civo support
diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md
index 2cef99ae43b9373bd4223b6e556756b5d39aa7cb..6deefa7266b7a5780d039852bd0767c20dc76806 100644
--- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md
+++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md
@@ -138,7 +138,7 @@ View the [AWS Terraform provider](https://registry.terraform.io/providers/hashic
After configuring your project, manually trigger the provisioning of your cluster. In GitLab:
1. On the left sidebar, go to **Build > Pipelines**.
-1. Next to **Play** (**{play}**), select the dropdown list icon (**{chevron-lg-down}**).
+1. Next to **Play** ({{< icon name="play" >}}), select the dropdown list icon ({{< icon name="chevron-lg-down" >}}).
1. Select **Deploy** to manually trigger the deployment job.
When the pipeline finishes successfully, you can view the new cluster:
@@ -179,4 +179,4 @@ To remove all resources:
```
1. On the left sidebar, select **Build > Pipelines** and select the most recent pipeline.
-1. For the `destroy` job, select **Play** (**{play}**).
+1. For the `destroy` job, select **Play** ({{< icon name="play" >}}).
diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md
index 94a7dd9d9e15b0a37e5cb62ffa04fe789a20b1c7..a9b405afa4ba76298c16b43f473270f2103e1921 100644
--- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md
+++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md
@@ -10,13 +10,16 @@ Learn how to create a new cluster on Google Kubernetes Engine (GKE) through
and Kubernetes Terraform providers create GKE clusters. You connect the clusters to GitLab
by using the GitLab agent for Kubernetes.
-NOTE:
+{{< alert type="note" >}}
+
Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial),
and in partnership with Google, GitLab is able to offer an additional $200 for new
GCP accounts to get started with the GitLab integration with Google Kubernetes Engine.
[Follow this link](https://cloud.google.com/partners?pcn_code=0014M00001h35gDQAQ&hl=en#contact-form)
and apply for credit.
+{{< /alert >}}
+
**Before you begin:**
- A [Google Cloud Platform (GCP) service account](https://cloud.google.com/docs/authentication#service-accounts).
@@ -78,21 +81,25 @@ To set up your project to communicate to GCP and the GitLab API:
1. Download the JSON file with the service account key you created in the previous step.
1. On your computer, encode the JSON file to `base64` (replace `/path/to/sa-key.json` to the path to your key):
- ::Tabs
+ {{< tabs >}}
- :::TabTitle MacOS
+ {{< tab title="MacOS" >}}
```shell
base64 -i /path/to/sa-key.json | tr -d \\n
```
- :::TabTitle Linux
+ {{< /tab >}}
+
+ {{< tab title="Linux" >}}
```shell
base64 /path/to/sa-key.json | tr -d \\n
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Use the output of this command as the `BASE64_GOOGLE_CREDENTIALS` environment variable in the next step.
@@ -133,7 +140,7 @@ After configuring your project, manually trigger the provisioning of your cluste
1. On the left sidebar, select **Build > Pipelines**.
1. Select **New pipeline**.
-1. Next to **Play** (**{play}**), select the dropdown list icon (**{chevron-lg-down}**).
+1. Next to **Play** ({{< icon name="play" >}}), select the dropdown list icon ({{< icon name="chevron-lg-down" >}}).
1. Select **Deploy** to manually trigger the deployment job.
When the pipeline finishes successfully, you can see your new cluster:
@@ -174,4 +181,4 @@ To remove all resources:
```
1. On the left sidebar, select **Build > Pipelines** and select the most recent pipeline.
-1. For the `destroy` job, select **Play** (**{play}**).
+1. For the `destroy` job, select **Play** ({{< icon name="play" >}}).
diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md
index df16b190ef8874abc2fa08df31568002ed0a0d8b..f1bd8a34e4d589a733dabd94d7722df3385e2cd8 100644
--- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md
+++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Install cert-manager with a cluster management project
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Assuming you already have a project created from a
[management project template](../../../../clusters/management_project_template.md), to install cert-manager you should
@@ -28,12 +31,15 @@ And update the `applications/cert-manager/helmfile.yaml` with a valid email addr
email: example@example.com
```
-NOTE:
+{{< alert type="note" >}}
+
If your Kubernetes version is earlier than 1.20 and you are
[migrating from GitLab Managed Apps to a cluster management project](../../../../clusters/migrating_from_gma_to_project_template.md),
then you can instead use `- path: applications/cert-manager-legacy/helmfile.yaml` to
take over an existing release of cert-manager v0.10.
+{{< /alert >}}
+
cert-manager:
- Is installed by default into the `gitlab-managed-apps` namespace of your cluster.
diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md
index d06bbbce7af4d798909e5b3ad0c54c3bf2dd4f88..7e2e6ea51b0f5947918c8fc2d2308fce7fefe49c 100644
--- a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md
+++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Install Ingress with a cluster management project
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Assuming you already have a project created from a
[management project template](../../../../clusters/management_project_template.md), to install Ingress you should
diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md
index 4bdbd5ecd3a2dc2e9b86ab8563204a7a6be78ad4..68645a7180d4688259015f229a7b43b4c5a2938b 100644
--- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md
+++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Install GitLab Runner with a cluster management project
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Assuming you already have a project created from a
[management project template](../../../../clusters/management_project_template.md), to install GitLab Runner you should
diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md
index 078154522f8618367cf202b8d7b029f54eb5aab0..4be5ffb004b8ffec760b3ab87c3690ddfb8d36c7 100644
--- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md
+++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Install Vault with a cluster management project
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[HashiCorp Vault](https://www.vaultproject.io/) is a secrets management solution which
can be used to safely manage and store passwords, credentials, certificates, and more. A Vault
diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md
index 329c83b85e74326dcf84f6e6322c23911ba34346..66b3f5f4ea365a1fada7d21383ea1d72a7fe666e 100644
--- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md
+++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrate to the GitLab agent for Kubernetes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To connect your Kubernetes cluster with GitLab, you can use:
@@ -31,10 +34,13 @@ This workflow uses an agent to connect to your cluster. The agent:
- Is not exposed to the internet.
- Does not require full [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) access to GitLab.
-NOTE:
+{{< alert type="note" >}}
+
The certificate-based integration was used for popular GitLab features like
GitLab-managed Apps, GitLab-managed clusters, and Auto DevOps.
+{{< /alert >}}
+
## Find certificate-based clusters
You can find all the certificate-based clusters within a GitLab instance or group, including subgroups and projects, using [a dedicated API](../../../api/cluster_discovery.md#discover-certificate-based-clusters). Querying the API with a group ID returns all the certificate-based clusters defined at or below the provided group.
@@ -43,9 +49,12 @@ Clusters defined in parent groups are not returned in this case. This behavior h
Disabled clusters are returned as well to avoid accidentally leaving clusters behind.
-NOTE:
+{{< alert type="note" >}}
+
The cluster discovery API does not work for personal namespaces.
+{{< /alert >}}
+
## Migrate generic deployments
To migrate generic deployments:
@@ -58,8 +67,11 @@ To migrate generic deployments:
## Migrate from GitLab-managed clusters to Kubernetes resources
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
With GitLab-managed clusters, GitLab creates separate service accounts and namespaces for every branch and deploys by using these resources.
diff --git a/doc/user/infrastructure/iac/_index.md b/doc/user/infrastructure/iac/_index.md
index e55cfa6b900ad32bb27b97baf143ea1c6333b282..241e4d29a715667f40b4f9a7947cf87eedbb1fc1 100644
--- a/doc/user/infrastructure/iac/_index.md
+++ b/doc/user/infrastructure/iac/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Infrastructure as Code with OpenTofu and GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To manage your infrastructure with GitLab, you can use the integration with OpenTofu to define resources that you can version, reuse, and share:
@@ -57,10 +60,13 @@ For more information about templates, inputs, and how to use the OpenTofu CI/CD
## Quickstart a Terraform project in pipelines
-WARNING:
+{{< alert type="warning" >}}
+
The Terraform CI/CD templates are deprecated and will be removed in GitLab 18.0.
See [the deprecation announcement](../../../update/deprecations.md#deprecate-terraform-cicd-templates) for more information.
+{{< /alert >}}
+
The integration with GitLab and Terraform happens through GitLab CI/CD.
Use an `include` attribute to add the Terraform template to your project and
customize from there.
@@ -97,9 +103,12 @@ to use one of these templates:
- [The stable template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) with a skeleton that you can built on top of.
- [The advanced template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) to fully customize your setup.
-NOTE:
+{{< alert type="note" >}}
+
In each GitLab major release (for example, 15.0), the latest templates replace the older ones. This process can introduce breaking changes. You can [use an older version of the template](troubleshooting.md#use-an-older-version-of-the-template) if you need to.
+{{< /alert >}}
+
### Use a Terraform template (deprecated)
To use a Terraform template:
diff --git a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md
index 00e208b00312032c4d82c6bb4db4e9417fedcee0..0cdc35a2007d9e6bd7ccb38e8b493c85334ab2e4 100644
--- a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md
+++ b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Terraform helpers
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Terraform CI/CD templates are deprecated and will be removed in GitLab 18.0.
See [the deprecation announcement](../../../update/deprecations.md#deprecate-terraform-cicd-templates) for more information.
+{{< /alert >}}
+
GitLab provides two helpers to ease your integration with the [GitLab-managed Terraform State](terraform_state.md).
- The `gitlab-terraform` script, which is a thin wrapper around the `terraform` command.
diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md
index c4c4dc5dcb0c4f9df422a24e1f35b68dd7dec9f1..f5c727c90ceb348dec41a3ccb19da78fe96ea96c 100644
--- a/doc/user/infrastructure/iac/mr_integration.md
+++ b/doc/user/infrastructure/iac/mr_integration.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: OpenTofu integration in merge requests
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around OpenTofu code changes and their expected effects using the merge request pages. This way users don't have to build custom tools or rely on third-party solutions to streamline their IaC workflows.
@@ -18,7 +21,8 @@ you can expose details from `tofu plan` runs directly into a merge request widge
enabling you to see statistics about the resources that OpenTofu creates,
modifies, or destroys.
-WARNING:
+{{< alert type="warning" >}}
+
Like any other job artifact, OpenTofu plan data is viewable by anyone with the Guest role on the repository.
Neither OpenTofu nor GitLab encrypts the plan file by default. If your OpenTofu `plan.json` or `plan.cache`
files include sensitive data like passwords, access tokens, or certificates, you should
@@ -27,6 +31,8 @@ encrypt the plan output or modify the project visibility settings. You should al
and set the [artifact's public flag to false](../../../ci/yaml/_index.md#artifactspublic) (`public: false`).
This setting ensures artifacts are accessible only to GitLab administrators and project members with at least the Reporter role.
+{{< /alert >}}
+
## Configure OpenTofu report artifacts
GitLab [integrates with OpenTofu](_index.md#quickstart-an-opentofu-project-in-pipelines)
@@ -62,12 +68,15 @@ To manually configure a GitLab OpenTofu Report artifact:
- alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'"
```
- NOTE:
- In distributions that use Bash (for example, Ubuntu), `alias` statements are not
+ {{< alert type="note" >}}
+
+In distributions that use Bash (for example, Ubuntu), `alias` statements are not
expanded in non-interactive mode. If your pipelines fail with the error
`convert_report: command not found`, alias expansion can be activated explicitly
by adding a `shopt` command to your script:
+ {{< /alert >}}
+
```yaml
before_script:
- shopt -s expand_aliases
diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md
index 371e8fe5b55a1c9e0f24ba434897f8bed1a50163..54f84fa77e9f943dbf002a39290042bc377092b4 100644
--- a/doc/user/infrastructure/iac/terraform_state.md
+++ b/doc/user/infrastructure/iac/terraform_state.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab-managed Terraform/OpenTofu state
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Support for state names that contain periods introduced in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `allow_dots_on_tf_state_names`. Disabled by default.
-> - Support for state names that contain periods [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385597) in GitLab 16.0. Feature flag `allow_dots_on_tf_state_names` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Support for state names that contain periods introduced in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `allow_dots_on_tf_state_names`. Disabled by default.
+- Support for state names that contain periods [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385597) in GitLab 16.0. Feature flag `allow_dots_on_tf_state_names` removed.
+
+{{< /history >}}
OpenTofu uses state files to store details about your infrastructure configuration.
With OpenTofu remote [backends](https://opentofu.org/docs/language/settings/backends/configuration/),
@@ -20,7 +27,8 @@ GitLab provides an [OpenTofu HTTP backend](https://opentofu.org/docs/language/se
to securely store your state files with minimal configuration.
The OpenTofu state backend provides automatic versioning and encryption of the state files managed by the GitLab instance.
-WARNING:
+{{< alert type="warning" >}}
+
**Disaster recovery planning**
OpenTofu state files are encrypted with the lockbox Ruby gem when they are at rest on disk and in object storage with a key derived from the [db_key_base application setting](../../../development/application_secrets.md#secret-entries).
[To decrypt a state file, GitLab must be available](https://gitlab.com/gitlab-org/gitlab/-/issues/335739).
@@ -30,6 +38,8 @@ Additionally, if GitLab serves up OpenTofu modules or other dependencies that ar
these will be inaccessible. To work around this issue, make other arrangements to host or back up these dependencies,
or consider using a separate GitLab instance with no shared points of failure.
+{{< /alert >}}
+
## Prerequisites
For GitLab Self-Managed, before you can use GitLab for your OpenTofu state files:
@@ -47,7 +57,8 @@ Prerequisites:
- To lock, unlock, and write to the state by using `tofu apply`, you must have at least the Maintainer role.
- To read the state by using `tofu plan -lock=false`, you must have at least the Developer role.
-WARNING:
+{{< alert type="warning" >}}
+
Like any other job artifact, OpenTofu plan data is viewable by anyone with the Guest role on the repository.
Neither OpenTofu nor GitLab encrypts the plan file by default. If your OpenTofu `plan.json` or `plan.cache`
files include sensitive data like passwords, access tokens, or certificates, you should
@@ -56,6 +67,8 @@ encrypt the plan output or modify the project visibility settings. You should al
and set the [artifact's access flag to 'developer'](../../../ci/yaml/_index.md#artifactsaccess) (`access: 'developer'`).
This setting ensures artifacts are accessible only to GitLab administrators and project members with at least the Developer role.
+{{< /alert >}}
+
To configure GitLab CI/CD as a backend:
1. In your OpenTofu project, in a `.tf` file like `backend.tf`,
@@ -96,11 +109,14 @@ This configuration can lead to problems like [being unable to lock the state fil
You can access the GitLab-managed OpenTofu state from your local machine.
-WARNING:
+{{< alert type="warning" >}}
+
On clustered deployments of GitLab, you should not use local storage.
A split state can occur across nodes, making subsequent OpenTofu executions
inconsistent. Instead, use a remote storage resource.
+{{< /alert >}}
+
1. Ensure the OpenTofu state has been
[initialized for CI/CD](#initialize-an-opentofu-state-as-a-backend-by-using-gitlab-cicd).
1. Copy a pre-populated OpenTofu `init` command:
@@ -108,7 +124,7 @@ inconsistent. Instead, use a remote storage resource.
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Operate > Terraform states**.
1. Next to the environment you want to use, select **Actions**
- (**{ellipsis_v}**) and select **Copy Terraform init command**.
+ ({{< icon name="ellipsis_v" >}}) and select **Copy Terraform init command**.
1. Open a terminal and run this command on your local machine.
@@ -309,7 +325,7 @@ curl --header "Private-Token: <your_access_token>" --request DELETE "https://git
If you have at least the Maintainer role, you can remove a state file.
1. On the left sidebar, select **Operate > Terraform states**.
-1. In the **Actions** column, select **Actions** (**{ellipsis_v}**) and then **Remove state file and versions**.
+1. In the **Actions** column, select **Actions** ({{< icon name="ellipsis_v" >}}) and then **Remove state file and versions**.
### Remove a state file by using the API
diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md
index df6ee290d5da8ef8203f032377d531d1f227ffe5..4e081c127900161d7b89f9b9bf69fc2db6ae179e 100644
--- a/doc/user/infrastructure/iac/terraform_template_recipes.md
+++ b/doc/user/infrastructure/iac/terraform_template_recipes.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Terraform template recipes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Terraform CI/CD templates are deprecated and will be removed in GitLab 18.0.
See [the deprecation announcement](../../../update/deprecations.md#deprecate-terraform-cicd-templates) for more information.
+{{< /alert >}}
+
You can customize your Terraform integration by adding the recipes on
this page to your pipeline.
diff --git a/doc/user/instance/clusters/_index.md b/doc/user/instance/clusters/_index.md
index 6e550bb59f8cd2e5472b3c90241b5e970772471a..d8d55f9995b03663388a79aa4c34198cf9101661 100644
--- a/doc/user/instance/clusters/_index.md
+++ b/doc/user/instance/clusters/_index.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Instance Kubernetes clusters (certificate-based) (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab,
use the [GitLab agent](../../clusters/agent/_index.md).
+{{< /alert >}}
+
Similar to Kubernetes clusters for [projects](../../project/clusters/_index.md)
and [groups](../../group/clusters/_index.md), instance Kubernetes clusters enable
you to connect a Kubernetes cluster to the GitLab instance, and use the same cluster
@@ -36,9 +42,12 @@ match the [environment selector](../../../ci/environments/_index.md#limit-the-en
## Cluster environments
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
For a consolidated view of which CI [environments](../../../ci/environments/_index.md)
are deployed to the Kubernetes cluster, see the documentation for
diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index d68ca2c660222bc4becdf387cb993efef186a71b..2babbb4ae85f2f1dd3ad0b66d7b862c84fe62632 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Flavored Markdown (GLFM)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you enter text in the GitLab UI, GitLab assumes the text is in the Markdown language.
The text is rendered with a set of styles. These styles are called *GitLab Flavored Markdown*.
@@ -26,10 +29,13 @@ You can use GitLab Flavored Markdown in the following areas:
You can also use other rich text files in GitLab. You might have to install a dependency
to do so. For more information, see the [`gitlab-markup` gem project](https://gitlab.com/gitlab-org/gitlab-markup).
-NOTE:
+{{< alert type="note" >}}
+
As this Markdown specification is **valid for GitLab only**, you should
[view these styles as they appear on GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md).
+{{< /alert >}}
+
We do our best to render the Markdown faithfully here, however the
[GitLab documentation website](https://docs.gitlab.com) and the [GitLab handbook](https://handbook.gitlab.com)
use a different Markdown processor.
@@ -127,7 +133,11 @@ Alt-H2
### Heading IDs and links
-> - Heading link generation [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/440733) in GitLab 17.0.
+{{< history >}}
+
+- Heading link generation [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/440733) in GitLab 17.0.
+
+{{< /history >}}
[View this topic rendered in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#heading-ids-and-links).
@@ -513,7 +523,11 @@ CommonMark ignores the blank line and renders this as one list with paragraph sp
### Description lists
-> - Description lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26314) in GitLab 17.7.
+{{< history >}}
+
+- Description lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26314) in GitLab 17.7.
+
+{{< /history >}}
A description list is a list of terms with corresponding descriptions.
Each term can have multiple descriptions.
@@ -544,7 +558,11 @@ Fruits
### Task lists
-> - Inapplicable checkboxes [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85982) in GitLab 15.3.
+{{< history >}}
+
+- Inapplicable checkboxes [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85982) in GitLab 15.3.
+
+{{< /history >}}
[View this topic rendered in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#task-lists).
@@ -636,12 +654,15 @@ Do not change to reference style links.
Some text to show that the reference links can follow later.
-NOTE:
+{{< alert type="note" >}}
+
Relative links do not allow the referencing of project files in a wiki
page, or a wiki page in a project file. The reason: a wiki is always
in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)`
points the link to `wikis/style` only when the link is inside of a wiki Markdown file.
+{{< /alert >}}
+
### URL auto-linking
[View this topic rendered in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#url-auto-linking).
@@ -666,8 +687,12 @@ Almost any URL you put into your text is auto-linked:
## GitLab-specific references
-> - Autocomplete for wiki pages [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442229) in GitLab 16.11.
-> - Ability to reference labels from groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/455120) in GitLab 17.1.
+{{< history >}}
+
+- Autocomplete for wiki pages [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442229) in GitLab 16.11.
+- Ability to reference labels from groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/455120) in GitLab 17.1.
+
+{{< /history >}}
GitLab Flavored Markdown renders GitLab-specific references. For example, you can reference
an issue, a commit, a team member, or even an entire project team. GitLab Flavored Markdown turns
@@ -737,7 +762,11 @@ For example:
### Show item title
-> - Support for work items (tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390854) in GitLab 16.0.
+{{< history >}}
+
+- Support for work items (tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390854) in GitLab 16.0.
+
+{{< /history >}}
<!-- When epics as work items are generally available and `work_item_epics` flag is removed,
refactor the link below and add a history note -->
@@ -753,8 +782,12 @@ URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+` are al
### Show item summary
-> - Support for issues and merge requests [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386937) in GitLab 15.10.
-> - Support for work items (tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390854) in GitLab 16.0.
+{{< history >}}
+
+- Support for issues and merge requests [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386937) in GitLab 15.10.
+- Support for work items (tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390854) in GitLab 16.0.
+
+{{< /history >}}
<!-- When epics as work items are generally available and `work_item_epics` flag is removed,
refactor the link below and add a history note -->
@@ -780,8 +813,12 @@ references refresh.
### Comment preview on hover
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29663) in GitLab 17.3 [with a flag](../administration/feature_flags.md) named `comment_tooltips`. Disabled by default.
-> - Feature flag removed in GitLab 17.6
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29663) in GitLab 17.3 [with a flag](../administration/feature_flags.md) named `comment_tooltips`. Disabled by default.
+- Feature flag removed in GitLab 17.6
+
+{{< /history >}}
Hovering over a link to a comment shows the author and first line of the comment.
@@ -927,8 +964,12 @@ entry and paste the spreadsheet:
### JSON tables
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86353) in GitLab 15.3.
-> - Ability to use Markdown [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375177) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86353) in GitLab 15.3.
+- Ability to use Markdown [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375177) in GitLab 17.9.
+
+{{< /history >}}
To render tables with JSON code blocks, use the following syntax:
@@ -1163,8 +1204,12 @@ Here's an example video:
### Change image or video dimensions
-> - Support for images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28118) in GitLab 15.7.
-> - Support for videos [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17139) in GitLab 15.9.
+{{< history >}}
+
+- Support for images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28118) in GitLab 15.7.
+- Support for videos [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17139) in GitLab 15.9.
+
+{{< /history >}}
[View this topic rendered in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#change-the-image-or-video-dimensions).
@@ -1384,7 +1429,11 @@ In wikis, you can also add and edit diagrams created with the [diagrams.net edit
### Mermaid
-> - Support for Entity Relationship diagrams and mind maps [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384386) in GitLab 16.0.
+{{< history >}}
+
+- Support for Entity Relationship diagrams and mind maps [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384386) in GitLab 16.0.
+
+{{< /history >}}
[View this topic rendered in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#mermaid).
@@ -1477,8 +1526,12 @@ For more information, see the [Kroki integration](../administration/integration/
## Math equations
-> - LaTeX-compatible fencing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21757) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `markdown_dollar_math`. Disabled by default. Enabled on GitLab.com.
-> - LaTeX-compatible fencing [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371180) in GitLab 15.8. Feature flag `markdown_dollar_math` removed.
+{{< history >}}
+
+- LaTeX-compatible fencing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21757) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `markdown_dollar_math`. Disabled by default. Enabled on GitLab.com.
+- LaTeX-compatible fencing [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371180) in GitLab 15.8. Feature flag `markdown_dollar_math` removed.
+
+{{< /history >}}
[View this topic rendered in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#math).
@@ -2159,7 +2212,11 @@ This example links to `<wiki_root>/documentation.md`:
### diagrams.net editor
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322174) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322174) in GitLab 15.10.
+
+{{< /history >}}
In wikis, you can use the [diagrams.net](https://app.diagrams.net/) editor to create diagrams. You
can also edit diagrams created with the diagrams.net editor. The diagram editor is available in both
@@ -2174,7 +2231,7 @@ To create a diagram in the plain text editor:
1. On the wiki page you want to edit, select **Edit**.
1. In the text box, make sure you're using the plain text editor
(the button on the bottom left says **Switch to rich text editing**).
-1. In the editor's toolbar, select **Insert or edit diagram** (**{diagram}**).
+1. In the editor's toolbar, select **Insert or edit diagram** ({{< icon name="diagram" >}}).
1. Create the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor.
1. Select **Save & exit**.
@@ -2186,7 +2243,7 @@ To edit a diagram in the plain text editor:
1. In the text box, make sure you're using the plain text editor
(the button on the bottom left says **Switch to rich text editing**).
1. Position your cursor in the Markdown image reference that contains the diagram.
-1. Select **Insert or edit diagram** (**{diagram}**).
+1. Select **Insert or edit diagram** ({{< icon name="diagram" >}}).
1. Edit the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor.
1. Select **Save & exit**.
@@ -2200,7 +2257,7 @@ To create a diagram in the rich text editor:
1. On the wiki page you want to edit, select **Edit**.
1. In the text box, make sure you're using the rich text editor
(the button on the bottom left says **Switch to plain text editing**).
-1. In the editor's toolbar, select **More options** (**{plus}**).
+1. In the editor's toolbar, select **More options** ({{< icon name="plus" >}}).
1. In the dropdown list, select **Create or edit diagram**.
1. Create the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor.
1. Select **Save & exit**.
@@ -2213,7 +2270,7 @@ To edit a diagram in the rich text editor:
1. In the text box, make sure you're using the rich text editor
(the button on the bottom left says **Switch to plain text editing**).
1. Select the diagram that you want to edit.
-1. In the floating toolbar, select **Edit diagram** (**{diagram}**).
+1. In the floating toolbar, select **Edit diagram** ({{< icon name="diagram" >}}).
1. Edit the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor.
1. Select **Save & exit**.
diff --git a/doc/user/namespace/_index.md b/doc/user/namespace/_index.md
index a3459ded32bd11edd03d9faac1a31a74a1971766..1163978e2260e1529a8b452303db7e2a0703ff2c 100644
--- a/doc/user/namespace/_index.md
+++ b/doc/user/namespace/_index.md
@@ -13,9 +13,12 @@ When you choose a name for your namespace, keep in mind:
- [Naming rules](../reserved_names.md#rules-for-usernames-project-and-group-names-and-slugs)
- [Reserved group names](../reserved_names.md#reserved-group-names)
-NOTE:
+{{< alert type="note" >}}
+
Namespaces with a period (`.`) cause issues with SSL certificate validation and the source path when [publishing Terraform modules](../packages/terraform_module_registry/_index.md#publish-a-terraform-module).
+{{< /alert >}}
+
## Types of namespaces
GitLab has two types of namespaces:
diff --git a/doc/user/okrs.md b/doc/user/okrs.md
index 299dc28fbf2a161d297be6779969ef2f500db126..184a64109e229f1503687c74c1b5a8efae47a54a 100644
--- a/doc/user/okrs.md
+++ b/doc/user/okrs.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Objectives and key results (OKR)
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103355) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `okrs_mvc`. Disabled by default.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103355) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `okrs_mvc`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
[Objectives and key results](https://en.wikipedia.org/wiki/OKR) (OKRs) are a framework for setting
and tracking goals that are aligned with your organization's overall strategy and vision.
@@ -58,7 +68,7 @@ To create an objective:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**.
-1. In the upper-right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**.
+1. In the upper-right corner, next to **New issue**, select the down arrow {{< icon name="chevron-lg-down" >}} and then select **New objective**.
1. Select **New objective** again.
1. Enter the objective title.
1. Select **Create objective**.
@@ -90,7 +100,11 @@ its parent's objective.
## Edit title and description
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -101,18 +115,22 @@ To edit an OKR:
1. [Open the objective](okrs.md#view-an-objective) or [key result](#view-a-key-result) that you want to edit.
1. Optional. To edit the title, select it, make your changes, and select any area outside the title
text box.
-1. Optional. To edit the description, select the edit icon (**{pencil}**), make your changes, and
+1. Optional. To edit the description, select the edit icon ({{< icon name="pencil" >}}), make your changes, and
select **Save**.
## View OKR system notes
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) to feature flag named `work_items_mvc` in GitLab 15.8. Disabled by default.
-> - Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144141) from `work_items_mvc` to `work_items_beta` in GitLab 16.10.
-> - Changing activity sort order [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.8.
-> - Filtering activity [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389971) in GitLab 15.10.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.10.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) to feature flag named `work_items_mvc` in GitLab 15.8. Disabled by default.
+- Feature flag [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144141) from `work_items_mvc` to `work_items_beta` in GitLab 16.10.
+- Changing activity sort order [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.8.
+- Filtering activity [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389971) in GitLab 15.10.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.10.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -127,7 +145,11 @@ You can add [comments](discussions/_index.md) and reply to threads in OKRs.
## Assign users
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
To show who is responsible for an OKR, you can assign users to it.
@@ -144,7 +166,11 @@ To change the assignee on an OKR:
## Assign labels
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -161,8 +187,12 @@ To add labels to an OKR:
## Add an objective to a milestone
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) in GitLab 15.7.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) in GitLab 15.7.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can add an objective to a [milestone](project/milestones/_index.md).
You can see the milestone title when you view an objective.
@@ -180,8 +210,12 @@ To add an objective to a milestone:
## Set progress
-> - Setting progress for key results [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382433) in GitLab 15.8.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Setting progress for key results [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382433) in GitLab 15.8.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Show how much of the work needed to achieve an objective is finished.
@@ -207,8 +241,12 @@ To set progress of an objective or key result:
## Set health status
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381899) in GitLab 15.7.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381899) in GitLab 15.7.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
To better track the risk in meeting your goals, you can assign a [health status](project/issues/managing_issues.md#health-status)
to each objective and key result.
@@ -226,9 +264,13 @@ To set health status of an OKR:
## Promote a key result to an objective
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386877) in GitLab 16.0.
-> - Quick action `/promote_to` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386877) in GitLab 16.0.
+- Quick action `/promote_to` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -237,17 +279,19 @@ Prerequisites:
To promote a key result:
1. [Open the key result](#view-a-key-result).
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**).
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. Select **Promote to objective**.
Alternatively, use the `/promote_to objective` [quick action](project/quick_actions.md).
## Convert an OKR to another item type
-DETAILS:
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385131) in GitLab 17.8 [with a flag](../administration/feature_flags.md) named `work_items_beta`. Disabled by default.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/385131) [to the flag](../administration/feature_flags.md) named `okrs_mvc`. For current flag state, see the top of this page.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385131) in GitLab 17.8 [with a flag](../administration/feature_flags.md) named `work_items_beta`. Disabled by default.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/385131) [to the flag](../administration/feature_flags.md) named `okrs_mvc`. For current flag state, see the top of this page.
+
+{{< /history >}}
Convert an objective or key result into another item type, such as:
@@ -256,9 +300,12 @@ Convert an objective or key result into another item type, such as:
- Objective
- Key result
-WARNING:
+{{< alert type="warning" >}}
+
Changing the type might result in data loss if the target type does not support all fields from the original type.
+{{< /alert >}}
+
Prerequisites:
- The OKR you want to convert must not have a parent item assigned.
@@ -269,7 +316,7 @@ To convert an OKR into another item type:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
1. In the issue list, find your objective or key result and select it.
-1. In the upper-right corner, select **More actions** (**{ellipsis_v}**), then select **Change type**.
+1. In the upper-right corner, select **More actions** ({{< icon name="ellipsis_v" >}}), then select **Change type**.
1. Select the desired item type.
1. If all conditions are met, select **Change type**.
@@ -278,7 +325,11 @@ by `issue`, `task`, `objective` or `key result` in a comment.
## Copy objective or key result reference
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1.
+
+{{< /history >}}
To refer to an objective or key result elsewhere in GitLab, you can use its full URL or a short reference, which looks like
`namespace/project-name#123`, where `namespace` is either a group or a username.
@@ -287,7 +338,7 @@ To copy the objective or key result reference to your clipboard:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your objective or key result to view it.
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**.
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then select **Copy Reference**.
You can now paste the reference into another description or comment.
@@ -295,7 +346,11 @@ Read more about objective or key result references in [GitLab-Flavored Markdown]
## Copy objective or key result email address
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1.
+
+{{< /history >}}
You can create a comment in an objective or key result by sending an email.
Sending an email to this address creates a comment that contains the email body.
@@ -307,11 +362,15 @@ To copy the objective's or key result's email address:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy objective email address** or **Copy key result email address**.
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then select **Copy objective email address** or **Copy key result email address**.
## Close an OKR
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
When an OKR is achieved, you can close it.
The OKR is marked as closed but is not deleted.
@@ -340,7 +399,11 @@ below an objective's description.
### Add a child objective
-> - Ability to select which project to create the objective in [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436255) in GitLab 17.1.
+{{< history >}}
+
+- Ability to select which project to create the objective in [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436255) in GitLab 17.1.
+
+{{< /history >}}
Prerequisites:
@@ -366,7 +429,11 @@ To add an existing objective to an objective:
### Add a child key result
-> - Ability to select which project to create the key result in [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436255) in GitLab 17.1.
+{{< history >}}
+
+- Ability to select which project to create the key result in [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436255) in GitLab 17.1.
+
+{{< /history >}}
Prerequisites:
@@ -392,8 +459,12 @@ To add an existing key result to an objective:
### Reorder objective and key result children
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385887) in GitLab 16.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385887) in GitLab 16.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -404,14 +475,21 @@ To reorder them, drag them around.
### Schedule OKR check-in reminders
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422761) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `okr_checkin_reminders`. Disabled by default.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422761) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `okr_checkin_reminders`. Disabled by default.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Schedule check-in reminders to remind your team to provide status updates on the key results you care
about.
Reminders are sent to all assignees of descendant objects and key results as email notifications
@@ -450,8 +528,12 @@ To turn off a check-in reminder, enter:
## Set an objective as a parent
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 16.6.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 16.6.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -469,7 +551,11 @@ next to **Parent**, select the dropdown list and then select **Unassign**.
## Confidential OKRs
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8410) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8410) in GitLab 15.3.
+
+{{< /history >}}
Confidential OKRs are OKRs visible only to members of a project with
[sufficient permissions](#who-can-see-confidential-okrs).
@@ -478,7 +564,11 @@ leaking out.
### Make an OKR confidential
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
By default, OKRs are public.
You can make an OKR confidential when you create or edit it.
@@ -507,12 +597,16 @@ Prerequisites:
To change the confidentiality of an existing OKR:
1. [Open the objective](#view-an-objective) or [key result](#view-a-key-result).
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**).
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. Select **Turn on confidentiality** or **Turn off confidentiality**.
### Who can see confidential OKRs
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
When an OKR is made confidential, only users with at least the Planner role for the project have
access to the OKR.
@@ -530,31 +624,38 @@ Confidential OKRs are hidden in search results for users without the necessary p
### Confidential OKR indicators
Confidential OKRs are visually different from regular OKRs in a few ways.
-Wherever OKRs are listed, you can see the confidential (**{eye-slash}**) icon
+Wherever OKRs are listed, you can see the confidential ({{< icon name="eye-slash" >}}) icon
next to the OKRs that are marked as confidential.
If you don't have [enough permissions](#who-can-see-confidential-okrs),
you cannot see confidential OKRs at all.
-Likewise, while inside the OKR, you can see the confidential (**{eye-slash}**) icon right next to
+Likewise, while inside the OKR, you can see the confidential ({{< icon name="eye-slash" >}}) icon right next to
the breadcrumbs.
Every change from regular to confidential and vice versa, is indicated by a
system note in the OKR's comments, for example:
-> - **{eye-slash}** Jo Garcia made the issue confidential 5 minutes ago
-> - **{eye}** Jo Garcia made the issue visible to everyone just now
+> - {{< icon name="eye-slash" >}} Jo Garcia made the issue confidential 5 minutes ago
+> - {{< icon name="eye" >}} Jo Garcia made the issue visible to everyone just now
## Lock discussion
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398649) in GitLab 16.9 [with a flag](../administration/feature_flags.md) named `work_items_beta`. Disabled by default.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398649) in GitLab 16.9 [with a flag](../administration/feature_flags.md) named `work_items_beta`. Disabled by default.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
You can prevent public comments in an OKR.
When you do, only project members can add and edit comments.
@@ -564,7 +665,7 @@ Prerequisites:
To lock an OKR:
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**).
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. Select **Lock discussion**.
A system note is added to the page details.
@@ -573,17 +674,27 @@ If an OKR is closed with a locked discussion, then you cannot reopen it until th
## Two-column layout
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. This feature is in [beta](../policy/development_stages_support.md).
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/446064) to feature flag named `work_items_beta` in GitLab 16.10. Disabled by default.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. This feature is in [beta](../policy/development_stages_support.md).
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/446064) to feature flag named `work_items_beta` in GitLab 16.10. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available per group, an administrator can [enable the feature flag](../administration/feature_flags.md) named `work_items_beta`.
On GitLab.com and GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
+{{< /alert >}}
+
When enabled, OKRs use a two-column layout, similar to issues.
The description and threads are on the left, and attributes, such as labels
or assignees, on the right.
@@ -595,11 +706,15 @@ If you find a bug, [comment on the feedback issue](https://gitlab.com/gitlab-org
## Linked items in OKRs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Enabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7.
-> - Adding related items by entering their URLs and IDs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427594) in GitLab 16.8.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150148) in GitLab 17.0. Feature flag `linked_work_items` removed.
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/10267) minimum required role from Reporter (if true) to Guest in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Enabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7.
+- Adding related items by entering their URLs and IDs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427594) in GitLab 16.8.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150148) in GitLab 17.0. Feature flag `linked_work_items` removed.
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/10267) minimum required role from Reporter (if true) to Guest in GitLab 17.0.
+
+{{< /history >}}
Linked items are a bi-directional relationship and appear in a block below
the Child objectives and key results. You can link an objective, key result, or a task in the same project with each other.
@@ -635,6 +750,6 @@ Prerequisites:
- You must have at least the Guest role for the project.
In the **Linked items** section of an objective or key result,
-next to each item, select the vertical ellipsis (**{ellipsis_v}**) and then select **Remove**.
+next to each item, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and then select **Remove**.
Due to the bi-directional relationship, the relationship no longer appears in either item.
diff --git a/doc/user/operations_dashboard/_index.md b/doc/user/operations_dashboard/_index.md
index 0d587b964c2c5d71cae8e197c3dbd4f093093808..14f3f462e545735c033ec74f3ee6a05b364d0414 100644
--- a/doc/user/operations_dashboard/_index.md
+++ b/doc/user/operations_dashboard/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Operations Dashboard
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Operations Dashboard provides a summary of each project's operational health,
including pipeline and alert status.
diff --git a/doc/user/organization/_index.md b/doc/user/organization/_index.md
index e96d055d1b3628c1ab4f510f197169d0c39644d0..afa78221a1fdce6a98b97e702ae1146cf9736ca3 100644
--- a/doc/user/organization/_index.md
+++ b/doc/user/organization/_index.md
@@ -5,23 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Organization
---
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409913) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `ui_for_organizations`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/409913) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `ui_for_organizations`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `ui_for_organizations`.
On GitLab.com and GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the
-sole discretion of GitLab Inc.
+{{< /alert >}}
+
+{{< alert type="disclaimer" />}}
+
+{{< alert type="note" >}}
-NOTE:
Organization is in development.
+{{< /alert >}}
+
Organization will be above the [top-level namespaces](../namespace/_index.md) for you to manage
everything you do as a GitLab administrator, including:
@@ -39,10 +44,13 @@ To view the organizations you have access to:
## Create an organization
-NOTE:
+{{< alert type="note" >}}
+
In [Cells 1.0](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-1.0/) organizations can be only private.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New organization**.
+{{< /alert >}}
+
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New organization**.
1. In the **Organization name** text box, enter a name for the organization.
1. In the **Organization URL** text box, enter a path for the organization.
1. In the **Organization description** text box, enter a description for the organization. Supports a [limited subset of Markdown](#supported-markdown-for-organization-description).
@@ -70,19 +78,25 @@ In [Cells 1.0](https://handbook.gitlab.com/handbook/engineering/architecture/des
## View an organization's visibility level
-NOTE:
+{{< alert type="note" >}}
+
In [Cells 1.0](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-1.0/) organizations can be only private.
+{{< /alert >}}
+
1. On the left sidebar, select **Organizations** and find your organization.
1. Select **Settings > General**.
1. Expand the **Visibility** section.
## Switch organizations
-NOTE:
+{{< alert type="note" >}}
+
Switching between organizations is not supported in [Cells 1.0](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-1.0/),
but is supported in [Cells 1.5](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/iterations/cells-1.5/).
+{{< /alert >}}
+
To switch organizations:
- On the left sidebar, in the upper corner, from the **Current organization** dropdown list select the organization you want to switch to.
@@ -94,7 +108,7 @@ To switch organizations:
1. Optional. Filter the results:
- To search for specific groups or projects, in the search box enter your search term (minimum three characters).
- To view only groups or projects, from the **Display** dropdown list select an option.
-1. Optional. To sort the results by name, date created, or date updated, from the dropdown list select an option. Then select ascending (**{sort-lowest}**) or descending (**{sort-highest}**) order.
+1. Optional. To sort the results by name, date created, or date updated, from the dropdown list select an option. Then select ascending ({{< icon name="sort-lowest" >}}) or descending ({{< icon name="sort-highest" >}}) order.
## Create a group in an organization
@@ -125,9 +139,12 @@ To change a user's role:
1. Find the user whose role you want to update.
1. From the **Organization role** dropdown list, select a role.
-NOTE:
+{{< alert type="note" >}}
+
If you cannot select from the **Organization role** dropdown list, this user is the organization's only Owner. To change this user's role, first assign the Owner role to another user.
+{{< /alert >}}
+
## Supported Markdown for Organization description
The Organization description field supports a limited subset of [GitLab Flavored Markdown](../markdown.md), including:
diff --git a/doc/user/packages/_index.md b/doc/user/packages/_index.md
index c481609837e6dd5f60705978c7429f41aed0746e..b6573913e491cb12ed65880e8acd8f35d3c3e5ab 100644
--- a/doc/user/packages/_index.md
+++ b/doc/user/packages/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Packages and Registries
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The GitLab [package registry](package_registry/_index.md) acts as a private or public registry
for a variety of common package managers. You can publish and share
diff --git a/doc/user/packages/composer_repository/_index.md b/doc/user/packages/composer_repository/_index.md
index b3eca2fbd694c5b58633c13c2b8da90447fd139c..46787e3ce71debe6df381067188aab6ad9b1c92d 100644
--- a/doc/user/packages/composer_repository/_index.md
+++ b/doc/user/packages/composer_repository/_index.md
@@ -5,16 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Composer packages in the package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Composer package registry for GitLab is under development and isn't ready for production use due to
limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6817) details the remaining
work and timelines to make it production ready.
+{{< /alert >}}
+
Publish [Composer](https://getcomposer.org/) packages in your project's package registry.
Then, install the packages whenever you need to use them as a dependency.
@@ -108,9 +114,12 @@ A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` temp
1. Above the file list, select **Set up CI/CD**. If this button is not available, select **CI/CD Configuration** and then **Edit**.
1. From the **Apply a template** list, select **Composer**.
-WARNING:
+{{< alert type="warning" >}}
+
Do not save unless you want to overwrite the existing CI/CD file.
+{{< /alert >}}
+
## Publishing packages with the same name or version
When you publish:
@@ -282,11 +291,14 @@ To install a package:
composer config --unset gitlab-domains
```
- NOTE:
- On GitLab.com, Composer uses the GitLab token from `auth.json` as a private token by default.
+ {{< alert type="note" >}}
+
+On GitLab.com, Composer uses the GitLab token from `auth.json` as a private token by default.
Without the `gitlab-domains` definition in `composer.json`, Composer uses the GitLab token
as basic-auth, with the token as a username and a blank password. This results in a 401 error.
+ {{< /alert >}}
+
1. With the `composer.json` and `auth.json` files configured, you can install the package by running:
```shell
@@ -299,12 +311,15 @@ To install a package:
composer req <package-name>:<package-version>
```
-WARNING:
+{{< alert type="warning" >}}
+
Never commit the `auth.json` file to your repository. To install packages from a CI/CD job,
consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages.md#satis) tool with your access token
stored in a [GitLab CI/CD variable](../../../ci/variables/_index.md) or in
[HashiCorp Vault](../../../ci/secrets/_index.md).
+{{< /alert >}}
+
### Install from source
You can install from source by pulling the Git repository directly. To do so, either:
@@ -331,9 +346,13 @@ You can install from source by pulling the Git repository directly. To do so, ei
#### SSH access
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119739) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `composer_use_ssh_source_urls`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/329246) GitLab 16.5.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135467) in GitLab 16.6. Feature flag `composer_use_ssh_source_urls` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119739) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `composer_use_ssh_source_urls`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/329246) GitLab 16.5.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135467) in GitLab 16.6. Feature flag `composer_use_ssh_source_urls` removed.
+
+{{< /history >}}
When you install from source, the `composer` configures an
access to the project's Git repository.
diff --git a/doc/user/packages/conan_repository/_index.md b/doc/user/packages/conan_repository/_index.md
index f4e1ad94cdd64e4f65034f39c0ba6cd63e5fc29b..f5c55e31a2ef17bb22e24ad6f0b31e3f4d9f55ca 100644
--- a/doc/user/packages/conan_repository/_index.md
+++ b/doc/user/packages/conan_repository/_index.md
@@ -5,19 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Conan packages in the package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Conan package registry for GitLab is under development and isn't ready for production use due to
limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6816) details the remaining
work and timelines to make it production ready.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
The Conan registry is not FIPS compliant and is disabled when [FIPS mode](../../../development/fips_gitlab.md) is enabled.
+{{< /alert >}}
+
Publish Conan packages in your project's package registry. Then install the
packages whenever you need to use them as a dependency.
@@ -118,12 +127,15 @@ To authenticate to the package registry, you need one of the following:
scope set to `read_package_registry`, `write_package_registry`, or both.
- A [CI job token](#publish-a-conan-package-by-using-cicd).
-NOTE:
+{{< alert type="note" >}}
+
Packages from private and internal projects are hidden if you are not
authenticated. If you try to search or download a package from a private or internal
project without authenticating, you receive the error `unable to find the package in remote`
in the Conan client.
+{{< /alert >}}
+
### Add your credentials to the GitLab remote
Associate your token with the GitLab remote, so that you don't have to
@@ -144,10 +156,13 @@ conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_acc
Now when you run commands with `--remote=gitlab`, your username and password are
included in the requests.
-NOTE:
+{{< alert type="note" >}}
+
Because your authentication with GitLab expires on a regular basis, you may
occasionally need to re-enter your personal access token.
+{{< /alert >}}
+
### Set a default remote for your project (optional)
If you want to interact with the GitLab package registry without having to
@@ -160,10 +175,13 @@ In a terminal, run this command:
conan remote add_ref Hello/0.1@mycompany/beta gitlab
```
-NOTE:
+{{< alert type="note" >}}
+
The package recipe includes the version, so the default remote for
`Hello/0.1@user/channel` doesn't work for `Hello/0.2@user/channel`.
+{{< /alert >}}
+
If you don't set a default user or remote, you can still include the user and
remote in your commands:
@@ -266,11 +284,14 @@ Prerequisites:
conan install .. <options>
```
-NOTE:
+{{< alert type="note" >}}
+
If you try installing the package you created in this tutorial, the install command
has no effect because the package already exists.
Delete `~/.conan/data` to clean up the packages stored in the cache.
+{{< /alert >}}
+
## Remove a Conan package
There are two ways to remove a Conan package from the GitLab package registry.
@@ -284,14 +305,17 @@ There are two ways to remove a Conan package from the GitLab package registry.
You must explicitly include the remote in this command, otherwise the package
is removed only from your local system cache.
- NOTE:
- This command removes all recipe and binary package files from the
+ {{< alert type="note" >}}
+
+This command removes all recipe and binary package files from the
package registry.
+ {{< /alert >}}
+
- From the GitLab user interface:
Go to your project's **Deploy > Package Registry**. Remove the
- package by selecting **Remove repository** (**{remove}**).
+ package by selecting **Remove repository** ({{< icon name="remove" >}}).
## Search for Conan packages in the package registry
@@ -319,9 +343,12 @@ The scope of your search depends on your Conan remote configuration:
- If you have a remote configured for a [project](#add-a-remote-for-your-project), your search includes all
packages in the target project, as long as you have permission to access it.
-NOTE:
+{{< alert type="note" >}}
+
The limit of the search results is 500 packages, and the results are sorted by the most recently published packages.
+{{< /alert >}}
+
## Fetch Conan package information from the package registry
The `conan info` command returns information about a package:
diff --git a/doc/user/packages/container_registry/_index.md b/doc/user/packages/container_registry/_index.md
index 686ac3503c17cc4b61e6d71b8d0d6ad4ab41f2ce..1610eefa0af029fce1c15e0492324a57660509df 100644
--- a/doc/user/packages/container_registry/_index.md
+++ b/doc/user/packages/container_registry/_index.md
@@ -5,19 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab container registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use the integrated container registry to store container images for each GitLab project.
To enable the container registry for your GitLab instance, see the [administrator documentation](../../../administration/packages/container_registry.md).
-NOTE:
+{{< alert type="note" >}}
+
If you pull container images from Docker Hub, you can use the
[GitLab Dependency Proxy](../dependency_proxy/_index.md#use-the-dependency-proxy-for-docker-images) to avoid
rate limits and speed up your pipelines.
+{{< /alert >}}
+
## View the container registry
You can view the container registry for a project or group.
@@ -48,7 +54,7 @@ To download and run a container image hosted in the container registry:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Deploy > Container Registry**.
-1. Find the container image you want to work with and select **Copy image path** （**{copy-to-clipboard}**）.
+1. Find the container image you want to work with and select **Copy image path** （{{< icon name="copy-to-clipboard" >}}）.
1. Use `docker run` with the copied link:
@@ -56,10 +62,13 @@ To download and run a container image hosted in the container registry:
docker run [options] registry.example.com/group/project/image [arguments]
```
-NOTE:
+{{< alert type="note" >}}
+
You must [authenticate with the container registry](authenticate_with_container_registry.md) to download
container images from a private repository.
+{{< /alert >}}
+
For more information on running container images, see the [Docker documentation](https://docs.docker.com/get-started/).
## Naming convention for your container images
@@ -161,7 +170,11 @@ this setting. However, disabling the container registry disables all container r
## Supported image types
-> - OCI conformance [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10345) in GitLab 16.6.
+{{< history >}}
+
+- OCI conformance [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10345) in GitLab 16.6.
+
+{{< /history >}}
The container registry supports the [Docker V2](https://distribution.github.io/distribution/spec/manifest-v2-2/)
and [Open Container Initiative (OCI)](https://github.com/opencontainers/image-spec/blob/main/spec.md)
@@ -171,7 +184,11 @@ OCI support means that you can host OCI-based image formats in the registry, suc
## Container image signatures
-> - Container image signature display [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7856) in GitLab 17.1.
+{{< history >}}
+
+- Container image signature display [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7856) in GitLab 17.1.
+
+{{< /history >}}
In the GitLab container registry, you can use the [OCI 1.1 manifest `subject` field](https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md)
to associate container images with [Cosign signatures](../../../ci/yaml/signing_examples.md).
@@ -201,6 +218,9 @@ For example:
COSIGN_EXPERIMENTAL=1 cosign sign --registry-referrers-mode oci-1-1 <container image>
```
-NOTE:
+{{< alert type="note" >}}
+
While the GitLab container registry supports the OCI 1.1 manifest `subject` field, it does not fully
implement the [OCI 1.1 Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers).
+
+{{< /alert >}}
diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md
index 9279684e767bc21cc9a187a7a23c23272cd673a0..eb0075ae90f5c4db6a5becda103f732ada689aac 100644
--- a/doc/user/packages/container_registry/authenticate_with_container_registry.md
+++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Authenticate with the container registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To authenticate with the container registry, you can use a:
@@ -21,12 +24,15 @@ All of these authentication methods require the minimum scope:
- For read (pull) access, to be `read_registry`.
- For write (push) access, to be `write_registry` and `read_registry`.
-NOTE:
+{{< alert type="note" >}}
+
[Admin Mode](../../../administration/settings/sign_in_restrictions.md#admin-mode)
does not apply during authentication with the container registry. If you are an administrator
with Admin Mode enabled, and you create a personal access token without the `admin_mode` scope,
that token works even though Admin Mode is enabled.
+{{< /alert >}}
+
To authenticate, run the `docker login` command. For example:
```shell
diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md
index 0d67961dd26cc59e5f7634f0242e4b4da061e88c..fc8800c82ef3fff6f42b8bc18e6ba636d2838bbf 100644
--- a/doc/user/packages/container_registry/build_and_push_images.md
+++ b/doc/user/packages/container_registry/build_and_push_images.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Build and push container images to the container registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Before you can build and push container images, you must [authenticate](authenticate_with_container_registry.md) with the container registry.
@@ -211,7 +214,10 @@ deploy:
environment: production
```
-NOTE:
+{{< alert type="note" >}}
+
This example explicitly calls `docker pull`. If you prefer to implicitly pull the container image using `image:`,
and use either the [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes/) executor,
make sure that [`pull_policy`](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work) is set to `always`.
+
+{{< /alert >}}
diff --git a/doc/user/packages/container_registry/container_protection_rules.md b/doc/user/packages/container_registry/container_protection_rules.md
index ae3c065f4be46da6011d0c6a3d2167aaf70ac9cd..69903d1b17668190309c73a6f084155ee64c416e 100644
--- a/doc/user/packages/container_registry/container_protection_rules.md
+++ b/doc/user/packages/container_registry/container_protection_rules.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'container_repository_protection_rules.md'
-remove_date: '2025-02-28'
+redirect_to: container_repository_protection_rules.md
+remove_date: "2025-02-28"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/packages/container_registry/container_repository_protection_rules.md b/doc/user/packages/container_registry/container_repository_protection_rules.md
index a15ddd40ceb2a23e94cad5c6ea1dc05730edf7ba..c746396630fd5836586f3a09eb2a1c2f52d889aa 100644
--- a/doc/user/packages/container_registry/container_repository_protection_rules.md
+++ b/doc/user/packages/container_registry/container_repository_protection_rules.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Protected container repositories
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463669) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `containers_protected_containers`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/429074) in GitLab 17.8.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/480385) in GitLab 17.8. Feature flag `container_registry_protected_containers` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463669) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `containers_protected_containers`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/429074) in GitLab 17.8.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/480385) in GitLab 17.8. Feature flag `container_registry_protected_containers` removed.
+
+{{< /history >}}
By default, any user with at least the Developer role can push and delete
container images to or from container repositories. Protect a container repository to restrict
@@ -41,7 +48,11 @@ A container repository is protected if at least one protection rule matches.
## Create a container repository protection rule
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146523) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146523) in GitLab 16.10.
+
+{{< /history >}}
Prerequisites:
@@ -64,7 +75,11 @@ The protection rule is created and the container repository is now protected.
## Delete a container repository protection rule
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146622) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146622) in GitLab 17.0.
+
+{{< /history >}}
Prerequisites:
@@ -75,7 +90,7 @@ To delete a protection rule:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > Packages and registries**.
1. Expand **Container registry**.
-1. Under **Protected container repositories**, next to the protection rule you want to delete, select **Delete** (**{remove}**).
+1. Under **Protected container repositories**, next to the protection rule you want to delete, select **Delete** ({{< icon name="remove" >}}).
1. On the confirmation dialog, select **Delete**.
The protection rule is deleted and the container repository is no longer protected.
diff --git a/doc/user/packages/container_registry/delete_container_registry_images.md b/doc/user/packages/container_registry/delete_container_registry_images.md
index 18681d48c6ce6200ade4aaba8a62de38740e1420..fa44d723d2e5a40404f72b321fa896f9bda6a551 100644
--- a/doc/user/packages/container_registry/delete_container_registry_images.md
+++ b/doc/user/packages/container_registry/delete_container_registry_images.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Delete container images from the container registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can delete container images from your container registry.
@@ -18,10 +21,13 @@ for deleting container images from specific projects.
To delete specific container images from a project or group, you can use [the GitLab UI](#use-the-gitlab-ui)
or [GitLab API](#use-the-gitlab-api).
-WARNING:
+{{< alert type="warning" >}}
+
Deleting container images is a destructive action and can't be undone. To restore
a deleted container image, you must rebuild and re-upload it.
+{{< /alert >}}
+
## Garbage collection
Deleting a container image on self-managed instances doesn't free up storage space, it only marks the image
@@ -50,9 +56,9 @@ To delete container images using the GitLab UI:
by either:
- Deleting the entire repository, and all the tags it contains, by selecting
- the red **{remove}** **Trash** icon.
+ the red {{< icon name="remove" >}} **Trash** icon.
- Navigating to the repository, and deleting tags individually or in bulk
- by selecting the red **{remove}** **Trash** icon next to the tag you want
+ by selecting the red {{< icon name="remove" >}} **Trash** icon next to the tag you want
to delete.
1. On the dialog, select **Remove tag**.
@@ -71,11 +77,14 @@ information, see the following endpoints:
## Use GitLab CI/CD
-NOTE:
+{{< alert type="note" >}}
+
GitLab CI/CD doesn't provide a built-in way to remove your container images. This example uses a
third-party tool called [`regctl`](https://github.com/regclient/regclient) that talks to the GitLab Registry API.
For assistance with this third-party tool, see [the issue queue for regclient](https://github.com/regclient/regclient/issues).
+{{< /alert >}}
+
The following example defines two stages: `build`, and `clean`. The `build_image` job builds a container
image for the branch, and the `delete_image` job deletes it. The `reg` executable is downloaded and used to
remove the container image matching the `$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG`
@@ -121,10 +130,13 @@ delete_image:
- regctl tag rm $IMAGE
```
-NOTE:
+{{< alert type="note" >}}
+
You can download the latest `regctl` release from [the releases page](https://github.com/regclient/regclient/releasess), then update
the code example by changing the `REGCTL_VERSION` variable defined in the `delete_image` job.
+{{< /alert >}}
+
## Use a cleanup policy
You can create a per-project [cleanup policy](reduce_container_registry_storage.md#cleanup-policy) to ensure older tags and
diff --git a/doc/user/packages/container_registry/protected_container_tags.md b/doc/user/packages/container_registry/protected_container_tags.md
index 9883432ccc79676c06e5c2baf48d486f09b8b6a1..2d6c9faf3fccb5763cfc749f0cc156e11cff7b9c 100644
--- a/doc/user/packages/container_registry/protected_container_tags.md
+++ b/doc/user/packages/container_registry/protected_container_tags.md
@@ -5,18 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Protected container tags
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/505455) as an [experiment](../../../policy/development_stages_support.md) in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `container_registry_protected_tags`. Disabled by default.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/505455) as an [experiment](../../../policy/development_stages_support.md) in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `container_registry_protected_tags`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Control who can push and delete container tags in your project.
By default, users with the Developer role or higher can push and delete image tags in all project container repositories.
@@ -82,7 +92,7 @@ To delete a protection rule:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > Packages and registries**.
1. Expand **Container registry**.
-1. Under **Protected container tags**, next to the protection rule you want to delete, select **Delete** (**{remove}**).
+1. Under **Protected container tags**, next to the protection rule you want to delete, select **Delete** ({{< icon name="remove" >}}).
1. When prompted for confirmation, select **Delete**.
The protection rule is deleted and matching tags are no longer protected.
diff --git a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md
index 73b786b984d48ac63169e828aa5b50539ab01a2f..1efc55946158caa99573f672f8718ec65a97eebd 100644
--- a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md
+++ b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Reduce container registry data transfers
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Depending on the frequency with which images or tags are downloaded from the container registry,
data transfer can be quite high. This page offers several recommendations and tips for
diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md
index 2bc42dd38ed901fd848ff0efc0c3dcee7b689a8c..c65e3615603bf0d6172fc0e0abc5e73c74e487ef 100644
--- a/doc/user/packages/container_registry/reduce_container_registry_storage.md
+++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Reduce container registry storage
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Container registries can grow in size over time if you don't manage your registry usage. For example,
if you add a large number of images or tags:
@@ -20,11 +23,18 @@ to automatically manage your container registry usage.
## View container registry usage
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5523) in GitLab 15.7
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5523) in GitLab 15.7
+{{< /history >}}
To view the storage usage for the container registry:
@@ -83,7 +93,11 @@ the size value only changes when:
## Cleanup policy
-> - [Required permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) changed from developer to maintainer in GitLab 15.0.
+{{< history >}}
+
+- [Required permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) changed from developer to maintainer in GitLab 15.0.
+
+{{< /history >}}
The cleanup policy is a scheduled job you can use to remove tags from the container registry.
For the project where it's defined, tags matching the regex pattern are removed.
@@ -94,10 +108,13 @@ To delete the underlying layers and images that aren't associated with any tags,
### Enable the cleanup policy
-WARNING:
+{{< alert type="warning" >}}
+
For performance reasons, enabled cleanup policies are automatically disabled for projects on
GitLab.com that don't have a container image.
+{{< /alert >}}
+
### How the cleanup policy works
The cleanup policy collects all tags in the container registry and excludes tags until the only
@@ -118,12 +135,16 @@ The cleanup policy:
1. Excludes [protected tags](protected_container_tags.md).
1. Deletes the remaining tags in the list from the container registry.
-WARNING:
+{{< alert type="warning" >}}
+
On GitLab.com, the execution time for the cleanup policy is limited. Some tags may remain in
the container registry after the policy runs. The next time the policy runs, the remaining tags are included.
It may take multiple runs to delete all tags.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
GitLab Self-Managed instances support third-party container registries that comply with the
[Docker Registry HTTP API V2](https://distribution.github.io/distribution/spec/api/)
specification. However, this specification does not include a tag delete operation. Therefore, GitLab uses a
@@ -133,6 +154,7 @@ for more information. Due to possible implementation variations, this workaround
to work with all third-party registries in the same predictable way. If you use the GitLab Container
Registry, this workaround is not required because we implemented a special tag delete operation. In
this case, you can expect cleanup policies to be consistent and predictable.
+{{< /alert >}}
#### Example cleanup policy workflow
@@ -192,16 +214,22 @@ To create a cleanup policy in the UI:
| **Remove tags older than** | Remove only tags older than X days. |
| **Remove tags matching** | A regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). |
- NOTE:
- Both keep and remove regex patterns are automatically surrounded with `\A` and `\Z` anchors, so you do not need to include them. However, make sure to take this into account when choosing and testing your regex patterns.
+ {{< alert type="note" >}}
+
+Both keep and remove regex patterns are automatically surrounded with `\A` and `\Z` anchors, so you do not need to include them. However, make sure to take this into account when choosing and testing your regex patterns.
+
+ {{< /alert >}}
1. Select **Save**.
The policy runs on the scheduled interval you selected.
-NOTE:
+{{< alert type="note" >}}
+
If you edit the policy and select **Save** again, the interval is reset.
+{{< /alert >}}
+
### Regex pattern examples
Cleanup policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API.
@@ -244,7 +272,11 @@ Here are some examples of regex patterns you can use:
### Set cleanup limits to conserve resources
-> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84996) the feature flag `container_registry_expiration_policies_throttling` in GitLab 15.0.
+{{< history >}}
+
+- [Removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84996) the feature flag `container_registry_expiration_policies_throttling` in GitLab 15.0.
+
+{{< /history >}}
Cleanup policies are executed as a background process. This process is complex, and depending on the number of tags to delete,
the process can take time to finish.
@@ -369,7 +401,7 @@ the tags. To create the list and delete the tags:
the tags' names are written to the `list_o_tags.out` file:
```shell
- # Get a list of all tags in a certain container repository while considering [pagination](../../../api/rest/index.md#pagination)
+ # Get a list of all tags in a certain container repository while considering [pagination](../../../api/rest/_index.md#pagination)
echo -n "" > list_o_tags.out; for i in {1..N}; do curl --fail-with-body --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags?per_page=100&page=${i}" | jq '.[].name' | sed 's:^.\(.*\).$:\1:' >> list_o_tags.out; done
```
@@ -388,9 +420,9 @@ the tags. To create the list and delete the tags:
1. Remove any tags that you want to keep from the `list_o_tags.out` file. For example, you can use `sed` to
parse the file and remove the tags.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Linux
+ {{< tab title="Linux" >}}
```shell
# Remove the `latest` tag from the file
@@ -406,7 +438,9 @@ the tags. To create the list and delete the tags:
sed -i '/_v3$/d' list_o_tags.out
```
- :::TabTitle macOS
+ {{< /tab >}}
+
+ {{< tab title="macOS" >}}
```shell
# Remove the `latest` tag from the file
@@ -422,7 +456,9 @@ the tags. To create the list and delete the tags:
sed -i .bak '/_v3$/d' list_o_tags.out
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Double-check the `list_o_tags.out` file to make sure it contains only the tags that you want to
delete.
diff --git a/doc/user/packages/container_registry/troubleshoot_container_registry.md b/doc/user/packages/container_registry/troubleshoot_container_registry.md
index a2216b6c4310f71683b691cbbacc88e97143ef43..8c50030f29fd8a3edbec7872dfaa38003666ff5e 100644
--- a/doc/user/packages/container_registry/troubleshoot_container_registry.md
+++ b/doc/user/packages/container_registry/troubleshoot_container_registry.md
@@ -76,10 +76,13 @@ The following procedure uses these sample project names:
docker pull gitlab.example.com/org/build/sample_project/cr:v2.9.1
```
- NOTE:
- Use either a [personal access token](../../profile/personal_access_tokens.md) or a
+ {{< alert type="note" >}}
+
+Use either a [personal access token](../../profile/personal_access_tokens.md) or a
[deploy token](../../project/deploy_tokens/_index.md) to authenticate your user account.
+ {{< /alert >}}
+
1. Rename the images to match the new project name:
```shell
diff --git a/doc/user/packages/debian_repository/_index.md b/doc/user/packages/debian_repository/_index.md
index 99ad3faf991240f727a3700db0fe02564896daf3..8670308540970d457795e3b3af66d10be8912293 100644
--- a/doc/user/packages/debian_repository/_index.md
+++ b/doc/user/packages/debian_repository/_index.md
@@ -5,17 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Debian packages in the package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default.
-WARNING:
+{{< alert type="warning" >}}
+
The Debian package registry for GitLab is under development and isn't ready for production use. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6057) details the remaining
work and timelines to make it production ready. Support for [Debian packages is an experiment](../package_registry/supported_package_managers.md), and has known security vulnerabilities.
+{{< /alert >}}
+
Publish Debian packages in your project's package registry. Then install the
packages whenever you need to use them as a dependency.
@@ -40,9 +46,12 @@ Debian repository support is still a work in progress. It's gated behind a featu
[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
can opt to enable it.
-WARNING:
+{{< alert type="warning" >}}
+
Understand the [stability and security risks of enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
+{{< /alert >}}
+
To enable it:
```ruby
@@ -59,9 +68,12 @@ Feature.disable(:debian_packages)
The Debian group repository is also behind a second feature flag that is disabled by default.
-WARNING:
+{{< alert type="warning" >}}
+
Understand the [stability and security risks of enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
+{{< /alert >}}
+
To enable it:
```ruby
@@ -177,7 +189,11 @@ dput --config=dput.cf --unchecked --no-upload-log gitlab <your_package>.changes
## Upload a package with explicit distribution and component
-> - Upload with explicit distribution and component [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101838) in GitLab 15.9.
+{{< history >}}
+
+- Upload with explicit distribution and component [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101838) in GitLab 15.9.
+
+{{< /history >}}
When you don't have access to `.changes` file, you can directly upload a `.deb` by passing
distribution `codename` and target `component` as parameters with
diff --git a/doc/user/packages/dependency_proxy/_index.md b/doc/user/packages/dependency_proxy/_index.md
index d25313b02aac2ddd423dccdf32fae9f376337f4b..00c2525a3c073f7f76428525178b303e4de3465e 100644
--- a/doc/user/packages/dependency_proxy/_index.md
+++ b/doc/user/packages/dependency_proxy/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dependency proxy for container images
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The GitLab dependency proxy for container images is a local proxy you can use for your frequently-accessed
upstream images.
@@ -33,8 +36,12 @@ For a list of planned additions, view the
## Enable or turn off the dependency proxy for a group
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0.
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+{{< history >}}
+
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0.
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+
+{{< /history >}}
To enable or turn off the dependency proxy for a group:
@@ -66,8 +73,12 @@ Prerequisites:
### Authenticate with the dependency proxy for container images
-> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/276777) the feature flag `dependency_proxy_for_private_groups` in GitLab 15.0.
-> - Support for group access tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362991) in GitLab 16.3.
+{{< history >}}
+
+- [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/276777) the feature flag `dependency_proxy_for_private_groups` in GitLab 15.0.
+- Support for group access tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362991) in GitLab 16.3.
+
+{{< /history >}}
Because the dependency proxy for container images is storing Docker images in a space associated with your group,
you must authenticate with it.
@@ -75,9 +86,12 @@ you must authenticate with it.
Follow the [instructions for using images from a private registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry),
but instead of using `registry.example.com:5000`, use your GitLab domain with no port `gitlab.example.com`.
-NOTE:
+{{< alert type="note" >}}
+
[Admin Mode](../../../administration/settings/sign_in_restrictions.md#admin-mode) does not apply during authentication with the dependency proxy for container images. If you are an administrator with Admin Mode enabled, and you create a personal access token without the `admin_mode` scope, that token works even though Admin Mode is enabled.
+{{< /alert >}}
+
For example, to manually sign in:
```shell
@@ -364,11 +378,14 @@ see [issue 354826](https://gitlab.com/gitlab-org/gitlab/-/issues/354826).
### `exec format error` when running images from the dependency proxy
-NOTE:
+{{< alert type="note" >}}
+
This issue was [resolved](https://gitlab.com/gitlab-org/gitlab/-/issues/325669) in GitLab 16.3.
For self managed instances that are 16.2 or earlier, you can update your instance to 16.3
or use the workaround documented below.
+{{< /alert >}}
+
This error occurs if you try to use the dependency proxy on an ARM-based Docker install in GitLab 16.2 or earlier.
The dependency proxy only supports the x86_64 architecture when pulling an image with a specific tag.
diff --git a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md
index 234b645d390869aa95aaeee2d45ec0d844a2759a..13460338b9c06aa6c6edd10d2e7b7d682fe45904 100644
--- a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md
+++ b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Reduce dependency proxy storage for container images
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
There's no automatic removal process for blobs. Unless you delete them manually, they're stored
indefinitely. This page covers several options for clearing unused items from the cache.
@@ -25,8 +28,12 @@ image or tag from Docker Hub.
## Cleanup policies
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0.
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+{{< history >}}
+
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0.
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+
+{{< /history >}}
### Enable cleanup policies from within GitLab
diff --git a/doc/user/packages/generic_packages/_index.md b/doc/user/packages/generic_packages/_index.md
index 2680fb783fd42cbc7dc1fb2fed8876ab9d0ff626..8ba6badb9e04ef54e4ec932fc0fd788d67fa92f5 100644
--- a/doc/user/packages/generic_packages/_index.md
+++ b/doc/user/packages/generic_packages/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab generic packages repository
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the generic packages repository to publish and manage generic files, such as release binaries, in your project's package registry. This feature is particularly useful for storing and distributing artifacts that don't fit into specific package formats like npm or Maven.
@@ -67,9 +70,9 @@ Replace the placeholders in the URL with your specific values:
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle Personal access token
+{{< tab title="Personal access token" >}}
With HTTP headers:
@@ -87,7 +90,9 @@ curl --location --user "<username>:<personal_access_token>" \
"https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"
```
-:::TabTitle Project access token
+{{< /tab >}}
+
+{{< tab title="Project access token" >}}
With HTTP headers:
@@ -105,7 +110,9 @@ curl --location --user "<project_access_token_username>:project_access_token" \
"https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"
```
-:::TabTitle Deploy token
+{{< /tab >}}
+
+{{< tab title="Deploy token" >}}
With HTTP headers:
@@ -125,7 +132,9 @@ curl --location --user "<deploy_token_username>:<deploy_token>" \
Replace `<deploy_token_username>` with the username of your deploy token and `<deploy_token>` with your actual deploy token.
-:::TabTitle CI/CD job token
+{{< /tab >}}
+
+{{< tab title="CI/CD job token" >}}
These examples are for a `.gitlab-ci.yml` file. GitLab CI/CD automatically provides the `CI_JOB_TOKEN`.
@@ -153,7 +162,9 @@ publish:
"${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
Each request returns a response indicating success or failure. If your upload is successful, the response status is `201 Created`.
@@ -173,9 +184,9 @@ You should follow these best practices when you publish multiple files to the re
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle With a Bash script
+{{< tab title="With a Bash script" >}}
Create a Bash script to iterate through files and upload them:
@@ -199,7 +210,9 @@ for file in "$DIRECTORY_PATH"/*; do
done
```
-:::TabTitle With GitLab CI/CD
+{{< /tab >}}
+
+{{< tab title="With GitLab CI/CD" >}}
For automated uploads in your CI/CD pipeline, you can iterate through your files and upload them:
@@ -219,7 +232,9 @@ upload_package:
done
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Maintain directory structure
@@ -264,9 +279,9 @@ Replace the placeholders in the URL with your specific values:
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle Personal access token
+{{< tab title="Personal access token" >}}
With HTTP headers:
@@ -286,7 +301,9 @@ curl --user "<username>:<access_token>" \
--output file.txt
```
-:::TabTitle Project access token
+{{< /tab >}}
+
+{{< tab title="Project access token" >}}
With HTTP headers:
@@ -306,7 +323,9 @@ curl --user "<project_access_token_username>:<project_access_token>" \
--output file.txt
```
-:::TabTitle Deploy token
+{{< /tab >}}
+
+{{< tab title="Deploy token" >}}
With HTTP headers:
@@ -326,7 +345,9 @@ curl --user "<deploy_token_username>:<deploy_token>" \
--output file.txt
```
-:::TabTitle CI/CD job token
+{{< /tab >}}
+
+{{< tab title="CI/CD job token" >}}
These examples are for a `.gitlab-ci.yml` file. GitLab CI/CD automatically provides the `CI_JOB_TOKEN`.
@@ -358,7 +379,9 @@ download:
Each request returns a response indicating success or failure. If your upload is successful, the response status is `201 Created`.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Download multiple files
@@ -377,9 +400,9 @@ You should follow these best practices when you download multiple files from the
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle With a Bash script
+{{< tab title="With a Bash script" >}}
Create a bash script to download multiple files:
@@ -407,7 +430,9 @@ for file in "${files[@]}"; do
done
```
-:::TabTitle With GitLab CI/CD
+{{< /tab >}}
+
+{{< tab title="With GitLab CI/CD" >}}
For automated downloads in your CI/CD pipeline:
@@ -426,7 +451,9 @@ download_package:
done
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Download an entire package
@@ -459,8 +486,12 @@ done
## Disable publishing duplicate package names
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0.
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+{{< history >}}
+
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0.
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+
+{{< /history >}}
By default, when you publish a package with the same name and version as an existing package, the new files are added to the existing package. You can disable publishing duplicate file names in the settings.
@@ -475,9 +506,12 @@ To disable publishing duplicate file names:
1. In the **Generic** row of the **Duplicate packages** table, turn off the **Allow duplicates** toggle.
1. Optional. In the **Exceptions** text box, enter a regular expression that matches the names and versions of packages to allow.
-NOTE:
+{{< alert type="note" >}}
+
If **Allow duplicates** is turned on, you can specify package names and versions that should not have duplicates in the **Exceptions** text box.
+{{< /alert >}}
+
## Add a package retention policy
Implement a package retention policy to manage storage and maintain relevant versions.
diff --git a/doc/user/packages/go_proxy/_index.md b/doc/user/packages/go_proxy/_index.md
index 8694f9bb696f32f204f764365c345dd274e70191..68c546e2dc15a8e2733a9b23ed581e628abce5bb 100644
--- a/doc/user/packages/go_proxy/_index.md
+++ b/doc/user/packages/go_proxy/_index.md
@@ -5,19 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Go proxy for GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in GitLab 13.1 [with a flag](../../../administration/feature_flags.md) named `go_proxy`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in GitLab 13.1 [with a flag](../../../administration/feature_flags.md) named `go_proxy`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
See [epic 3043](https://gitlab.com/groups/gitlab-org/-/epics/3043).
+{{< /alert >}}
+
With the Go proxy for GitLab, every project in GitLab can be fetched with the
[Go proxy protocol](https://proxy.golang.org/).
@@ -80,11 +90,14 @@ and add the following text. Replace the variables in `< >` with your values.
If you make a `go get` request with invalid HTTP credentials, you receive a 404 error.
-WARNING:
+{{< alert type="warning" >}}
+
If you use an environment variable called `NETRC`, Go uses its value
as a filename and ignores `~/.netrc`. If you intend to use `~/.netrc` in
the GitLab CI **do not use `NETRC` as an environment variable name**.
+{{< /alert >}}
+
```plaintext
machine <url> login <username> password <token>
```
diff --git a/doc/user/packages/harbor_container_registry/_index.md b/doc/user/packages/harbor_container_registry/_index.md
index b5434706f34aef879ee87b5b0eb8d4cf27227166..e473dcf5a4c5a557f98b34ec4cd6cdc9967d6144 100644
--- a/doc/user/packages/harbor_container_registry/_index.md
+++ b/doc/user/packages/harbor_container_registry/_index.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Harbor registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - **Harbor Registry** [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/439494) from the **Operate** menu section to **Deploy** in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- **Harbor Registry** [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/439494) from the **Operate** menu section to **Deploy** in GitLab 17.0.
+
+{{< /history >}}
You can integrate the [Harbor container registry](../../project/integrations/harbor.md) into GitLab and use Harbor as the container registry for your GitLab project to store images.
@@ -26,9 +33,12 @@ At the project level, in the upper-right corner, you can see **CLI Commands** wh
corresponding commands to sign in, build images, and push images. **CLI Commands** is not shown at
the group level.
-NOTE:
+{{< alert type="note" >}}
+
Default settings for the Harbor integration at the project level are inherited from the group level.
+{{< /alert >}}
+
## Use images from the Harbor registry
To download and run a Harbor image hosted in the GitLab Harbor registry:
diff --git a/doc/user/packages/helm_repository/_index.md b/doc/user/packages/helm_repository/_index.md
index ac21f1a241d66cfa736de291519d24fdef7214c3..2704c38016b6995ea7f6818a300ed911e6e39ebf 100644
--- a/doc/user/packages/helm_repository/_index.md
+++ b/doc/user/packages/helm_repository/_index.md
@@ -5,16 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Helm charts in the package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The Helm chart registry for GitLab is under development and isn't ready for production use due to
limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6366) details the remaining
work and timelines to make it production ready.
+{{< /alert >}}
+
Publish Helm packages in your project's package registry. Then install the
packages whenever you need to use them as a dependency.
@@ -38,10 +44,13 @@ To authenticate to the Helm repository, you need either:
## Publish a package
-NOTE:
+{{< alert type="note" >}}
+
You can publish Helm charts with duplicate names or versions. If duplicates exist, GitLab always
returns the chart with the latest version.
+{{< /alert >}}
+
Once built, a chart can be uploaded to the desired channel with `curl` or `helm cm-push`:
- With `curl`:
@@ -100,10 +109,13 @@ upload:
## Install a package
-NOTE:
+{{< alert type="note" >}}
+
When requesting a package, GitLab considers only the 1000 most recent packages created.
For each package, only the most recent package file is returned.
+{{< /alert >}}
+
To install the latest version of a chart, use the following command:
```shell
diff --git a/doc/user/packages/maven_repository/_index.md b/doc/user/packages/maven_repository/_index.md
index 5b748128e50f8e7b47339219fef65a1ba368371d..2426e209712efb5be1a43e2e92fc54d93d635541 100644
--- a/doc/user/packages/maven_repository/_index.md
+++ b/doc/user/packages/maven_repository/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Maven packages in the package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Publish [Maven](https://maven.apache.org) artifacts in your project's package registry.
Then, install the packages whenever you need to use them as a dependency.
@@ -40,9 +43,9 @@ Update your configuration to authenticate to the Maven repository with HTTP.
You must add the authentication details to the configuration file
for your client.
-::Tabs
+{{< tabs >}}
-:::TabTitle `mvn`
+{{< tab title="`mvn`" >}}
| Token type | Name must be | Token |
| --------------------- | --------------- | ---------------------------------------------------------------------- |
@@ -50,9 +53,12 @@ for your client.
| Deploy token | `Deploy-Token` | Paste token as-is, or define an environment variable to hold the token |
| CI Job token | `Job-Token` | `${CI_JOB_TOKEN}` |
-NOTE:
+{{< alert type="note" >}}
+
The `<name>` field must be named to match the token you chose.
+{{< /alert >}}
+
Add the following section to your
[`settings.xml`](https://maven.apache.org/settings.html) file.
@@ -74,7 +80,9 @@ Add the following section to your
</settings>
```
-:::TabTitle `gradle`
+{{< /tab >}}
+
+{{< tab title="`gradle`" >}}
| Token type | Name must be | Token |
| --------------------- | --------------- | ---------------------------------------------------------------------- |
@@ -82,9 +90,12 @@ Add the following section to your
| Deploy token | `Deploy-Token` | Paste token as-is, or define an environment variable to hold the token |
| CI Job token | `Job-Token` | `System.getenv("CI_JOB_TOKEN")` |
-NOTE:
+{{< alert type="note" >}}
+
The `<name>` field must be named to match the token you chose.
+{{< /alert >}}
+
In [your `GRADLE_USER_HOME` directory](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home),
create a file `gradle.properties` with the following content:
@@ -132,15 +143,17 @@ file:
}
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
##### Basic HTTP Authentication
You can also use basic HTTP authentication to authenticate to the Maven package registry.
-::Tabs
+{{< tabs >}}
-:::TabTitle `mvn`
+{{< tab title="`mvn`" >}}
| Token type | Name must be | Token |
| --------------------- | ---------------------------- | ---------------------------------------------------------------------- |
@@ -169,7 +182,9 @@ Add the following section to your
</settings>
```
-:::TabTitle `gradle`
+{{< /tab >}}
+
+{{< tab title="`gradle`" >}}
| Token type | Name must be | Token |
| --------------------- | ---------------------------- | ---------------------------------------------------------------------- |
@@ -223,7 +238,9 @@ Add a `repositories` section to your
}
```
-:::TabTitle `sbt`
+{{< /tab >}}
+
+{{< tab title="`sbt`" >}}
| Token type | Name must be | Token |
|-----------------------|------------------------------|------------------------------------------------------------------------|
@@ -235,9 +252,12 @@ Authentication for [SBT](https://www.scala-sbt.org/index.html) is based on
[basic HTTP Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
You must to provide a name and a password.
-NOTE:
+{{< alert type="note" >}}
+
The name field must be named to match the token you chose.
+{{< /alert >}}
+
To install a package from the Maven GitLab package registry by using `sbt`, you must configure
a [Maven resolver](https://www.scala-sbt.org/1.x/docs/Resolvers.html#Maven+resolvers).
If you're accessing a private or an internal project or group, you need to set up
@@ -261,7 +281,9 @@ In this example:
scheme or the port. Example: `gitlab.example.com`.
- `<name>` and `<token>` are explained in the table above.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Naming convention
@@ -300,9 +322,9 @@ For the instance-level endpoint, ensure the relevant section of your `pom.xml` i
You must add publishing details to the configuration file for your client.
-::Tabs
+{{< tabs >}}
-:::TabTitle `mvn`
+{{< tab title="`mvn`" >}}
No matter which endpoint you choose, you must have:
@@ -334,7 +356,9 @@ The relevant `repository` section of your `pom.xml` in Maven should look like th
- The `<your_endpoint_url>` depends on which [endpoint](#endpoint-urls) you choose.
- Replace `gitlab.example.com` with your domain name.
-:::TabTitle `gradle`
+{{< /tab >}}
+
+{{< tab title="`gradle`" >}}
To publish a package by using Gradle:
@@ -409,21 +433,26 @@ To publish a package by using Gradle:
}
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Publish a package
-WARNING:
+{{< alert type="warning" >}}
+
Using the `DeployAtEnd` option can cause an upload to be rejected with `400 bad request {"message":"Validation failed: Name has already been taken"}`. For more details,
see [issue 424238](https://gitlab.com/gitlab-org/gitlab/-/issues/424238).
+{{< /alert >}}
+
After you have set up the [authentication](#authenticate-to-the-package-registry)
and [chosen an endpoint for publishing](#naming-convention),
publish a Maven package to your project.
-::Tabs
+{{< tabs >}}
-:::TabTitle `mvn`
+{{< tab title="`mvn`" >}}
To publish a package by using Maven:
@@ -445,7 +474,9 @@ The message should also show that the package was published to the correct locat
Uploading to gitlab-maven: https://example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar
```
-:::TabTitle `gradle`
+{{< /tab >}}
+
+{{< tab title="`gradle`" >}}
Run the publish task:
@@ -455,7 +486,9 @@ gradle publish
Go to your project's **Packages and registries** page and view the published packages.
-:::TabTitle `sbt`
+{{< /tab >}}
+
+{{< tab title="`sbt`" >}}
Configure the `publishTo` setting in your `build.sbt` file:
@@ -484,13 +517,18 @@ correct location:
[info] published my-project_2.12 to https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/my-project_2.12/0.1.1-SNAPSHOT/my-project_2.12-0.1.1-SNAPSHOT.pom
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
+
+{{< alert type="note" >}}
-NOTE:
If you protect a Maven package before publishing it, the package will be rejected with a `403 Forbidden` error and an `Authorization failed` error message.
Ensure the Maven package is not protected when publishing.
For more information about package protection rules, see [how to protect a package](../../../user/packages/package_registry/package_protection_rules.md#protect-a-package).
+{{< /alert >}}
+
## Install a package
To install a package from the GitLab package registry, you must configure
@@ -504,9 +542,9 @@ a package, the most recently-published package is retrieved.
In case there are not enough permissions to read the most recently-published
package than `403 Forbidden` is returning.
-::Tabs
+{{< tabs >}}
-:::TabTitle `mvn`
+{{< tab title="`mvn`" >}}
To install a package by using `mvn install`:
@@ -544,16 +582,21 @@ You can also install packages by using the Maven [`dependency:get` command](http
- `<gitlab endpoint url>` is the URL of the GitLab [endpoint](#endpoint-urls).
- `<path to settings.xml>` is the path to the `settings.xml` file that contains the [authentication details](#edit-the-client-configuration).
-NOTE:
+{{< alert type="note" >}}
+
The repository IDs in the command(`gitlab-maven`) and the `settings.xml` file must match.
+{{< /alert >}}
+
The message should show that the package is downloading from the package registry:
```shell
Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom
```
-:::TabTitle `gradle`
+{{< /tab >}}
+
+{{< tab title="`gradle`" >}}
To install a package by using `gradle`:
@@ -581,7 +624,9 @@ To install a package by using `gradle`:
gradle install
```
-:::TabTitle `sbt`
+{{< /tab >}}
+
+{{< tab title="`sbt`" >}}
To install a package by using `sbt`:
@@ -597,11 +642,17 @@ To install a package by using `sbt`:
sbt update
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Proxy downloads for Maven packages
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/507768) in GitLab 17.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/507768) in GitLab 17.8.
+
+{{< /history >}}
The GitLab Maven package registry uses [remote included checksums](https://maven.apache.org/resolver/expected-checksums.html#remote-included-checksums).
When you download a file, the registry proxies the file and sends both the file and its related checksums to Maven clients in a single request.
@@ -616,9 +667,12 @@ Due to technical constraints, when you use object storage, the Maven package reg
setting in the object storage configuration for `packages`.
Instead, proxy download is always enabled for Maven package registry downloads.
-NOTE:
+{{< alert type="note" >}}
+
If you don't use object storage, this behavior has no impact on your instance.
+{{< /alert >}}
+
## CI/CD integration for Maven packages
You can use CI/CD to automatically build, test, and publish Maven packages.
@@ -866,8 +920,12 @@ To delete older package versions, consider using the Packages API or the UI.
### Do not allow duplicate Maven packages
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0.
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+{{< history >}}
+
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0.
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+
+{{< /history >}}
To prevent users from publishing duplicate Maven packages, you can use the [GraphQl API](../../../api/graphql/reference/_index.md#packagesettings) or the UI.
@@ -878,20 +936,30 @@ In the UI:
1. In the **Maven** row of the **Duplicate packages** table, turn off the **Allow duplicates** toggle.
1. Optional. In the **Exceptions** text box, enter a regular expression that matches the names and versions of packages to allow.
-NOTE:
+{{< alert type="note" >}}
+
If **Allow duplicates** is turned on, you can specify package names and versions that should not have duplicates in the **Exceptions** text box.
+{{< /alert >}}
+
Your changes are automatically saved.
### Request forwarding to Maven Central
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85299) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. Disabled by default.
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85299) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. Disabled by default.
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
When a Maven package is not found in the package registry, the request is forwarded
to [Maven Central](https://search.maven.org/).
@@ -947,9 +1015,9 @@ section to your `settings.xml`:
After you have configured your repository to use the Package Repository for Maven,
you can configure GitLab CI/CD to build new packages automatically.
-::Tabs
+{{< tabs >}}
-:::TabTitle `mvn`
+{{< tab title="`mvn`" >}}
You can create a new package each time the default branch is updated.
@@ -1019,7 +1087,9 @@ user's home location. In this example:
- The user is `root`, because the job runs in a Docker container.
- Maven uses the configured CI/CD variables.
-:::TabTitle `gradle`
+{{< /tab >}}
+
+{{< tab title="`gradle`" >}}
You can create a package each time the default branch
is updated.
@@ -1041,7 +1111,9 @@ is updated.
When the pipeline is successful, the Maven package is created.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Version validation
@@ -1091,20 +1163,24 @@ that you can use when performing tasks with GitLab CI/CD.
The GitLab Maven repository supports the following CLI commands:
-::Tabs
+{{< tabs >}}
-:::TabTitle `mvn`
+{{< tab title="`mvn`" >}}
- `mvn deploy`: Publish your package to the package registry.
- `mvn install`: Install packages specified in your Maven project.
- `mvn dependency:get`: Install a specific package.
-:::TabTitle `gradle`
+{{< /tab >}}
+
+{{< tab title="`gradle`" >}}
- `gradle publish`: Publish your package to the package registry.
- `gradle install`: Install packages specified in your Gradle project.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Troubleshooting
@@ -1123,21 +1199,25 @@ To resolve many common issues, try these steps:
To improve performance, clients cache files related to a package. If you encounter issues, clear
the cache with these commands:
-::Tabs
+{{< tabs >}}
-:::TabTitle `mvn`
+{{< tab title="`mvn`" >}}
```shell
rm -rf ~/.m2/repository
```
-:::TabTitle `gradle`
+{{< /tab >}}
+
+{{< tab title="`gradle`" >}}
```shell
rm -rf ~/.gradle/caches # Or replace ~/.gradle with your custom GRADLE_USER_HOME
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Review network trace logs
@@ -1152,9 +1232,12 @@ mvn deploy \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace
```
-WARNING:
+{{< alert type="warning" >}}
+
When you set these options, all network requests are logged and a large amount of output is generated.
+{{< /alert >}}
+
### Verify your Maven settings
If you encounter issues within CI/CD that relate to the `settings.xml` file, try adding
diff --git a/doc/user/packages/npm_registry/_index.md b/doc/user/packages/npm_registry/_index.md
index e12a47575bb1c729eafab26177a337e2cc28a507..ef6c02db5d8e8e934311e8e81c6bdc0292cfb579 100644
--- a/doc/user/packages/npm_registry/_index.md
+++ b/doc/user/packages/npm_registry/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: npm packages in the package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Node Package Manager (npm) is the default package manager for JavaScript and Node.js. Developers use npm to share and reuse code, manage dependencies, and streamline project workflows. In GitLab, npm packages play a crucial role in the software development lifecycle.
@@ -46,15 +49,18 @@ Create or edit the `.npmrc` file in the same directory as your `package.json`. I
//<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"
```
-WARNING:
+{{< alert type="warning" >}}
+
Never hardcode GitLab tokens (or any tokens) directly in `.npmrc` files or any other files that can
be committed to a repository.
+{{< /alert >}}
+
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle For an instance
+{{< tab title="For an instance" >}}
```shell
//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
@@ -62,7 +68,9 @@ For example:
Replace `<domain_name>` with your domain name. For example, `gitlab.com`.
-:::TabTitle For a group
+{{< /tab >}}
+
+{{< tab title="For a group" >}}
```shell
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"
@@ -73,7 +81,9 @@ Make sure to replace:
- `<domain_name>` with your domain name. For example, `gitlab.com`.
- `<group_id>` with the group ID from the group home page.
-:::TabTitle For a project
+{{< /tab >}}
+
+{{< tab title="For a project" >}}
```shell
//<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"
@@ -84,7 +94,9 @@ Make sure to replace:
- `<domain_name>` with your domain name. For example, `gitlab.com`.
- `<project_id>` with the project ID from the [project overview page](../../project/working_with_projects.md#access-a-project-by-using-the-project-id).
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### With `npm config set`
@@ -102,9 +114,9 @@ are not supported.
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle For an instance
+{{< tab title="For an instance" >}}
```shell
npm config set -- //<domain_name>/api/v4/packages/npm/:_authToken=<token>
@@ -115,7 +127,9 @@ Make sure to replace:
- `<domain_name>` with your domain name. For example, `gitlab.com`.
- `<token>` with your deploy token, group access token, project access token, or personal access token.
-:::TabTitle For a group
+{{< /tab >}}
+
+{{< tab title="For a group" >}}
```shell
npm config set -- //<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken=<token>
@@ -127,7 +141,9 @@ Make sure to replace:
- `<group_id>` with the group ID from the group home page.
- `<token>` with your deploy token, group access token, project access token, or personal access token.
-:::TabTitle For a project
+{{< /tab >}}
+
+{{< tab title="For a project" >}}
```shell
npm config set -- //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken=<token>
@@ -139,7 +155,9 @@ Make sure to replace:
- `<project_id>` with the project ID from the [project overview page](../../project/working_with_projects.md#access-a-project-by-using-the-project-id).
- `<token>` with your deploy token, group access token, project access token, or personal access token.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Set up the registry URL
@@ -151,11 +169,14 @@ Before configuring the registry URL, it's important to understand the scope of d
- `npm config set` command: This modifies the global npm configuration and affects all npm commands run on your system.
- `publishConfig` in `package.json`: This configuration is specific to the package and only applies when publishing that package.
-WARNING:
+{{< alert type="warning" >}}
+
Running `npm config set` changes the global npm configuration. The change affects all npm commands
run on your system, regardless of the current working directory. Be cautious when using this method,
especially on shared systems.
+{{< /alert >}}
+
### For publishing packages
When publishing packages, use the project endpoint:
@@ -167,9 +188,9 @@ https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
Replace `gitlab.example.com` with your GitLab instance's domain and `<project_id>` with your project's ID.
To configure this URL, use one of these methods:
-::Tabs
+{{< tabs >}}
-:::TabTitle `.npmrc` file
+{{< tab title="`.npmrc` file" >}}
Create or edit the `.npmrc` file in your project root:
@@ -178,7 +199,9 @@ Create or edit the `.npmrc` file in your project root:
//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"
```
-:::TabTitle `npm config`
+{{< /tab >}}
+
+{{< tab title="`npm config`" >}}
Use the `npm config set` command:
@@ -186,7 +209,9 @@ Use the `npm config set` command:
npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
```
-:::TabTitle `package.json`
+{{< /tab >}}
+
+{{< tab title="`package.json`" >}}
Add a `publishConfig` section to your `package.json`:
@@ -198,7 +223,9 @@ Add a `publishConfig` section to your `package.json`:
}
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
Replace `@scope` with your package's scope.
@@ -207,9 +234,9 @@ Replace `@scope` with your package's scope.
When you install packages, you can use project, group, or instance endpoints. The URL structure varies accordingly.
To configure these URLs, use one of these methods:
-::Tabs
+{{< tabs >}}
-:::TabTitle `.npmrc` file
+{{< tab title="`.npmrc` file" >}}
Create or edit the `.npmrc` file in your project root. Use the appropriate URL based on your needs:
@@ -231,7 +258,9 @@ Create or edit the `.npmrc` file in your project root. Use the appropriate URL b
@scope:registry=https://gitlab.example.com/api/v4/packages/npm/
```
-:::TabTitle `npm config`
+{{< /tab >}}
+
+{{< tab title="`npm config`" >}}
Use the `npm config set` command with the appropriate URL:
@@ -253,7 +282,9 @@ Use the `npm config set` command with the appropriate URL:
npm config set @scope:registry=https://gitlab.example.com/api/v4/packages/npm/
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
Replace `gitlab.example.com`, `<project_id>`, `<group_id>`, and `@scope` with the appropriate values for your GitLab instance and package.
@@ -319,10 +350,13 @@ When publishing by using a CI/CD pipeline, you can use the
to authenticate with your project's package registry. GitLab uses these variables to create a `.npmrc` file
for authentication during execution of your CI/CD job.
-NOTE:
+{{< alert type="note" >}}
+
When you generate the `.npmrc` file, do not specify the port after `${CI_SERVER_HOST}` if it is a default port.
`http` URLs default to `80`, and `https` URLs default to `443`.
+{{< /alert >}}
+
In the GitLab project containing your `package.json`, edit or create a `.gitlab-ci.yml` file. For example:
```yaml
@@ -378,8 +412,12 @@ Prerequisites:
### Install from a group
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299834) in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `npm_group_level_endpoints`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121837) in GitLab 16.1. Feature flag `npm_group_level_endpoints` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299834) in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `npm_group_level_endpoints`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121837) in GitLab 16.1. Feature flag `npm_group_level_endpoints` removed.
+
+{{< /history >}}
1. [Authenticate to the package registry](#authenticate-to-the-package-registry).
1. Set the registry:
@@ -419,8 +457,12 @@ Prerequisites:
### Package forwarding to npmjs.com
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in GitLab 12.9.
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in GitLab 12.9.
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+
+{{< /history >}}
When an npm package is not found in the package registry, GitLab responds with an HTTP redirect so the requesting client can resend the request to [npmjs.com](https://www.npmjs.com/).
@@ -432,7 +474,11 @@ Improvements are tracked in [epic 3608](https://gitlab.com/groups/gitlab-org/-/e
## Deprecate a package
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396763) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396763) in GitLab 16.0.
+
+{{< /history >}}
You can deprecate a package so that a deprecation warning displays when the package is fetched.
@@ -522,7 +568,11 @@ npm install @scope/package@my-tag # Install a specific tag
#### From CI/CD
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) in GitLab 15.10.
+
+{{< /history >}}
You can use a [`CI_JOB_TOKEN`](../../../ci/jobs/ci_job_token.md) or [deploy token](../../project/deploy_tokens/_index.md)
to run `npm dist-tag` commands in a GitLab CI/CD job.
@@ -600,10 +650,13 @@ from a user that has access to all the groups or individual projects:
@group-2:registry=https://gitlab.example.com/api/v4/packages/npm/
```
-WARNING:
+{{< alert type="warning" >}}
+
Personal access tokens must be treated carefully. Read our [token security considerations](../../../security/tokens/_index.md#security-considerations)
for guidance on managing personal access tokens (for example, setting a short expiry and using minimal scopes).
+{{< /alert >}}
+
### `npm publish` targets default npm registry (`registry.npmjs.org`)
Ensure that your package scope is set consistently in your `package.json` and `.npmrc` files.
diff --git a/doc/user/packages/nuget_repository/_index.md b/doc/user/packages/nuget_repository/_index.md
index 74966de408f038e667075eba392470cc3eb4b677..6bd204a1955cd568daf4c1048acd412322370897 100644
--- a/doc/user/packages/nuget_repository/_index.md
+++ b/doc/user/packages/nuget_repository/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: NuGet packages in the package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Publish NuGet packages in your project's package registry. Then, install the
packages whenever you need to use them as a dependency.
@@ -38,10 +41,13 @@ When asking for versions of a given NuGet package name, the GitLab package regis
Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future.
-WARNING:
+{{< alert type="warning" >}}
+
Because of how NuGet handles credentials, the package registry rejects anonymous requests on the group-level endpoint.
To work around this limitation, set up [authentication](#add-the-package-registry-as-a-source-for-nuget-packages).
+{{< /alert >}}
+
## Add the package registry as a source for NuGet packages
To publish and install packages to the package registry, you must add the
@@ -331,7 +337,11 @@ nuget push <package_file> -Source <source_name>
### Publish a package with the .NET CLI
-> - Publishing a package with `--api-key` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214674) in GitLab 16.1.
+{{< history >}}
+
+- Publishing a package with `--api-key` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214674) in GitLab 16.1.
+
+{{< /history >}}
Prerequisites:
@@ -401,7 +411,11 @@ updated:
### Publish a NuGet package with Chocolatey CLI
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416404) in GitLab 16.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416404) in GitLab 16.2.
+
+{{< /history >}}
Prerequisites:
@@ -431,9 +445,13 @@ the existing package is overwritten.
### Do not allow duplicate NuGet packages
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293748) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `nuget_duplicates_option`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/419078) in GitLab 16.6. Feature flag `nuget_duplicates_option` removed.
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293748) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `nuget_duplicates_option`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/419078) in GitLab 16.6. Feature flag `nuget_duplicates_option` removed.
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+
+{{< /history >}}
To prevent users from publishing duplicate NuGet packages, you can use the [GraphQl API](../../../api/graphql/reference/_index.md#packagesettings) or the UI.
@@ -444,15 +462,21 @@ In the UI:
1. In the **NuGet** row of the **Duplicate packages** table, turn off the **Allow duplicates** toggle.
1. Optional. In the **Exceptions** text box, enter a regular expression that matches the names and versions of packages to allow.
-NOTE:
+{{< alert type="note" >}}
+
If **Allow duplicates** is turned on, you can specify package names and versions that should not have duplicates in the **Exceptions** text box.
+{{< /alert >}}
+
Your changes are automatically saved.
-WARNING:
+{{< alert type="warning" >}}
+
If the .nuspec file isn't located in the root of the package or the beginning of the archive, the package might
not be recognized as a duplicate right away. However, it will be rejected later, and an error will be shown in the UI.
+{{< /alert >}}
+
## Install packages
If multiple packages have the same name and version, when you install
@@ -463,11 +487,14 @@ To install a NuGet package from the package registry, you must first
### Install a package with the NuGet CLI
-WARNING:
+{{< alert type="warning" >}}
+
By default, `nuget` checks the official source at `nuget.org` first. If you have
a NuGet package in the package registry with the same name as a package at
`nuget.org`, you must specify the source name to install the correct package.
+{{< /alert >}}
+
Install the latest version of a package by running this command:
```shell
@@ -483,11 +510,14 @@ nuget install <package_id> -OutputDirectory <output_directory> \
### Install a package with the .NET CLI
-WARNING:
+{{< alert type="warning" >}}
+
If you have a package in the package registry with the same name as a package at
a different source, verify the order in which `dotnet` checks sources during
install. This is defined in the `nuget.config` file.
+{{< /alert >}}
+
Install the latest version of a package by running this command:
```shell
@@ -500,7 +530,11 @@ dotnet add package <package_id> \
### Install a package using NuGet v2 feed
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416405) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416405) in GitLab 16.5.
+
+{{< /history >}}
Prerequisites:
@@ -549,11 +583,18 @@ choco upgrade MyPackage -Source gitlab -Version 1.0.3
## Delete a package
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38275) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38275) in GitLab 16.5.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
Deleting a package is a permanent action that cannot be undone.
+{{< /alert >}}
+
Prerequisites:
- You must have the [Maintainer](../../permissions.md#project-members-permissions) role or higher in the project.
@@ -588,7 +629,11 @@ nuget push My.Package.snupkg -Source <source_name>
### Use the package registry as a symbol server
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416178) in GitLab 16.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416178) in GitLab 16.7.
+
+{{< /history >}}
GitLab can consume symbol files from the NuGet package registry,
so you can use the package registry as a symbol server.
@@ -634,7 +679,11 @@ Note that:
## Supported CLI commands
-> - `nuget delete` and `dotnet nuget delete` commands [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38275) in GitLab 16.5.
+{{< history >}}
+
+- `nuget delete` and `dotnet nuget delete` commands [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38275) in GitLab 16.5.
+
+{{< /history >}}
The GitLab NuGet repository supports the following commands for the NuGet CLI (`nuget`) and the .NET
CLI (`dotnet`):
diff --git a/doc/user/packages/package_registry/_index.md b/doc/user/packages/package_registry/_index.md
index 312d183295f79f0c876cdd51f9c07c927db26e60..c1f4ddb11e9e870e04990a86d113c4c91ca7d550 100644
--- a/doc/user/packages/package_registry/_index.md
+++ b/doc/user/packages/package_registry/_index.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3.
+
+{{< /history >}}
With the GitLab package registry, you can use GitLab as a private or public registry for a variety
of [supported package managers](supported_package_managers.md).
@@ -64,10 +71,13 @@ For most package types, the following credential types are valid:
- If your organization uses two factor authentication (2FA), you must use a personal access token with the scope set to `api`.
- If you are publishing a package by using CI/CD pipelines, you must use a CI job token.
-NOTE:
+{{< alert type="note" >}}
+
If the "Package registry" feature is turned off for your project at **Settings > General > Visibility, project features, permissions**, you will receive a 403 Forbidden response.
Accessing the package registry with a deploy token is not available when external authorization is enabled.
+{{< /alert >}}
+
## Use GitLab CI/CD
You can use [GitLab CI/CD](../../../ci/_index.md) to build or import packages into
@@ -148,10 +158,14 @@ Registry disables all package registry operations.
### Allow anyone to pull from package registry
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385994) in GitLab 15.7.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/468058) in GitLab 17.4 to support NuGet group endpoints.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/468059) in GitLab 17.5 to support Maven group endpoint.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/468062) in GitLab 17.5 to support Terraform module namespace endpoints.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385994) in GitLab 15.7.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/468058) in GitLab 17.4 to support NuGet group endpoints.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/468059) in GitLab 17.5 to support Maven group endpoint.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/468062) in GitLab 17.5 to support Terraform module namespace endpoints.
+
+{{< /history >}}
To allow anyone to pull from the package registry, regardless of project visibility:
diff --git a/doc/user/packages/package_registry/dependency_proxy/_index.md b/doc/user/packages/package_registry/dependency_proxy/_index.md
index b2345501dd6f847102ca1fdc03548178a4f11fb5..a8a6f03db12a032fd4a636f6aabbf894396b08e5 100644
--- a/doc/user/packages/package_registry/dependency_proxy/_index.md
+++ b/doc/user/packages/package_registry/dependency_proxy/_index.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Dependency proxy for packages
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3610) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `packages_dependency_proxy_maven`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/415218) in GitLab 16.8. Feature flag `packages_dependency_proxy_maven` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3610) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `packages_dependency_proxy_maven`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/415218) in GitLab 16.8. Feature flag `packages_dependency_proxy_maven` removed.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
The dependency proxy is in [beta](../../../../policy/development_stages_support.md#beta). Review the documentation carefully before you use this feature.
+{{< /alert >}}
+
The GitLab dependency proxy for packages is a local proxy for frequently pulled packages.
It is implemented as a pull-through cache that works at the project level.
@@ -57,19 +67,26 @@ Advanced caching support depends on how the upstream package registry
responds to dependency proxy requests, and on
which package format you use.
-::Tabs
+{{< tabs >}}
-:::TabTitle Maven
+{{< tab title="Maven" >}}
| Package registry | Advanced caching supported? |
|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
-| [GitLab](../../maven_repository/_index.md) | **{check-circle}** Yes |
-| [Maven Central](https://mvnrepository.com/repos/central) | **{check-circle}** Yes |
-| [Artifactory](https://jfrog.com/integration/maven-repository/) | **{check-circle}** Yes |
-| [Sonatype Nexus](https://help.sonatype.com/en/maven-repositories.html) | **{check-circle}** Yes |
-| [GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) | **{dotted-circle}** No |
-::EndTabs
+| [GitLab](../../maven_repository/_index.md) | {{< icon name="check-circle" >}} Yes |
+
+| [Maven Central](https://mvnrepository.com/repos/central) | {{< icon name="check-circle" >}} Yes |
+
+| [Artifactory](https://jfrog.com/integration/maven-repository/) | {{< icon name="check-circle" >}} Yes |
+
+| [Sonatype Nexus](https://help.sonatype.com/en/maven-repositories.html) | {{< icon name="check-circle" >}} Yes |
+
+| [GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) | {{< icon name="dotted-circle" >}} No |
+
+{{< /tab >}}
+
+{{< /tabs >}}
### Permissions
@@ -85,15 +102,15 @@ The dependency proxy uses the [same permissions as the package registry](../_ind
| Project visibility | Minimum [role](../../../permissions.md#roles) | Can read package files? | Can write package files? | Behavior |
|--------------------|-------------------------------------------------------|-------------------------|--------------------------|----------|
-| Public | Anonymous | **{dotted-circle}** No | **{dotted-circle}** No | Request rejected. |
-| Public | Guest | **{check-circle}** Yes | **{dotted-circle}** No | Package file returned from either the cache or the remote registry. |
-| Public | Developer | **{check-circle}** Yes | **{check-circle}** Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. |
-| Internal | Anonymous | **{dotted-circle}** No | **{dotted-circle}** No | Request rejected |
-| Internal | Guest | **{check-circle}** Yes | **{dotted-circle}** No | Package file returned from either the cache or the remote registry. |
-| Internal | Developer | **{check-circle}** Yes | **{check-circle}** Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. |
-| Private | Anonymous | **{dotted-circle}** No | **{dotted-circle}** No | Request rejected |
-| Private | Reporter | **{check-circle}** Yes | **{dotted-circle}** No | Package file returned from either the cache or the remote registry. |
-| Private | Developer | **{check-circle}** Yes | **{check-circle}** Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. |
+| Public | Anonymous | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Request rejected. |
+| Public | Guest | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Package file returned from either the cache or the remote registry. |
+| Public | Developer | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. |
+| Internal | Anonymous | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Request rejected |
+| Internal | Guest | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Package file returned from either the cache or the remote registry. |
+| Internal | Developer | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. |
+| Private | Anonymous | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Request rejected |
+| Private | Reporter | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Package file returned from either the cache or the remote registry. |
+| Private | Developer | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. |
At a minimum, any user who can use the dependency proxy can also use the project's package registry.
@@ -122,9 +139,9 @@ To configure the client:
1. Complete the configuration for your client:
-::Tabs
+{{< tabs >}}
-:::TabTitle mvn
+{{< tab title="mvn" >}}
[Basic HTTP authentication](../../maven_repository/_index.md#basic-http-authentication) is accepted.
However, you should use the [custom HTTP header authentication](../../maven_repository/_index.md#custom-http-header),
@@ -149,7 +166,9 @@ Where:
By default, Maven Central is checked first through the [Super POM](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Super_POM).
However, you might want to force `mvn` to check the GitLab endpoint first. To do this, follow the instructions from the [request forward](../../maven_repository/_index.md#additional-configuration-for-mvn).
-:::TabTitle gradle
+{{< /tab >}}
+
+{{< tab title="gradle" >}}
Add a `repositories` section to your [`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) file.
@@ -194,7 +213,9 @@ In this example:
- `<project_id>` is the ID of the project to be used as a dependency proxy.
- `REPLACE_WITH_NAME` is explained in the [Basic HTTP authentication](../../maven_repository/_index.md#basic-http-authentication) section.
-:::TabTitle sbt
+{{< /tab >}}
+
+{{< tab title="sbt" >}}
In your [`build.sbt`](https://www.scala-sbt.org/1.x/docs/Directories.html#sbt+build+definition+files), add the following lines:
@@ -210,7 +231,9 @@ In this example:
- `<host>` is the host present in the `<endpoint url>` without the protocol scheme or the port. Example: `gitlab.example.com`.
- `<name>` and `<token>` are explained in the [Basic HTTP authentication](../../maven_repository/_index.md#basic-http-authentication) section.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Configure the remote registry
@@ -226,9 +249,9 @@ To set those parameters:
1. Expand **Package registry**.
1. Under **Dependency Proxy**, complete the form for your package format:
-::Tabs
+{{< tabs >}}
-:::TabTitle Maven
+{{< tab title="Maven" >}}
Any Maven package registry can be connected to the dependency proxy. You can
authorize the connection with the Maven package registry username and password.
@@ -242,7 +265,9 @@ in the form:
You must either set both the username and password, or leave both fields empty.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Troubleshooting
@@ -257,9 +282,9 @@ However, you might encounter one of the following responses:
- `502 Bad Gateway` - The remote package registry could not fulfill the file request. Verify the [dependency proxy settings](#configure-the-remote-registry).
- `504 Gateway Timeout` - The remote package registry timed out. Verify the [dependency proxy settings](#configure-the-remote-registry).
-::Tabs
+{{< tabs >}}
-:::TabTitle Maven
+{{< tab title="Maven" >}}
```shell
curl --fail-with-body --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/<group id and artifact id>/<version>/<file_name>"
@@ -283,4 +308,6 @@ The request to manually pull a package is:
curl --fail-with-body --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/com/my_company/my_package/1.2.3/my_package-1.2.3.pom"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/user/packages/package_registry/package_protection_rules.md b/doc/user/packages/package_registry/package_protection_rules.md
index 0f187948e58326cd13fcdf9fbda631ea3d11fba1..17d7b3db3f2d0ac7fc823629d5e8d8941053a132 100644
--- a/doc/user/packages/package_registry/package_protection_rules.md
+++ b/doc/user/packages/package_registry/package_protection_rules.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Protected packages
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416395) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `packages_protected_packages`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
-> - The protection rule setting **Push protected up to access level** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/416382) to **Minimum access level for push** in GitLab 17.1
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/472655) in GitLab 17.5.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472655) in GitLab 17.6. Feature flag `packages_protected_packages` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416395) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `packages_protected_packages`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+- The protection rule setting **Push protected up to access level** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/416382) to **Minimum access level for push** in GitLab 17.1
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/472655) in GitLab 17.5.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472655) in GitLab 17.6. Feature flag `packages_protected_packages` removed.
+
+{{< /history >}}
By default, any user with at least the Developer role can create,
edit, and delete packages. Add a package protection rule to restrict
@@ -30,7 +37,11 @@ When a package is protected, the default behavior enforces these restrictions on
## Protect a package
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140473) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140473) in GitLab 16.9.
+
+{{< /history >}}
Prerequisites:
@@ -68,7 +79,11 @@ If at least one protection rule applies to the package, the package is protected
## Delete a package protection rule and unprotect a package
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140483) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140483) in GitLab 16.10.
+
+{{< /history >}}
Prerequisites:
@@ -79,7 +94,7 @@ To unprotect a package:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > Packages and registries**.
1. Expand **Package registry**.
-1. Under **Protected packages**, next to the protection rule you want to delete, select **Delete** (**{remove}**).
+1. Under **Protected packages**, next to the protection rule you want to delete, select **Delete** ({{< icon name="remove" >}}).
1. On the confirmation dialog, select **Delete**.
The package protection rule is deleted, and does not appear in the settings.
diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md
index 194902a124bd5ae50479e72c51e0c4fae88cb03f..8f8432ca6ed495e1df6264d50d98f18a9f3942f8 100644
--- a/doc/user/packages/package_registry/reduce_package_registry_storage.md
+++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Reduce package registry storage
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Without cleanup, package registries become large over time. When a large number of packages and
their assets are added:
@@ -59,7 +62,11 @@ The package assets are permanently deleted.
## Cleanup policy
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346153) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346153) in GitLab 15.2.
+
+{{< /history >}}
Depending on the number of packages to remove, the process of manually deleting the packages can take a long time to finish.
A cleanup policy defines a set of rules that, applied to a project, defines which package assets you can automatically delete.
@@ -72,9 +79,12 @@ By default, the packages cleanup policy is disabled. To enable it:
1. Expand **Package registry**.
1. Under **Manage storage used by package assets**, set the rules appropriately.
-NOTE:
+{{< alert type="note" >}}
+
To access these project settings, you must be at least a maintainer on the related project.
+{{< /alert >}}
+
### Available rules
- `Number of duplicated assets to keep`: The number of duplicated assets to keep. Some package formats allow you
diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md
index 5fac40c39874e4d733931d315823f95d3a89f333..8ec8e0b7d6da012a99c7b716b08695e1bf93fa3c 100644
--- a/doc/user/packages/package_registry/supported_functionality.md
+++ b/doc/user/packages/package_registry/supported_functionality.md
@@ -10,9 +10,12 @@ and pulling packages, request forwarding, managing duplicates, and authenticatio
## Publishing packages
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Packages can be published to your project, group, or instance.
@@ -35,9 +38,12 @@ Packages can be published to your project, group, or instance.
## Pulling packages
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Packages can be pulled from your project, group, or instance.
@@ -60,9 +66,12 @@ Packages can be pulled from your project, group, or instance.
## Forwarding requests
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Requests for packages not found in your GitLab project are forwarded to the public registry. For example, Maven Central, npmjs, or PyPI.
@@ -123,9 +132,12 @@ You can use GitLab pipelines to import packages from other repositories, such as
## Allow or prevent duplicates
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
By default, the GitLab package registry either allows or prevents duplicates based on the default of that specific package manager format.
@@ -148,9 +160,12 @@ By default, the GitLab package registry either allows or prevents duplicates bas
## Authentication tokens
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab tokens are used to authenticate with the GitLab package registry.
@@ -175,9 +190,12 @@ The following tokens are supported:
## Authentication protocols
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The following authentication protocols are supported:
@@ -202,9 +220,12 @@ The following authentication protocols are supported:
## Supported hash types
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the [API](../../../api/packages.md).
diff --git a/doc/user/packages/package_registry/supported_package_managers.md b/doc/user/packages/package_registry/supported_package_managers.md
index 1cb758dd0ffb0b6024f7502b45365f7c57ccd114..ddd97708bf92be2428cc11f800c15e9b11f27734 100644
--- a/doc/user/packages/package_registry/supported_package_managers.md
+++ b/doc/user/packages/package_registry/supported_package_managers.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Supported package managers
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
Not all package manager formats are ready for production use.
+{{< /alert >}}
+
The package registry supports the following package manager types:
| Package type | Status |
diff --git a/doc/user/packages/pypi_repository/_index.md b/doc/user/packages/pypi_repository/_index.md
index e3595bba05c68b4bc17c1cc1f490fc1dda1578c7..b946d23ebacaf82fb8a4be236c97b25d504285a5 100644
--- a/doc/user/packages/pypi_repository/_index.md
+++ b/doc/user/packages/pypi_repository/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: PyPI packages in the package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Python Package Index (PyPI) is the official third-party software repository for Python.
Use the GitLab PyPI package registry to publish and share Python packages in your GitLab projects,
@@ -44,9 +47,9 @@ To authenticate with a GitLab token:
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle With a personal access token
+{{< tab title="With a personal access token" >}}
```yaml
run:
@@ -60,7 +63,9 @@ run:
- python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*
```
-:::TabTitle With a deploy token
+{{< /tab >}}
+
+{{< tab title="With a deploy token" >}}
```yaml
run:
@@ -74,7 +79,9 @@ run:
- python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*
```
-:::TabTitle With a CI/CD job token
+{{< /tab >}}
+
+{{< tab title="With a CI/CD job token" >}}
```yaml
run:
@@ -88,7 +95,9 @@ run:
- python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Authenticate for a group
@@ -171,10 +180,13 @@ When a PyPI package is not found in the package registry, the request is forward
Administrators can disable this behavior in the [Continuous Integration settings](../../../administration/settings/continuous_integration.md).
-NOTE:
+{{< alert type="note" >}}
+
When you use the `--index-url` option, do not specify the port if it is a default
port. `http` URLs default to 80, and `https` URLs default to 443.
+{{< /alert >}}
+
### Install from a project
To install the latest version of a package, use the following command:
diff --git a/doc/user/packages/pypi_repository/auto_publish_tutorial.md b/doc/user/packages/pypi_repository/auto_publish_tutorial.md
index 675198c96cc2b519b3b156ee334b8e98e36722ae..823f717f5444ae638dee61fe1f9d4d2402b94382 100644
--- a/doc/user/packages/pypi_repository/auto_publish_tutorial.md
+++ b/doc/user/packages/pypi_repository/auto_publish_tutorial.md
@@ -39,7 +39,7 @@ To create a `.gitlab-ci.yml` file:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Repository**.
1. Above the file list, select the branch you want to commit to.
-1. Select **Create new** (**{plus}**) and **New file**.
+1. Select **Create new** ({{< icon name="plus" >}}) and **New file**.
1. Name the file `.gitlab-ci.yml`. In the larger window, paste this sample configuration:
```yaml
diff --git a/doc/user/packages/rubygems_registry/_index.md b/doc/user/packages/rubygems_registry/_index.md
index 75922a2bbc16141150bd27def3dc71f88cf2dc4a..633ebc07c3a7d13eb2e2f2ef9ccc6a0f78401d62 100644
--- a/doc/user/packages/rubygems_registry/_index.md
+++ b/doc/user/packages/rubygems_registry/_index.md
@@ -5,18 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Ruby gems in the package registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52147) in GitLab 13.9 [with a flag](../../../administration/feature_flags.md) named `rubygem_packages`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52147) in GitLab 13.9 [with a flag](../../../administration/feature_flags.md) named `rubygem_packages`. Disabled by default. This feature is an [experiment](../../../policy/development_stages_support.md).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
You can publish Ruby gems to your project's package registry. Then, you can download them from the UI or with the API.
This feature is an [experiment](../../../policy/development_stages_support.md).
@@ -36,9 +46,9 @@ To do this, you can use:
For example:
-::Tabs
+{{< tabs >}}
-:::TabTitle With an access token
+{{< tab title="With an access token" >}}
To authenticate with an access token:
@@ -54,7 +64,9 @@ In this example:
- `<token>` must be the token value of either your personal access token or deploy token.
- `<project_id>` is displayed on the [project overview page](../../project/working_with_projects.md#access-a-project-by-using-the-project-id).
-:::TabTitle With a CI/CD job token
+{{< /tab >}}
+
+{{< tab title="With a CI/CD job token" >}}
To authenticate with a CI/CD job token:
@@ -83,7 +95,9 @@ To authenticate with a CI/CD job token:
https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/rubygems: '${env.CI_JOB_TOKEN}'
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Push a Ruby gem
diff --git a/doc/user/packages/terraform_module_registry/_index.md b/doc/user/packages/terraform_module_registry/_index.md
index c2a001b07f9758c56bc7718d2e680876a80c50fb..d5a40cd625dab8126660a874200abc93e2efd886 100644
--- a/doc/user/packages/terraform_module_registry/_index.md
+++ b/doc/user/packages/terraform_module_registry/_index.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Terraform Module Registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Infrastructure registry and Terraform Module Registry [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/404075) into a single Terraform Module Registry feature in GitLab 15.11.
-> - Support for groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140215) in GitLab 16.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Infrastructure registry and Terraform Module Registry [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/404075) into a single Terraform Module Registry feature in GitLab 15.11.
+- Support for groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140215) in GitLab 16.9.
+
+{{< /history >}}
With the Terraform Module Registry, you can use GitLab projects as a
private registry for terraform modules. You can create and publish
@@ -19,7 +26,11 @@ projects.
## View Terraform modules
-> - Support for Readme files [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438060) in GitLab 17.2.
+{{< history >}}
+
+- Support for Readme files [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438060) in GitLab 17.2.
+
+{{< /history >}}
To view Terraform modules in your project or group:
@@ -98,7 +109,11 @@ Example response:
### Using a CI/CD template (recommended)
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110493) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110493) in GitLab 15.9.
+
+{{< /history >}}
You can use the [`Terraform-Module.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform-Module.gitlab-ci.yml)
or the advanced [`Terraform/Module-Base.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Module-Base.gitlab-ci.yml)
@@ -160,8 +175,12 @@ For other ways to control jobs in your CI/CD pipeline, refer to the [CI/CD YAML
### Allow duplicate Terraform modules
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368040) in GitLab 16.8.
-> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368040) in GitLab 16.8.
+- Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/370471) from Maintainer to Owner in GitLab 17.0.
+
+{{< /history >}}
By default, the Terraform Module Registry enforces uniqueness for module names in the same namespace.
@@ -174,9 +193,12 @@ To allow publishing duplicate module names:
Your changes are automatically saved.
-NOTE:
+{{< alert type="note" >}}
+
If **Allow duplicates** is turned on, you can specify module names that should not have duplicates in the **Exceptions** text box.
+{{< /alert >}}
+
You can also allow publishing duplicate names by enabling `terraform_module_duplicates_allowed` in the [GraphQL API](../../../api/graphql/reference/_index.md#packagesettings).
To allow duplicates with specific names:
diff --git a/doc/user/packages/workflows/build_packages.md b/doc/user/packages/workflows/build_packages.md
index e677f6283682b9690469911619c659c110feb870..acd82c31414de4d5517e2deb13425cb48f408a26 100644
--- a/doc/user/packages/workflows/build_packages.md
+++ b/doc/user/packages/workflows/build_packages.md
@@ -112,10 +112,13 @@ To build a package:
conan create . mycompany/beta
```
- NOTE:
- If you use an [instance remote](../conan_repository/_index.md#add-a-remote-for-your-instance), you must
+ {{< alert type="note" >}}
+
+If you use an [instance remote](../conan_repository/_index.md#add-a-remote-for-your-instance), you must
follow a specific [naming convention](../conan_repository/_index.md#package-recipe-naming-convention-for-instance-remotes).
+ {{< /alert >}}
+
A package with the recipe `Hello/0.1@mycompany/beta` is created.
For more details about creating and managing Conan packages, see the
diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md
index 4fafa03a07438c4855c2b9fb18b1b0b1a5cb900a..cafe680c484ca4e6e0e38d35f42b7d33e33eb89e 100644
--- a/doc/user/packages/workflows/project_registry.md
+++ b/doc/user/packages/workflows/project_registry.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Store all of your packages in one GitLab project
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can store all of your packages in one project's package registry. Rather than using
a GitLab repository to store code, you can use the repository to store all your packages.
diff --git a/doc/user/packages/workflows/working_with_monorepos.md b/doc/user/packages/workflows/working_with_monorepos.md
index bb9d6f3df003fe7597e7f63e17353822ef63e668..34fbb350ae598e357e3a6228a3ddcc31e0d90ed3 100644
--- a/doc/user/packages/workflows/working_with_monorepos.md
+++ b/doc/user/packages/workflows/working_with_monorepos.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Monorepo package management workflows
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use a monorepo project as a package registry to publish packages to multiple projects.
@@ -51,10 +54,13 @@ To publish a package for `MyProject`:
NPM_TOKEN=<token> npm publish
```
-WARNING:
+{{< alert type="warning" >}}
+
Never hardcode GitLab tokens (or any tokens) directly in `.npmrc` files or any other files that can
be committed to a repository.
+{{< /alert >}}
+
You should see the package for `MyProject` published in your project's package registry.
To publish a package in `ChildProject`, follow the same steps. The contents of the `.npmrc` file can be identical to the one you added in `MyProject`.
diff --git a/doc/user/packages/yarn_repository/_index.md b/doc/user/packages/yarn_repository/_index.md
index 6cb2b3acbd61f1524f2336b8e2097f0bec761936..387442acb756b43cc69d0b74d04885506e7bca10 100644
--- a/doc/user/packages/yarn_repository/_index.md
+++ b/doc/user/packages/yarn_repository/_index.md
@@ -170,10 +170,13 @@ Your package should now publish to the package registry when the pipeline runs.
## Install a package
-NOTE:
+{{< alert type="note" >}}
+
If multiple packages have the same name and version, the most recently-published
package is retrieved when you install a package.
+{{< /alert >}}
+
You can use one of two API endpoints to install packages:
- **Instance-level**: Best used when working with many packages in an organization scope.
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 26d2daa553d15611025030e5d0abf2c21896e453..cc103ea452554b9224f91ec54773436b0e57a102 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Roles and permissions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you add a user to a project or group, you assign them a role.
The role determines which actions they can take in GitLab.
@@ -29,7 +32,11 @@ It's okay to list multiple related objects per line (for example, "View pipeline
## Roles
-> - Planner role [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/482733) in GitLab 17.7.
+{{< history >}}
+
+- Planner role [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/482733) in GitLab 17.7.
+
+{{< /history >}}
You can assign users a default role or a [custom role](custom_roles.md).
@@ -602,11 +609,18 @@ For more information, see
## Users with Minimal Access
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Support for inviting users with Minimal Access role [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106438) in GitLab 15.9.
-> - Support for inviting users with Minimal Access role [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106438) in GitLab 15.9.
+{{< /history >}}
Users with the Minimal Access role do not:
diff --git a/doc/user/profile/_index.md b/doc/user/profile/_index.md
index 8cebcfd15d12ae5ea1897beab417e89868a3347d..12c45ddcb3146dfc372660664d939f62ccbc1f09 100644
--- a/doc/user/profile/_index.md
+++ b/doc/user/profile/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User account
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Each GitLab account has a user profile, which contains information about you and your GitLab activity.
@@ -73,13 +76,20 @@ The new email address is added as a secondary email address.
You can use secondary email addresses to reset passwords but not to authenticate.
You can update your [primary email address](#change-your-primary-email).
-NOTE:
+{{< alert type="note" >}}
+
[Making your email non-public](#set-your-public-email) does not prevent it from being used for commit matching,
[project imports](../project/import/_index.md), and [group migrations](../group/import/_index.md).
+{{< /alert >}}
+
## Delete email addresses from your user profile
-> - Automatic deletion of unverified secondary email addresses [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151562) in GitLab 17.0.
+{{< history >}}
+
+- Automatic deletion of unverified secondary email addresses [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151562) in GitLab 17.0.
+
+{{< /history >}}
You can delete a secondary email address from your account. You cannot delete your
primary email address.
@@ -89,16 +99,19 @@ sent to the primary email address instead.
Unverified secondary email addresses are automatically deleted after three days.
-NOTE:
+{{< alert type="note" >}}
+
Because of [issue 438600](https://gitlab.com/gitlab-org/gitlab/-/issues/438600), group notifications are still sent to
the deleted email address.
+{{< /alert >}}
+
To delete an email address from your account:
1. On the left sidebar, select your avatar.
1. Select **Edit profile**.
1. On the left sidebar, select **Emails**.
-1. Select **Delete** (**{remove}**) and confirm you want to **Remove**.
+1. Select **Delete** ({{< icon name="remove" >}}) and confirm you want to **Remove**.
You can also [use the API to delete a secondary email address](../../api/user_email_addresses.md#delete-an-email-address).
@@ -106,9 +119,12 @@ You can also [use the API to delete a secondary email address](../../api/user_em
You can make your user profile visible to only you and GitLab administrators.
-NOTE:
+{{< alert type="note" >}}
+
A GitLab administrator can [disable](../../administration/settings/account_and_limit_settings.md#prevent-users-from-making-their-profiles-private) this setting, forcing all profiles to be made public.
+{{< /alert >}}
+
To make your profile private:
1. On the left sidebar, select your avatar.
@@ -122,11 +138,14 @@ The following is hidden from your user profile page (`https://gitlab.example.com
- Date when account was created
- Tabs for activity, groups, contributed projects, personal projects, starred projects, snippets
-NOTE:
+{{< alert type="note" >}}
+
Making your user profile page private does not hide all your public resources from
the REST or GraphQL APIs. For example, the email address associated with your commit
signature is accessible unless you [use an automatically-generated private commit email](#use-an-automatically-generated-private-commit-email).
+{{< /alert >}}
+
### User visibility
The public page of a user, located at `/username`, is always visible whether you are signed-in or
@@ -146,7 +165,7 @@ the README file with information, it's included on your profile page.
To create a new project and add its README to your profile:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details:
- In the **Project name** field, enter the name for your new project.
@@ -170,9 +189,13 @@ to match your username.
## Add external accounts to your user profile page
-> - Mastodon user account [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132892) in GitLab 16.6 [with a flag](../feature_flags.md) named `mastodon_social_ui`. Disabled by default.
-> - Mastodon user account [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/428163) in GitLab 16.7. Feature flag `mastodon_social_ui` removed.
-> - Ability to verify Mastodon account using your GitLab user profile [added](https://gitlab.com/gitlab-org/gitlab/-/issues/433391) in GitLab 17.4 [with a flag](../feature_flags.md) named `verify_mastodon_user`. Disabled by default.
+{{< history >}}
+
+- Mastodon user account [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132892) in GitLab 16.6 [with a flag](../feature_flags.md) named `mastodon_social_ui`. Disabled by default.
+- Mastodon user account [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/428163) in GitLab 16.7. Feature flag `mastodon_social_ui` removed.
+- Ability to verify Mastodon account using your GitLab user profile [added](https://gitlab.com/gitlab-org/gitlab/-/issues/433391) in GitLab 17.4 [with a flag](../feature_flags.md) named `verify_mastodon_user`. Disabled by default.
+
+{{< /history >}}
You can add links to certain other external accounts you might have, like Skype and X (formerly Twitter).
They can help other users connect with you on other platforms.
@@ -333,8 +356,12 @@ blocked users don't appear in the followers list on user profiles.
### Disable following and being followed by other users
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325558) in GitLab 16.0 [with a flag](../feature_flags.md) named `disable_follow_users`.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/420620) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325558) in GitLab 16.0 [with a flag](../feature_flags.md) named `disable_follow_users`.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/420620) in GitLab 16.3.
+
+{{< /history >}}
You can disable following and being followed by other users.
@@ -344,9 +371,12 @@ You can disable following and being followed by other users.
1. Clear the **Enable follow users** checkbox.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
When this feature is being disabled, all current followed/following connections are deleted.
+{{< /alert >}}
+
## View a user's activity
GitLab tracks [user contribution activity](contributions_calendar.md).
@@ -414,7 +444,11 @@ GitLab administrators can
### Stay signed in indefinitely
-> - Ability to turn the **Remember me** setting on and off [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369133) in GitLab 16.0.
+{{< history >}}
+
+- Ability to turn the **Remember me** setting on and off [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369133) in GitLab 16.0.
+
+{{< /history >}}
To remain signed in indefinitely, select the **Remember me** checkbox on the GitLab sign-in page.
@@ -442,12 +476,15 @@ When it expires or isn't available, GitLab:
When both the `remember_user_token` and `_gitlab_session` cookies are gone or expired, you must sign in again.
-NOTE:
+{{< alert type="note" >}}
+
When any session is signed out, or when a session is revoked
from the [active sessions list](active_sessions.md), all **Remember me** tokens are revoked.
While other sessions remain active, the **Remember me** feature doesn't restore
a session if the browser is closed or the existing session expires.
+{{< /alert >}}
+
## Related topics
- [Create users](account/create_accounts.md)
diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md
index 6c3c4256a7c82a09447f058d66961c9abf72c55e..c9fc9891ed982c0b4fb9c249abbbf42a1b58469d 100644
--- a/doc/user/profile/account/create_accounts.md
+++ b/doc/user/profile/account/create_accounts.md
@@ -1,14 +1,17 @@
---
stage: Fulfillment
group: Provision
-description: Create user accounts in GitLab.
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
+description: Create user accounts in GitLab.
title: Create users
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can create user accounts in GitLab in different ways:
@@ -70,18 +73,21 @@ Users are created when they:
## Create users through the Rails console
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions.
Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
To create a user through the Rails console:
1. [Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session).
1. Run the command according to your GitLab version:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle 16.10 and earlier
+ {{< tab title="16.10 and earlier" >}}
```ruby
u = User.new(username: 'test_user', email: 'test@example.com', name: 'Test User', password: 'password', password_confirmation: 'password')
@@ -90,7 +96,9 @@ To create a user through the Rails console:
u.save!
```
- :::TabTitle 16.11 through 17.6
+ {{< /tab >}}
+
+ {{< tab title="16.11 through 17.6" >}}
```ruby
u = User.new(username: 'test_user', email: 'test@example.com', name: 'Test User', password: 'password', password_confirmation: 'password')
@@ -99,7 +107,9 @@ To create a user through the Rails console:
u.save!
```
- :::TabTitle 17.7 and later
+ {{< /tab >}}
+
+ {{< tab title="17.7 and later" >}}
```ruby
u = Users::CreateService.new(nil,
@@ -113,4 +123,6 @@ To create a user through the Rails console:
).execute
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md
index 8d3d5a769f347f8e441a21c8b4e87866fbe8db98..bffd82ab5d3d8cfb1c699ef5abeb2fcf3b98c25b 100644
--- a/doc/user/profile/account/delete_account.md
+++ b/doc/user/profile/account/delete_account.md
@@ -5,32 +5,48 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deleting a user account
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Users can be deleted from a GitLab instance, either by:
- The user themselves.
- An administrator.
-NOTE:
+{{< alert type="note" >}}
+
Deleting a user deletes all projects in that user namespace.
+{{< /alert >}}
+
## Delete your own account
-> - Delay between a user deleting their own account and deletion of the user record introduced in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `delay_delete_own_user`. Enabled by default on GitLab.com.
+{{< history >}}
+
+- Delay between a user deleting their own account and deletion of the user record introduced in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `delay_delete_own_user`. Enabled by default on GitLab.com.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `delay_delete_own_user`. On GitLab.com, this feature is available. On GitLab Dedicated, this feature is not available.
+{{< /alert >}}
+
On GitLab.com, it takes seven days from when you delete your own account to when your account is deleted. During this time:
- That user is [blocked](../../../administration/moderate_users.md#block-a-user).
- You cannot create a new account with the same username.
- NOTE:
- After the seven day time period is finished, any user can create a user account with that previously used username. Therefore, you should not assume that you will be able to create a new account with that username after the seven days, because it might be taken.
+ {{< alert type="note" >}}
+
+After the seven day time period is finished, any user can create a user account with that previously used username. Therefore, you should not assume that you will be able to create a new account with that username after the seven days, because it might be taken.
+
+ {{< /alert >}}
You can [create a new account with the same email address](#create-a-new-account-with-the-same-email-address)
if you remove that email address from your account first.
@@ -70,9 +86,12 @@ primary email address.
## Delete users and user contributions
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
As an administrator, to delete a user account:
@@ -85,10 +104,13 @@ As an administrator, to delete a user account:
- **Delete user and contributions** to delete the user and their associated records. This option also removes all groups (and
projects within these groups) where the user is the sole direct Owner of a group. Inherited ownership doesn't apply.
-WARNING:
+{{< alert type="warning" >}}
+
Using the **Delete user and contributions** option may result in removing more data than intended. See
[associated records](#associated-records) for additional details.
+{{< /alert >}}
+
### Associated records
When deleting users, you can either:
@@ -123,17 +145,26 @@ records are always removed.
The deleting associated records option can be requested in the [API](../../../api/users.md#delete-a-user) as well as
the **Admin** area.
-WARNING:
+{{< alert type="warning" >}}
+
User approvals are associated with a user ID. Other user contributions do not have an associated user ID. When you delete a user and their contributions are moved to a "Ghost User", the approval contributions refer to a missing or invalid user ID. Instead of deleting users, consider [blocking](../../../administration/moderate_users.md#block-a-user), [banning](../../../administration/moderate_users.md#ban-a-user), or [deactivating](../../../administration/moderate_users.md#deactivate-a-user) them.
+{{< /alert >}}
+
## Delete the root account on a self-managed instance
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
The root account is the most privileged account on the system. Deleting the root account might result in losing access to the instance [**Admin** area](../../../administration/admin_area.md) if there is no other administrator available on the instance.
+{{< /alert >}}
+
You can delete the root account using either the UI or the [GitLab Rails console](../../../administration/operations/rails_console.md).
Before you delete the root account:
@@ -155,9 +186,12 @@ To delete the root account:
### Use the GitLab Rails console
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
Prerequisites:
- You must have access to the GitLab Rails console.
diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md
index ed8a726f85c06d0b9ceb9a1ccfcb7c599bbb7b36..052c70feb617940c98005bd0f005ea64053855c6 100644
--- a/doc/user/profile/account/two_factor_authentication.md
+++ b/doc/user/profile/account/two_factor_authentication.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Two-factor authentication
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
Two-factor authentication (2FA) provides an additional level of security to your GitLab account. For others to access
your account, they would need your username and password _and_ access to your second factor of authentication.
@@ -90,14 +93,20 @@ in a safe place.
### Enable a one-time password authenticator using FortiAuthenticator
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available per user, an administrator can
[enable the feature flag](../../../administration/feature_flags.md) named `forti_authenticator`.
On GitLab.com and GitLab Dedicated, this feature is not available.
+{{< /alert >}}
+
You can use FortiAuthenticator as an OTP provider in GitLab. Users must:
- Exist in both FortiAuthenticator and GitLab with the same username.
@@ -155,10 +164,17 @@ Configure FortiAuthenticator in GitLab. On your GitLab server:
### Enable a one-time password authenticator using Cisco Duo
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15760) in GitLab 15.10.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15760) in GitLab 15.10.
+
+{{< /history >}}
You can use Cisco Duo as an OTP provider in GitLab.
@@ -221,15 +237,21 @@ On your GitLab server:
### Enable a one-time password authenticator using FortiToken Cloud
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available per user, an administrator can
[enable the feature flag](../../../administration/feature_flags.md) named `forti_token_cloud`.
On GitLab.com and GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
+{{< /alert >}}
+
You can use FortiToken Cloud as an OTP provider in GitLab. Users must:
- Exist in both FortiToken Cloud and GitLab with the same username.
@@ -280,8 +302,12 @@ Configure FortiToken Cloud in GitLab. On your GitLab server:
### Set up a WebAuthn device
-> - Optional one-time password authentication for WebAuthn devices [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378844) in GitLab 15.10 [with a feature flag](../../../administration/feature_flags.md) named `webauthn_without_totp`.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/396931) in GitLab 17.6. Feature flag `webauthn_without_totp` removed.
+{{< history >}}
+
+- Optional one-time password authentication for WebAuthn devices [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378844) in GitLab 15.10 [with a feature flag](../../../administration/feature_flags.md) named `webauthn_without_totp`.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/396931) in GitLab 17.6. Feature flag `webauthn_without_totp` removed.
+
+{{< /history >}}
WebAuthn is [supported by](https://caniuse.com/#search=webauthn) the following:
@@ -320,18 +346,24 @@ If this is the first time you have set up 2FA, you
must [download recovery codes](#recovery-codes) so you can recover access to your
account if you lose access.
-WARNING:
+{{< alert type="warning" >}}
+
You can lose access to your account if you clear your browser data.
+{{< /alert >}}
+
## Recovery codes
Immediately after successfully enabling 2FA with an OTP authenticator, you're prompted to download
a set of generated recovery codes. If you ever lose access to your OTP authenticator, you can use one of
these recovery codes to sign in to your account.
-WARNING:
+{{< alert type="warning" >}}
+
Each code can be used only once to sign in to your account.
+{{< /alert >}}
+
You should copy and print the codes, or use **Download codes** to download them for storage in a safe
place. If you choose to download them, the file is called `gitlab-recovery-codes.txt`.
@@ -353,9 +385,12 @@ To regenerate 2FA recovery codes, you need access to a desktop browser:
1. In the **Disable two-factor authentication** section, select **Regenerate recovery codes**.
1. On the dialog, enter your current password and select **Regenerate recovery codes**.
-NOTE:
+{{< alert type="note" >}}
+
If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes.
+{{< /alert >}}
+
## Sign in with two-factor authentication enabled
Signing in with 2FA enabled is only slightly different than the typical sign-in process. Enter your username and password
@@ -375,7 +410,11 @@ in.
## Disable two-factor authentication
-> - Ability to disable OTP authenticator and WebAuthn devices individually or simultaneously [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393419) in GitLab 17.6.
+{{< history >}}
+
+- Ability to disable OTP authenticator and WebAuthn devices individually or simultaneously [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393419) in GitLab 17.6.
+
+{{< /history >}}
You can disable the OTP authenticator and WebAuthn devices individually or simultaneously. To disable them simultaneously:
@@ -389,9 +428,12 @@ This clears all your 2FA registrations, including mobile applications and WebAut
## Information for GitLab administrators
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
- Take care that 2FA keeps working after [restoring a GitLab backup](../../../administration/backup_restore/_index.md).
- To ensure 2FA authorizes correctly with an OTP server, synchronize your GitLab
diff --git a/doc/user/profile/account/two_factor_authentication_troubleshooting.md b/doc/user/profile/account/two_factor_authentication_troubleshooting.md
index a431847a9d92232a53ab35066ff27b398ee52986..30525bd444594c40444672b08e39c6afee898f9d 100644
--- a/doc/user/profile/account/two_factor_authentication_troubleshooting.md
+++ b/doc/user/profile/account/two_factor_authentication_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting two-factor authentication
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
## Error: `HTTP Basic: Access denied. If a password was provided for Git authentication ...`
@@ -128,9 +131,12 @@ After signing in, immediately set up 2FA with a new device.
### Disable and reset 2FA on your account
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
If other methods are unavailable, create a support ticket to request
a GitLab global administrator to disable 2FA for your account.
diff --git a/doc/user/profile/achievements.md b/doc/user/profile/achievements.md
index 04287ecbbaa5a7e923bb61cd2ae3ed25a6262a8d..77cbee7cc341e9ef8a5442243afdfc567810cf0d 100644
--- a/doc/user/profile/achievements.md
+++ b/doc/user/profile/achievements.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Achievements
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113156) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `achievements`. Disabled by default.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113156) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `achievements`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available,
an administrator can [enable the feature flag](../../administration/feature_flags.md) named `achievements`.
+{{< /alert >}}
+
Achievements are a way to reward users for their activity on GitLab.
As a namespace maintainer or owner, you can create custom achievements for specific contributions. You can award these
achievements to users or revoke them based on defined criteria.
@@ -304,7 +314,11 @@ If you don't want to display achievements on your profile, you can opt out. To d
## Change visibility of specific achievements
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161225) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161225) in GitLab 17.3.
+
+{{< /history >}}
If you don't want to display all achievements on your profile, you can change the visibility of specific achievements.
diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md
index c4a8b45cdb19d1611dd3954e7f83340f75fc2a9b..d2aa96bcc86da9e7a7442a8c9481b196bd79defa 100644
--- a/doc/user/profile/active_sessions.md
+++ b/doc/user/profile/active_sessions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Active sessions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab lists all devices that have logged into your account. You can
review the sessions, and revoke any you don't recognize.
@@ -36,11 +39,14 @@ To revoke an active session:
1. On the left sidebar, select **Active Sessions**.
1. Select **Revoke** next to a session. The current session cannot be revoked, as this would sign you out of GitLab.
-NOTE:
+{{< alert type="note" >}}
+
When any session is revoked all **Remember me** tokens for all
devices are revoked. For details about **Remember me**, see
[cookies used for sign-in](_index.md#cookies-used-for-sign-in).
+{{< /alert >}}
+
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/user/profile/comment_templates.md b/doc/user/profile/comment_templates.md
index 48fcd7e5021d26662010a5d36c2fb364c44c85a1..3a9e949c0a6e2dabcafb78721542ea554f8b4b8b 100644
--- a/doc/user/profile/comment_templates.md
+++ b/doc/user/profile/comment_templates.md
@@ -2,22 +2,29 @@
stage: Create
group: Code Review
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
-description: "Build templates for text frequently used in comments, and share those templates with your project or group."
+description: Build templates for text frequently used in comments, and share those templates with your project or group.
title: Comment templates
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113232) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. Enabled for GitLab team members only.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119468) in GitLab 16.0.
-> - [Feature flag `saved_replies` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123363) in GitLab 16.6.
-> - Saved replies for groups [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12669) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `group_saved_replies_flag`. Disabled by default.
-> - Saved replies for groups [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/440817) on GitLab.com and GitLab Self-Managed in GitLab 16.11.
-> - Saved replies for groups [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/504028) in GitLab 17.8. Feature flag `group_saved_replies_flag` removed.
-> - Saved replies for projects [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12669) in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `project_saved_replies_flag`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/504028) in GitLab 17.8. Feature flag `project_saved_replies_flag` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113232) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. Enabled for GitLab team members only.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119468) in GitLab 16.0.
+- [Feature flag `saved_replies` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123363) in GitLab 16.6.
+- Saved replies for groups [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12669) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `group_saved_replies_flag`. Disabled by default.
+- Saved replies for groups [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/440817) on GitLab.com and GitLab Self-Managed in GitLab 16.11.
+- Saved replies for groups [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/504028) in GitLab 17.8. Feature flag `group_saved_replies_flag` removed.
+- Saved replies for projects [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12669) in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `project_saved_replies_flag`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/504028) in GitLab 17.8. Feature flag `project_saved_replies_flag` removed.
+
+{{< /history >}}
With comment templates, create and reuse text for any text area in:
@@ -35,7 +42,7 @@ or large, like chunks of boilerplate text you use frequently:
To include the text of a comment template in your comment:
-1. In the editor toolbar for your comment, select **Comment templates** (**{comment-lines}**).
+1. In the editor toolbar for your comment, select **Comment templates** ({{< icon name="comment-lines" >}}).
1. Select your desired comment template.
## Create comment templates
@@ -46,7 +53,7 @@ To create a comment template for your own use:
1. On the left sidebar, select your avatar.
1. From the dropdown list, select **Preferences**.
-1. On the left sidebar, select **Comment templates** (**{comment-lines}**).
+1. On the left sidebar, select **Comment templates** ({{< icon name="comment-lines" >}}).
1. Select **Add new**.
1. Provide a **Name** for your comment template.
1. Enter the **Content** of your reply. You can use any formatting you use in
@@ -55,13 +62,16 @@ To create a comment template for your own use:
### For a group
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
To create a comment template shared with all members of a group:
1. In the editor toolbar for a comment, select **Comment templates**
- (**{comment-lines}**), then select **Manage group comment templates**.
+ ({{< icon name="comment-lines" >}}), then select **Manage group comment templates**.
1. Select **Add new**.
1. Provide a **Name** for your comment template.
1. Enter the **Content** of your reply. You can use any formatting you use in
@@ -70,13 +80,16 @@ To create a comment template shared with all members of a group:
### For a project
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
To create a comment template shared with all members of a project:
1. In the editor toolbar for a comment, select **Comment templates**
- (**{comment-lines}**), then select **Manage project comment templates**.
+ ({{< icon name="comment-lines" >}}), then select **Manage project comment templates**.
1. Select **Add new**.
1. Provide a **Name** for your comment template.
1. Enter the **Content** of your reply. You can use any formatting you use in
@@ -89,25 +102,31 @@ To see existing comment templates:
1. On the left sidebar, select your avatar.
1. From the dropdown list, select **Preferences**.
-1. On the left sidebar, select **Comment templates** (**{comment-lines}**).
+1. On the left sidebar, select **Comment templates** ({{< icon name="comment-lines" >}}).
1. Scroll to **Comment templates**.
### For a group
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
1. In the editor toolbar for a comment, select **Comment templates**
- (**{comment-lines}**).
+ ({{< icon name="comment-lines" >}}).
1. Select **Manage group comment templates**.
### For a project
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
1. In the editor toolbar for a comment, select **Comment templates**
- (**{comment-lines}**).
+ ({{< icon name="comment-lines" >}}).
1. Select **Manage project comment templates**.
## Edit or delete comment templates
@@ -116,27 +135,33 @@ To edit or delete an existing comment template:
1. On the left sidebar, select your avatar.
1. From the dropdown list, select **Preferences**.
-1. On the left sidebar, select **Comment templates** (**{comment-lines}**).
+1. On the left sidebar, select **Comment templates** ({{< icon name="comment-lines" >}}).
1. Scroll to **Comment templates**, and identify the comment template you want to edit.
-1. To edit, select **Edit** (**{pencil}**).
-1. To delete, select **Delete** (**{remove}**), then select **Delete** again on the dialog.
+1. To edit, select **Edit** ({{< icon name="pencil" >}}).
+1. To delete, select **Delete** ({{< icon name="remove" >}}), then select **Delete** again on the dialog.
### For a group
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
1. In the editor toolbar for a comment, select **Comment templates**
- (**{comment-lines}**), then select **Manage group comment templates**.
-1. To edit, select **Edit** (**{pencil}**).
-1. To delete, select **Delete** (**{remove}**), then select **Delete** again on the dialog.
+ ({{< icon name="comment-lines" >}}), then select **Manage group comment templates**.
+1. To edit, select **Edit** ({{< icon name="pencil" >}}).
+1. To delete, select **Delete** ({{< icon name="remove" >}}), then select **Delete** again on the dialog.
### For a project
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
1. In the editor toolbar for a comment, select **Comment templates**
- (**{comment-lines}**), then select **Manage project comment templates**.
-1. To edit, select **Edit** (**{pencil}**).
-1. To delete, select **Delete** (**{remove}**), then select **Delete** again on the dialog.
+ ({{< icon name="comment-lines" >}}), then select **Manage project comment templates**.
+1. To edit, select **Edit** ({{< icon name="pencil" >}}).
+1. To delete, select **Delete** ({{< icon name="remove" >}}), then select **Delete** again on the dialog.
diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md
index e8d2a804269f7e54089014062b24756ff1e852cd..507c9a9128924070cdee348c617032a4f8f3f0d7 100644
--- a/doc/user/profile/contributions_calendar.md
+++ b/doc/user/profile/contributions_calendar.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Contributions calendar
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The contributions calendar displays a [user's events](#user-contribution-events) from the past 12 months.
This includes contributions made in forked and [private](#show-private-contributions-on-your-user-profile-page) repositories.
@@ -16,9 +19,12 @@ This includes contributions made in forked and [private](#show-private-contribut
The gradient color of the tiles represents the number of contributions made per day. The gradient ranges from blank (0 contributions) to dark blue (more than 30 contributions).
-NOTE:
+{{< alert type="note" >}}
+
The contribution calendar only displays contributions from the last 12 months, but issue [24264](https://gitlab.com/gitlab-org/gitlab/-/issues/24264) proposes to change this to more than 12 months. General improvements to the user profile are proposed in issue [8488](https://gitlab.com/groups/gitlab-org/-/epics/8488).
+{{< /alert >}}
+
## User contribution events
GitLab tracks the following contribution events:
@@ -85,7 +91,7 @@ GitLab provides RSS feeds of user activity. To subscribe to the
RSS feed of a user's activity:
1. Go to the [user's profile](_index.md#access-your-user-profile).
-1. In the upper-right corner, select the feed symbol (**{rss}**) to display the results as an RSS feed in Atom format.
+1. In the upper-right corner, select the feed symbol ({{< icon name="rss" >}}) to display the results as an RSS feed in Atom format.
The URL of the result contains both a feed token, and
the user's activity that you're authorized to view.
diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md
index fbbf31d2810bccbefe0b38daea9ed6e90d961d7c..670c81bbc192f38e847c58025fbcf8c29c6294a3 100644
--- a/doc/user/profile/notifications.md
+++ b/doc/user/profile/notifications.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Notification emails
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Enhanced email styling [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78604) in GitLab 14.9 [with a feature flag](../../administration/feature_flags.md) named `enhanced_notify_css`. Disabled by default.
-> - Enhanced email styling [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 14.9.
-> - Enhanced email styling [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 15.0.
-> - Product marketing emails [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/418137) in GitLab 16.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Enhanced email styling [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78604) in GitLab 14.9 [with a feature flag](../../administration/feature_flags.md) named `enhanced_notify_css`. Disabled by default.
+- Enhanced email styling [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 14.9.
+- Enhanced email styling [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 15.0.
+- Product marketing emails [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/418137) in GitLab 16.6.
+
+{{< /history >}}
Stay informed about what's happening in GitLab with email notifications.
You can receive updates about activity in issues, merge requests, epics, and designs.
@@ -115,7 +122,7 @@ To select a notification level for a group, use either of these methods:
Or:
1. On the left sidebar, select **Search or go to** and find your group.
-1. Select the notification dropdown list, next to the bell icon (**{notifications}**).
+1. Select the notification dropdown list, next to the bell icon ({{< icon name="notifications" >}}).
1. Select the desired [notification level](#notification-levels).
#### Change email address used for group notifications
@@ -144,7 +151,7 @@ To select a notification level for a project, use either of these methods:
Or:
1. On the left sidebar, select **Search or go to** and find your project.
-1. Select the notification dropdown list, next to the bell icon (**{notifications}**).
+1. Select the notification dropdown list, next to the bell icon ({{< icon name="notifications" >}}).
1. Select the desired [notification level](#notification-levels).
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
@@ -209,18 +216,28 @@ to change their user notification settings to **Watch** instead.
### Edit notification settings for issues, merge requests, and epics
To toggle notifications on an issue, merge request, or epic: on the right sidebar,
-select the vertical ellipsis (**{ellipsis_v}**), then turn on or off the **Notifications** toggle.
+select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then turn on or off the **Notifications** toggle.
#### Moved notifications
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132678) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `notifications_todos_buttons`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132678) in GitLab 16.5 [with a flag](../../administration/feature_flags.md) named `notifications_todos_buttons`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag. For more information, see the history. Enabling this feature flag moves the notifications and to-do item buttons to the upper-right corner of the page.
+{{< /alert >}}
+
When you **turn on** notifications, you start receiving notifications on each update, even if you
haven't participated in the discussion.
When you turn notifications on in an epic, you aren't automatically subscribed to the issues linked
@@ -275,14 +292,21 @@ To always receive notifications on your own issues, merge requests, and so on, t
## Notifications for unknown sign-ins
-> - Listing the full name and username of the signed-in user [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225183) in GitLab 15.10.
-> - Geographic location [added](https://gitlab.com/gitlab-org/gitlab/-/issues/296128) in GitLab 17.5.
+{{< history >}}
+
+- Listing the full name and username of the signed-in user [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225183) in GitLab 15.10.
+- Geographic location [added](https://gitlab.com/gitlab-org/gitlab/-/issues/296128) in GitLab 17.5.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is enabled by default for self-managed instances. Administrators may disable this feature
through the [Sign-in restrictions](../../administration/settings/sign_in_restrictions.md#email-notification-for-unknown-sign-ins) section of the UI.
The feature is always enabled on GitLab.com.
+{{< /alert >}}
+
When a user successfully signs in from a previously unknown IP address or device,
GitLab notifies the user by email. In this way, GitLab proactively alerts users of potentially
malicious or unauthorized sign-ins. This notification email includes the:
@@ -304,7 +328,11 @@ GitLab uses several methods to identify a known sign-in. All methods must fail f
## Notifications for attempted sign-ins using incorrect verification codes
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374740) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374740) in GitLab 15.5.
+
+{{< /history >}}
GitLab sends you an email notification if it detects an attempt to sign in to your account using a wrong two-factor
authentication (2FA) code. This can help you detect that a bad actor gained access to your username and password, and is trying
@@ -322,7 +350,11 @@ The participants are:
## Notifications on group or project access expiration
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.3.
+
+{{< /history >}}
GitLab sends an email notification if a user's access to a group or project expires in seven days.
This reminds group or project members to extend their access duration if they want to.
@@ -422,9 +454,12 @@ For example, an email with the reason `assigned` has this sentence in the footer
#### On-call alerts notifications
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
An [on-call alert](../../operations/incident_management/oncall_schedules.md)
notification email can have one of [the alert's](../../operations/incident_management/alerts.md) statuses:
@@ -436,9 +471,12 @@ notification email can have one of [the alert's](../../operations/incident_manag
#### Incident escalation notifications
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
An [incident escalation](../../operations/incident_management/escalation_policies.md)
notification email can have one of [the incident's](../../operations/incident_management/incidents.md) status:
diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md
index 4141d8ffdd67f712dd1564c64548bfe52173a011..9a8aebeec41a7f907dc6b5397da46e7ad478c919 100644
--- a/doc/user/profile/personal_access_tokens.md
+++ b/doc/user/profile/personal_access_tokens.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Personal access tokens
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Personal access tokens can be an alternative to [OAuth2](../../api/oauth2.md) and used to:
@@ -26,11 +29,14 @@ Personal access tokens are:
- Similar to [project access tokens](../project/settings/project_access_tokens.md) and [group access tokens](../group/settings/group_access_tokens.md), but are attached
to a user rather than a project or group.
-NOTE:
+{{< alert type="note" >}}
+
Though required, GitLab usernames are ignored when authenticating with a personal access token.
There is an [issue for tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/212953) to make GitLab
use the username.
+{{< /alert >}}
+
For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/rest/authentication.md#personalprojectgroup-access-tokens).
Alternately, GitLab administrators can use the API to create [impersonation tokens](../../api/rest/authentication.md#impersonation-tokens).
@@ -38,18 +44,28 @@ Use impersonation tokens to automate authentication as a specific user.
## Create a personal access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days is populated in the UI.
-> - Ability to create non-expiring personal access tokens [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0.
-> - Maximum allowable lifetime limit [extended to 400 days](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) in GitLab 17.6 [with a flag](../feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
-> - Personal access token description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443819) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days is populated in the UI.
+- Ability to create non-expiring personal access tokens [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0.
+- Maximum allowable lifetime limit [extended to 400 days](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) in GitLab 17.6 [with a flag](../feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+- Personal access token description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443819) in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the extended maximum allowable lifetime limit is controlled by a feature flag.
For more information, see the history.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The ability to create personal access tokens without an expiry date was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0. For more information on when personal access tokens expire and expiry dates are added to existing tokens, see the documentation on [access token expiration](#access-token-expiration).
+{{< /alert >}}
+
You can create as many personal access tokens as you like.
1. On the left sidebar, select your avatar.
@@ -79,30 +95,43 @@ to the URL. For example:
https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry
```
-WARNING:
+{{< alert type="warning" >}}
+
Personal access tokens must be treated carefully. Read our [token security considerations](../../security/tokens/_index.md#security-considerations)
for guidance on managing personal access tokens (for example, setting a short expiry and using minimal scopes).
+{{< /alert >}}
+
## Revoke or rotate a personal access token
-> - Ability to use the UI to rotate a personal access token [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241523) in GitLab 17.7.
+{{< history >}}
+
+- Ability to use the UI to rotate a personal access token [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241523) in GitLab 17.7.
+
+{{< /history >}}
At any time, you can use the UI to revoke or, in GitLab 17.7 and later, rotate a personal access token.
1. On the left sidebar, select your avatar.
1. Select **Edit profile**.
1. On the left sidebar, select **Access tokens**.
-1. In the **Active personal access tokens** area, for the relevant token, select **Revoke** (**{remove}**) or **Rotate** (**{retry}**).
+1. In the **Active personal access tokens** area, for the relevant token, select **Revoke** ({{< icon name="remove" >}}) or **Rotate** ({{< icon name="retry" >}}).
1. On the confirmation dialog, select **Revoke** or **Rotate**.
- WARNING:
+ {{< alert type="warning" >}}
+
These actions cannot be undone. Any tools that rely on a revoked or rotated access token will stop working.
+ {{< /alert >}}
+
## Disable personal access tokens
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
@@ -113,16 +142,27 @@ or the Admin UI to disable personal access tokens.
### Use the application settings API
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384201) in GitLab 15.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384201) in GitLab 15.7.
+
+{{< /history >}}
In GitLab 15.7 and later, you can use the [`disable_personal_access_tokens` attribute in the application settings API](../../api/settings.md#available-settings) to disable personal access tokens.
-NOTE:
+{{< alert type="note" >}}
+
After you have used the API to disable personal access tokens, those tokens cannot be used in subsequent API calls to manage this setting. To re-enable personal access tokens, you must use the [GitLab Rails console](../../administration/operations/rails_console.md). You can also upgrade to GitLab 17.3 or later so you can use the Admin UI instead.
+{{< /alert >}}
+
### Use the Admin UI
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436991) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436991) in GitLab 17.3.
+
+{{< /history >}}
In GitLab 17.3 and later, you can use the Admin UI to disable personal access tokens:
@@ -134,9 +174,13 @@ In GitLab 17.3 and later, you can use the Admin UI to disable personal access to
### Disable personal access tokens for enterprise users
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369504) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `enterprise_disable_personal_access_tokens`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/369504) in GitLab 17.2
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/369504) in GitLab 17.3 . Feature flag `enterprise_disable_personal_access_tokens` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369504) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `enterprise_disable_personal_access_tokens`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/369504) in GitLab 17.2
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/369504) in GitLab 17.3 . Feature flag `enterprise_disable_personal_access_tokens` removed.
+
+{{< /history >}}
Prerequisites:
@@ -149,9 +193,12 @@ Disabling the personal access tokens of a group's [enterprise users](../enterpri
- Disables the existing personal access tokens of the enterprise users.
- Disables OAuth tokens. This prevents usage of the [Web IDE](../project/web_ide/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
Disabling personal access tokens for enterprise users does not disable personal access tokens for [service accounts](service_accounts.md).
+{{< /alert >}}
+
To disable the enterprise users' personal access tokens:
1. On the left sidebar, select **Search or go to** and find your group or subgroup.
@@ -164,9 +211,13 @@ When you delete or block an enterprise user account, their personal access token
## View token usage information
-> - In GitLab 16.0 and earlier, token usage information is updated every 24 hours.
-> - The frequency of token usage information updates [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/410168) in GitLab 16.1 from 24 hours to 10 minutes.
-> - Ability to view IP addresses [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428577) in GitLab 17.8 [with a flag](../../administration/feature_flags.md) named `pat_ip`. Enabled by default in 17.9.
+{{< history >}}
+
+- In GitLab 16.0 and earlier, token usage information is updated every 24 hours.
+- The frequency of token usage information updates [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/410168) in GitLab 16.1 from 24 hours to 10 minutes.
+- Ability to view IP addresses [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/428577) in GitLab 17.8 [with a flag](../../administration/feature_flags.md) named `pat_ip`. Enabled by default in 17.9.
+
+{{< /history >}}
Token usage information is updated every 10 minutes. GitLab considers a token used when the token is used to:
@@ -183,12 +234,16 @@ To view the last time a token was used, and the IP addresses from where the toke
## Personal access token scopes
-> - Personal access tokens no longer being able to access container or package registries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387721) in GitLab 16.0.
-> - `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default.
-> - Feature flag `k8s_proxy_pat` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131518) in GitLab 16.5.
-> - `read_service_ping` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/42692#note_1222832412) in GitLab 17.1.
-> - `manage_runner` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460721) in GitLab 17.1.
-> - `self_rotate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178111) in GitLab 17.9. Enabled by default.
+{{< history >}}
+
+- Personal access tokens no longer being able to access container or package registries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387721) in GitLab 16.0.
+- `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default.
+- Feature flag `k8s_proxy_pat` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131518) in GitLab 16.5.
+- `read_service_ping` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/42692#note_1222832412) in GitLab 17.1.
+- `manage_runner` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460721) in GitLab 17.1.
+- `self_rotate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178111) in GitLab 17.9. Enabled by default.
+
+{{< /history >}}
A personal access token can perform actions based on the assigned scopes.
@@ -210,17 +265,27 @@ A personal access token can perform actions based on the assigned scopes.
| `self_rotate` | Grants permission to rotate this token using the [personal access token API](../../api/personal_access_tokens.md#rotate-a-personal-access-token). Does not allow rotation of other tokens. |
| `read_service_ping`| Grant access to download Service Ping payload through the API when authenticated as an admin use. |
-WARNING:
+{{< alert type="warning" >}}
+
If you enabled [external authorization](../../administration/settings/external_authorization.md), personal access tokens cannot access container or package registries. If you use personal access tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use personal access tokens with container or package registries.
+{{< /alert >}}
+
## Access token expiration
-> - Maximum token lifetime of 400 days [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241523) in GitLab 17.6 [with a flag](../feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+{{< history >}}
+
+- Maximum token lifetime of 400 days [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241523) in GitLab 17.6 [with a flag](../feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the extended maximum allowable lifetime limit is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Personal access tokens expire on the date you define, at midnight, 00:00 AM UTC. A token with the expiration date of 2024-01-01 expires at 00:00:00 UTC on 2024-01-01.
- GitLab runs a check at 1:00 AM UTC every day to identify personal access tokens that expire soon. The owners of these tokens are [notified by email](#personal-access-token-expiry-emails).
@@ -266,8 +331,12 @@ automatically applied:
### Personal access token expiry emails
-> - Sixty and thirty day expiry notification emails [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464040) in GitLab 17.6 [with a flag](../../administration/feature_flags.md) named `expiring_pats_30d_60d_notifications`. Disabled by default.
-> - Sixty and thirty day notification emails [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173792) in GitLab 17.7. Feature flag `expiring_pats_30d_60d_notifications` removed.
+{{< history >}}
+
+- Sixty and thirty day expiry notification emails [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464040) in GitLab 17.6 [with a flag](../../administration/feature_flags.md) named `expiring_pats_30d_60d_notifications`. Disabled by default.
+- Sixty and thirty day notification emails [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173792) in GitLab 17.7. Feature flag `expiring_pats_30d_60d_notifications` removed.
+
+{{< /history >}}
GitLab runs a check every day at 1:00 AM UTC to identify personal access tokens that are expiring in the near future. The owners of these tokens are notified by email when these tokens expire in a certain number of days. The number of days differs depending on the version of GitLab:
@@ -282,9 +351,12 @@ You can subscribe to an iCalendar endpoint which contains events at the expiry d
You can [create a personal access token for a service account](../../api/group_service_accounts.md#create-a-personal-access-token-for-a-service-account-user) with no expiry date. These personal access tokens never expire, unlike non-service account personal access tokens.
-NOTE:
+{{< alert type="note" >}}
+
Allowing personal access tokens for service accounts to be created with no expiry date only affects tokens created after you change this setting. It does not affect existing tokens.
+{{< /alert >}}
+
#### GitLab.com
Prerequisites:
@@ -312,9 +384,12 @@ You can now create personal access tokens for a service account user with no exp
## Create a personal access token programmatically
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can create a predetermined personal access token
as part of your tests or automation.
@@ -356,9 +431,12 @@ sudo gitlab-rails runner "token = User.find_by_username('automation-bot').person
## Revoke a personal access token programmatically
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can programmatically revoke a personal access token
as part of your tests or automation.
@@ -392,9 +470,12 @@ sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here12
## Clone repository using personal access token
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To clone a repository when SSH is disabled, clone it using a personal access token by running the following command:
@@ -421,15 +502,21 @@ Remember this if you set up an automation pipeline that depends on authenticatio
### Unrevoke a personal access token
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If a personal access token is revoked accidentally by any method, administrators can unrevoke that token. By default, a daily job deletes revoked tokens at 1:00 AM system time.
-WARNING:
+{{< alert type="warning" >}}
+
Running the following commands changes data directly. This could be damaging if not done correctly, or under the right conditions. You should first run these commands in a test environment with a backup of the instance ready to be restored, just in case.
+{{< /alert >}}
+
1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session).
1. Unrevoke the token:
diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md
index a6206aa4f4b8dccd0a833f15ec9b1dddad3f7282..5534721e7e7cbc059740f736d17839da3a3ddbf5 100644
--- a/doc/user/profile/preferences.md
+++ b/doc/user/profile/preferences.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Profile preferences
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can update your preferences to change the look and feel of GitLab.
@@ -25,7 +28,11 @@ To change the color theme:
### Dark mode
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [experiment](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252).
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [experiment](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252).
+
+{{< /history >}}
Dark mode makes elements on the GitLab UI stand out on a dark background.
@@ -35,7 +42,11 @@ Dark mode works only with the **Dark** Syntax highlighting theme. You can report
## Change the syntax highlighting theme
-> - Changing the default syntax highlighting theme for authenticated and unauthenticated users [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25129) in GitLab 15.1.
+{{< history >}}
+
+- Changing the default syntax highlighting theme for authenticated and unauthenticated users [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25129) in GitLab 15.1.
+
+{{< /history >}}
Syntax highlighting is a feature in code editors and IDEs. The highlighter assigns a color to each type of code, such as strings and comments.
@@ -85,7 +96,11 @@ To change the layout width of your UI:
### Set the default text editor
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423104) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423104) in GitLab 17.7.
+
+{{< /history >}}
You can set a default editor for editing content in GitLab.
If you do not choose a default text editor, your last used choice is preserved.
@@ -99,13 +114,20 @@ If you do not choose a default text editor, your last used choice is preserved.
### Choose your home organization
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419079) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `ui_for_organizations`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419079) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `ui_for_organizations`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag. For more information, see the history.
On GitLab.com and GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
+{{< /alert >}}
+
If you are a member of two or more [organizations](../organization/_index.md), you can choose a home organization.
This is the organization you are in by default when you first sign in to GitLab.
@@ -119,12 +141,19 @@ To choose your home organization:
### Choose your homepage
-> - [Homepage options changed](https://gitlab.com/groups/gitlab-org/-/epics/13066) in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `your_work_projects_vue`. Disabled by default.
+{{< history >}}
+
+- [Homepage options changed](https://gitlab.com/groups/gitlab-org/-/epics/13066) in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `your_work_projects_vue`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
When the `your_work_projects_vue` feature flag is enabled, the **Your Contributed Projects** view becomes the default option, and an additional **Member Projects** option is available in the dropdown list. For more information, see the history.
-Control what page you view when you select the GitLab logo (**{tanuki}**). You can set your homepage to be Your Projects (default), Your Groups, Your Activity, and other content.
+{{< /alert >}}
+
+Control what page you view when you select the GitLab logo ({{< icon name="tanuki" >}}). You can set your homepage to be Your Projects (default), Your Groups, Your Activity, and other content.
To choose your homepage view:
@@ -189,7 +218,7 @@ You can view changes to whitespace in diffs.
To view diffs on the Web IDE, follow these steps:
-1. On the left sidebar, select **Source Control** (**{branch}**).
+1. On the left sidebar, select **Source Control** ({{< icon name="branch" >}}).
1. Under the **Changes** tab, select your file.
### Show whitespace changes in diffs
@@ -311,7 +340,11 @@ To use exact times on the GitLab UI:
### Customize time format
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15206) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15206) in GitLab 16.6.
+
+{{< /history >}}
You can customize the format used to display times of activities on your group and project overview pages and user
profiles. You can display times as:
@@ -331,19 +364,29 @@ To customize the time format:
## Disable exact code search
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 15.9 [with flags](../../administration/feature_flags.md) named `index_code_with_zoekt` and `search_code_with_zoekt`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/388519) in GitLab 16.6.
-> - Feature flags `index_code_with_zoekt` and `search_code_with_zoekt` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148378) in GitLab 17.1.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 15.9 [with flags](../../administration/feature_flags.md) named `index_code_with_zoekt` and `search_code_with_zoekt`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/388519) in GitLab 16.6.
+- Feature flags `index_code_with_zoekt` and `search_code_with_zoekt` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148378) in GitLab 17.1.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature is in [beta](../../policy/development_stages_support.md#beta) and subject to change without notice.
For more information, see [epic 9404](https://gitlab.com/groups/gitlab-org/-/epics/9404).
+{{< /alert >}}
+
Prerequisites:
- For [GitLab Self-Managed](../../subscriptions/self_managed/_index.md), an administrator must
@@ -359,7 +402,11 @@ To disable [exact code search](../search/exact_code_search.md) in user preferenc
## User identities in CI job JSON web tokens
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387537) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387537) in GitLab 16.0.
+
+{{< /history >}}
CI/CD jobs generate JSON web tokens, which can include a list of your external identities.
Instead of making separate API calls to get individual accounts, you can find your user identities in a single authentication token.
@@ -369,7 +416,11 @@ To enable including external identities, see [Token payload](../../ci/secrets/id
## Control follower engagement
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325558) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325558) in GitLab 16.0.
+
+{{< /history >}}
Turn off the ability to follow or be followed by other GitLab users. By default, your user profile, including your name and profile photo, is public in the **Following** tabs of other users. When you deactivate this setting:
@@ -420,18 +471,28 @@ You must be the administrator of the GitLab instance to configure GitLab with So
### Integrate with the extension marketplace
-DETAILS:
-**Offering:** GitLab.com
+{{< details >}}
+
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151352) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 17.0 [with flags](../../administration/feature_flags.md) named `web_ide_oauth` and `web_ide_extensions_marketplace`. Disabled by default.
+- Feature flag `web_ide_oauth` [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163181) and feature flag `web_ide_extensions_marketplace` [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/459028) in GitLab 17.4.
+- Feature flag `web_ide_oauth` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167464) in GitLab 17.5.
+- Enabled by default for [workspaces](../workspace/_index.md) in GitLab 17.6. Workspaces do not require any feature flags for the extension marketplace to be available.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151352) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 17.0 [with flags](../../administration/feature_flags.md) named `web_ide_oauth` and `web_ide_extensions_marketplace`. Disabled by default.
-> - Feature flag `web_ide_oauth` [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163181) and feature flag `web_ide_extensions_marketplace` [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/459028) in GitLab 17.4.
-> - Feature flag `web_ide_oauth` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167464) in GitLab 17.5.
-> - Enabled by default for [workspaces](../workspace/_index.md) in GitLab 17.6. Workspaces do not require any feature flags for the extension marketplace to be available.
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
You can use the [extension marketplace](../project/web_ide/_index.md#extension-marketplace) to search and
manage extensions for the [Web IDE](../project/web_ide/_index.md) and [workspaces](../workspace/_index.md).
For third-party extensions, you must enable the marketplace in user preferences.
@@ -445,9 +506,12 @@ To enable the extension marketplace for the Web IDE and workspaces:
1. In the third-party extension acknowledgement, select **I understand**.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
This preferences checkbox will always be available, even if the feature flags are disabled.
+{{< /alert >}}
+
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/user/profile/service_accounts.md b/doc/user/profile/service_accounts.md
index 1541b273a9b18d6e8237ca98262cf4d5c42b2da6..116d9dcdda4b87a5a30bbeba106559c10cbf0c3a 100644
--- a/doc/user/profile/service_accounts.md
+++ b/doc/user/profile/service_accounts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Service accounts
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A service account is a type of machine user that is not tied to an individual human
user.
@@ -53,9 +56,13 @@ How you create an account differs depending on whether you are a:
### Top-level group Owners
-> - Introduced for GitLab.com in GitLab 16.3
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163726) in GitLab 17.5 [with a feature flag](../../administration/feature_flags.md) named `allow_top_level_group_owners_to_create_service_accounts` for GitLab Self-Managed. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172502) in GitLab 17.6. Feature flag `allow_top_level_group_owners_to_create_service_accounts` removed.
+{{< history >}}
+
+- Introduced for GitLab.com in GitLab 16.3
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163726) in GitLab 17.5 [with a feature flag](../../administration/feature_flags.md) named `allow_top_level_group_owners_to_create_service_accounts` for GitLab Self-Managed. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172502) in GitLab 17.6. Feature flag `allow_top_level_group_owners_to_create_service_accounts` removed.
+
+{{< /history >}}
Prerequisites:
@@ -82,8 +89,11 @@ Prerequisites:
### Administrators in GitLab Self-Managed
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Prerequisites:
@@ -180,8 +190,11 @@ To delete a service account, [use the service accounts API to delete the service
#### Administrators in GitLab Self-Managed
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Prerequisites:
diff --git a/doc/user/profile/user_passwords.md b/doc/user/profile/user_passwords.md
index cfdc4992f1e00c91177181c98b9f77d21b633d68..4a330f1a0321614a45e7de032a298b53e76e2c55 100644
--- a/doc/user/profile/user_passwords.md
+++ b/doc/user/profile/user_passwords.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: User passwords
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you use a password to sign in to GitLab, a strong password is very important. A weak or guessable password makes it
easier for unauthorized people to sign in to your account.
@@ -26,7 +29,11 @@ authorization provider, you do not need to choose a password. GitLab
## Change your password
-> - Password reset emails sent to any verified email address [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16311) in GitLab 16.1.
+{{< history >}}
+
+- Password reset emails sent to any verified email address [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16311) in GitLab 16.1.
+
+{{< /history >}}
You can change your password. GitLab enforces [password requirements](#password-requirements) when you choose your new
password.
@@ -46,10 +53,13 @@ message:
> "If your email address exists in our database, you will receive a password recovery link at your email address in a few minutes."
-NOTE:
+{{< alert type="note" >}}
+
Your account can have more than one verified email address, and any email address
associated with your account can be verified.
+{{< /alert >}}
+
## Password requirements
Your passwords must meet a set of requirements when:
@@ -74,9 +84,13 @@ Self-managed installations can configure the following additional password requi
## Block weak passwords
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23610) in GitLab 15.4 [with a flag](../../administration/feature_flags.md) named `block_weak_passwords`, weak passwords aren't accepted. Disabled by default on GitLab Self-Managed.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/363445) on GitLab.com in GitLab 15.6.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/363445) and enabled on GitLab Self-Managed in GitLab 15.7. Feature flag `block_weak_passwords` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23610) in GitLab 15.4 [with a flag](../../administration/feature_flags.md) named `block_weak_passwords`, weak passwords aren't accepted. Disabled by default on GitLab Self-Managed.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/363445) on GitLab.com in GitLab 15.6.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/363445) and enabled on GitLab Self-Managed in GitLab 15.7. Feature flag `block_weak_passwords` removed.
+
+{{< /history >}}
GitLab disallows weak passwords. Your password is considered weak when it:
diff --git a/doc/user/project/_index.md b/doc/user/project/_index.md
index 809c44f218ac8d5e89b00021c6903f6b72ecd66a..fe01e72005732e278ebedc20a7421b38d658127c 100644
--- a/doc/user/project/_index.md
+++ b/doc/user/project/_index.md
@@ -1,13 +1,16 @@
---
stage: Tenant Scale
group: Organizations
-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"
+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
title: Create a project
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You have different options to create a project. You can create a blank project, create a project
from built-in or custom templates, or [create a project with `git push`](../../topics/git/project.md).
@@ -16,7 +19,7 @@ from built-in or custom templates, or [create a project with `git push`](../../t
To create a blank project:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create blank project**.
1. Enter the project details:
1. **Project name**: Enter the name of your project.
@@ -41,7 +44,7 @@ Anyone can [contribute to built-in project templates](../../development/project_
To create a project from a built-in template:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. Select the **Built-in** tab.
1. From the list of templates:
@@ -56,11 +59,14 @@ To create a project from a built-in template:
See the [viewing and access rights](../public_access.md) for users.
1. Select **Create project**.
-NOTE:
+{{< alert type="note" >}}
+
If a user creates a project from a template, or [imports a project](settings/import_export.md#import-a-project-and-its-data),
they are shown as the author of the imported items, which retain the original timestamp from the template or import.
This can make items appear as if they were created before the user's account existed.
+{{< /alert >}}
+
Imported objects are labeled as `By <username> on <timestamp>`.
Before GitLab 17.1, the label was suffixed with `(imported from GitLab)`.
@@ -71,7 +77,7 @@ HIPAA Audit Protocol published by the U.S Department of Health and Human Service
To create a project from the HIPAA Audit Protocol template:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. Select the **Built-in** tab.
1. Locate the **HIPAA Audit Protocol** template:
@@ -93,7 +99,7 @@ and [group](../group/custom_project_templates.md).
To create a project from a custom template:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from template**.
1. Select the **Instance** or **Group** tab.
1. From the list of templates:
@@ -109,22 +115,32 @@ To create a project from a custom template:
## Create a project that uses SHA-256 hashing
-DETAILS:
-**Status:** Experiment
+{{< details >}}
+
+- Status: Experiment
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431864) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `support_sha256_repositories`. Disabled by default. This feature is an [experiment](../../policy/development_stages_support.md#experiment).
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431864) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `support_sha256_repositories`. Disabled by default. This feature is an [experiment](../../policy/development_stages_support.md#experiment).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
You can select SHA-256 hashing for a project only when you create the project.
Git does not support migrating to SHA-256 later, or migrating back to SHA-1.
To create a project that uses SHA-256 hashing:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Enter the project details:
- **Project name**: Enter the name of your project.
- **Project slug**: Enter the path to your project. GitLab uses the slug as the URL path.
diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md
index 314141d64d27eeaba1553e2ce868996083fd8ad0..5390b9ad33c5efbe0150e9cb0d6602d015cc2731 100644
--- a/doc/user/project/autocomplete_characters.md
+++ b/doc/user/project/autocomplete_characters.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Autocomplete characters in Markdown fields."
+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
+description: Autocomplete characters in Markdown fields.
title: Autocomplete characters
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The autocomplete characters provide a quick way of entering field values into
Markdown fields. When you start typing a word in a Markdown field with one of
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md
index caa827d960c8b4df278b8a987a5a437abe85a311..1c3b3a3ffee0070c230a218ad3838abcc0868745 100644
--- a/doc/user/project/badges.md
+++ b/doc/user/project/badges.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Badges
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Badges are a unified way to present condensed pieces of information about your projects.
A badge consists of a small image and a URL that the image points to.
@@ -87,9 +90,12 @@ The following table shows the default test coverage limits and badge colors:
| Low | 0 up to 75% | <span style="color: #e05d44">â– </span> `#e05d44` |
| Unknown | No coverage | <span style="color: #9f9f9f">â– </span> `#9f9f9f` |
-NOTE:
+{{< alert type="note" >}}
+
*Up to* means up to, but not including, the upper bound.
+{{< /alert >}}
+
### Change the default limits
You can override the default limits by passing the following query parameters in the coverage report badge URL:
@@ -161,10 +167,13 @@ page of any project that belongs to the group.
By adding a badge to a group, you add and enforce a project-level badge
for all projects in the group.
-NOTE:
+{{< alert type="note" >}}
+
While these badges appear as project-level badges in the codebase, they
cannot be edited or deleted at the project level.
+{{< /alert >}}
+
If you need individual badges for each project, either:
- Add the badge at the [project level](#project-badges).
@@ -201,9 +210,12 @@ Then you can use the link to embed the badge in your HTML or Markdown pages.
1. Expand **General pipelines**.
1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images.
-NOTE:
+{{< alert type="note" >}}
+
The pipeline status badge is based on specific Git revisions (branches). Ensure you select the appropriate branch to view the correct pipeline status.
+{{< /alert >}}
+
## Customize badges
You can customize the following aspects of a badge:
@@ -282,7 +294,7 @@ To edit a badge in a project or group:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Settings > General**.
1. Expand **Badges**.
-1. Next to the badge you want to edit, select **Edit** (**{pencil}**).
+1. Next to the badge you want to edit, select **Edit** ({{< icon name="pencil" >}}).
1. Edit the **Name**, **Link**, or **Badge image URL**.
1. Select **Save changes**.
@@ -293,12 +305,15 @@ To delete a badge in a project or group:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Settings > General**.
1. Expand **Badges**.
-1. Next to the badge you want to delete, select **Delete** (**{remove}**).
+1. Next to the badge you want to delete, select **Delete** ({{< icon name="remove" >}}).
1. On the confirmation dialog, select **Delete badge**.
-NOTE:
+{{< alert type="note" >}}
+
Badges associated with a group can be edited or deleted only at the [group level](#group-badges).
+{{< /alert >}}
+
## Placeholders
Both the URL a badge points to and the image URL can contain placeholders,
@@ -318,8 +333,11 @@ The following placeholders are available:
project's repository
- `%{latest_tag}`: Latest tag added to the project's repository
-NOTE:
+{{< alert type="note" >}}
+
Placeholders allow badges to expose otherwise-private information, such as the
default branch or commit SHA when the project is configured to have a private
repository. This behavior is intentional, as badges are intended to be used publicly. Avoid
using these placeholders if the information is sensitive.
+
+{{< /alert >}}
diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md
index 91bc20e004c0b04fa14a839dc126220fdb7f5459..0c217c1bc11b4f3ffacd29c9275f39e90aae3fc0 100644
--- a/doc/user/project/canary_deployments.md
+++ b/doc/user/project/canary_deployments.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Canary deployments
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Canary deployments are a popular [continuous deployment](https://en.wikipedia.org/wiki/Continuous_deployment)
strategy, where a small portion of the fleet is updated to the new version of
@@ -72,9 +75,12 @@ Here's an example setup flow from scratch:
### Show Canary Ingress deployments on deploy boards (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< /alert >}}
+
To view canary deployments you must properly configure deploy boards:
1. Follow the steps to [enable deploy boards](deploy_boards.md#enabling-deploy-boards).
@@ -99,9 +105,12 @@ can quickly notice them.
#### How to check the current traffic weight on a Canary Ingress (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< /alert >}}
+
1. Visit the [deploy board](deploy_boards.md).
1. View the current weights on the right.
@@ -109,9 +118,12 @@ This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/e
#### How to change the traffic weight on a Canary Ingress (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+{{< /alert >}}
+
You can change the traffic weight in your environment's deploy board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql),
or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line).
diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md
index 1b8f2653314f655a056801c347f926c6ec2295fc..6fbc7018b6fc82f9f44de168385342266296c785 100644
--- a/doc/user/project/changelogs.md
+++ b/doc/user/project/changelogs.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Build, automate, and customize changelogs in your GitLab project."
+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
+description: Build, automate, and customize changelogs in your GitLab project.
title: Changelogs
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Changelogs are generated based on commit titles and Git trailers. To be included
in a changelog, a commit must contain a specific Git trailer. Changelogs are generated
@@ -71,7 +74,11 @@ in the API documentation.
### From the GitLab CLI
-> - [Introduced](https://gitlab.com/gitlab-org/cli/-/merge_requests/1222) in `glab` version 1.30.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/cli/-/merge_requests/1222) in `glab` version 1.30.0.
+
+{{< /history >}}
Prerequisites:
@@ -136,7 +143,11 @@ The file supports these variables:
### Custom templates
-> - Default template [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155806) from using `commit.reference` and `merge_request.reference` to `commit.web_url` and `merge_request.web_url` in GitLab 17.1.
+{{< history >}}
+
+- Default template [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155806) from using `commit.reference` and `merge_request.reference` to `commit.web_url` and `merge_request.web_url` in GitLab 17.1.
+
+{{< /history >}}
Category sections are generated using a template. The default template:
@@ -252,7 +263,11 @@ When specifying the template you should use `template: |` and not
### Template data
-> - `commit.web_url` and `merge_request.web_url` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155806) in GitLab 17.1.
+{{< history >}}
+
+- `commit.web_url` and `merge_request.web_url` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155806) in GitLab 17.1.
+
+{{< /history >}}
At the top level, the following variable is available:
diff --git a/doc/user/project/clusters/_index.md b/doc/user/project/clusters/_index.md
index b483c26f68bd8babb8c7dd808462364170b12de9..2d6f2b670bd3c5b3ba104240b9bb4fcb4a78c91f 100644
--- a/doc/user/project/clusters/_index.md
+++ b/doc/user/project/clusters/_index.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project-level Kubernetes clusters (certificate-based) (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8)
in GitLab 14.5. To connect clusters to GitLab, use the
[GitLab agent](../../clusters/agent/_index.md).
+{{< /alert >}}
+
[Project-level](../../infrastructure/clusters/connect/_index.md#cluster-levels-deprecated) Kubernetes clusters
allow you to connect a Kubernetes cluster to a project in GitLab.
diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md
index 57cb224011e21289ddee013fe81ae8ab0303d125..c73dd6a491710ae9b11521c3b7ff026cf42654d2 100644
--- a/doc/user/project/clusters/add_eks_clusters.md
+++ b/doc/user/project/clusters/add_eks_clusters.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Connect EKS clusters through cluster certificates (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/_index.md)
to create new clusters.
+{{< /alert >}}
+
Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic
Kubernetes Service (EKS).
@@ -27,7 +33,11 @@ To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastr
### How to create a new cluster on EKS through cluster certificates (deprecated)
-> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0.
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0.
+
+{{< /history >}}
Prerequisites:
@@ -162,9 +172,12 @@ create another IAM role (**role B**) for GitLab authentication with AWS:
After about 10 minutes, your cluster is ready to go.
-NOTE:
+{{< alert type="note" >}}
+
If you have [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) `kubectl` and you would like to manage your cluster with it, you must add your AWS external ID in the AWS configuration. For more information on how to configure AWS CLI, see [using an IAM role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount).
+{{< /alert >}}
+
#### Cluster settings
When you create a new cluster, you have the following settings:
@@ -221,9 +234,12 @@ on the running pod.
## Additional requirements for self-managed instances
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you are using GitLab Self-Managed, you need to configure
Amazon credentials. GitLab uses these credentials to assume an Amazon IAM role to create your cluster.
@@ -320,8 +336,11 @@ If the `Cluster` resource failed with the error
`The provided role doesn't have the Amazon EKS Managed Policies associated with it.`,
the role specified in **Role name** is not configured correctly.
-NOTE:
+{{< alert type="note" >}}
+
This role should be the role you created by following the
[EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) guide.
In addition to the policies that guide suggests, you must also include the
`AmazonEKSClusterPolicy` policy for this role in order for GitLab to manage the EKS cluster correctly.
+
+{{< /alert >}}
diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md
index dce6458b177b477d730998909297dbc4db38c346..fe35c39d1aa1806b87865f4c713c90968b07ec2e 100644
--- a/doc/user/project/clusters/add_existing_cluster.md
+++ b/doc/user/project/clusters/add_existing_cluster.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Connect existing clusters through cluster certificates (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/_index.md)
instead.
+{{< /alert >}}
+
If you have an existing Kubernetes cluster, you can add it to a project, group,
or instance and benefit from the integration with GitLab.
@@ -39,11 +49,14 @@ To host them on premises and with other providers,
use either the EKS or GKE method to guide you through and enter your cluster's
settings manually.
-WARNING:
+{{< alert type="warning" >}}
+
GitLab doesn't support `arm64` clusters. See the issue
[Helm Tiller fails to install on `arm64` cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838)
for details.
+{{< /alert >}}
+
### EKS clusters
To add an existing **EKS** cluster, you need:
@@ -68,8 +81,8 @@ To add an existing **GKE** cluster, you need:
To add a Kubernetes cluster to your project, group, or instance:
1. Go to your:
- 1. Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster.
- 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster.
+ 1. Project's {{< icon name="cloud-gear" >}} **Operate > Kubernetes clusters** page, for a project-level cluster.
+ 1. Group's {{< icon name="cloud-gear" >}} **Kubernetes** page, for a group-level cluster.
1. The **Admin** area's **Kubernetes** page, for an instance-level cluster.
1. On the **Kubernetes clusters** page, select the **Connect with a certificate** option from the **Actions** dropdown list.
1. On the **Connect a cluster** page, fill in the details:
@@ -155,10 +168,13 @@ To add a Kubernetes cluster to your project, group, or instance:
kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password>
```
- NOTE:
+ {{< alert type="note" >}}
+
Basic Authentication can be turned on and the password credentials
can be obtained using the Google Cloud Console.
+ {{< /alert >}}
+
Output:
```shell
@@ -217,12 +233,15 @@ integration to work properly.
-WARNING:
+{{< alert type="warning" >}}
+
Disabling RBAC means that any application running in the cluster,
or user who can authenticate to the cluster, has full API access. This is a
[security concern](../../infrastructure/clusters/connect/_index.md#security-implications-for-clusters-connected-with-certificates),
and may not be desirable.
+{{< /alert >}}
+
To effectively disable RBAC, global permissions can be applied granting full access:
```shell
diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md
index b51fc7bd56eaba2c91ad61f4fb6dab7ca388353c..2a25265e99ae739f7571e71e944cd8308c80ffb6 100644
--- a/doc/user/project/clusters/add_gke_clusters.md
+++ b/doc/user/project/clusters/add_gke_clusters.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Connect GKE clusters through cluster certificates (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
Use [Infrastructure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md)
to create a cluster hosted on Google Kubernetes Engine (GKE).
+{{< /alert >}}
+
Through GitLab, you can create new and connect existing clusters
hosted on Google Kubernetes Engine (GKE).
@@ -32,7 +42,11 @@ To create a new GKE cluster from GitLab, use [Infrastructure as Code](../../infr
## Create a new cluster on GKE through cluster certificates
-> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0.
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0.
+
+{{< /history >}}
Prerequisites:
@@ -61,9 +75,9 @@ To create new Kubernetes clusters to your project, group, or instance, through
cluster certificates:
1. Go to your:
- - Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level
+ - Project's {{< icon name="cloud-gear" >}} **Operate > Kubernetes clusters** page, for a project-level
cluster.
- - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster.
+ - Group's {{< icon name="cloud-gear" >}} **Kubernetes** page, for a group-level cluster.
- The **Admin** area's **Kubernetes** page, for an instance-level cluster.
1. Select **Integrate with a cluster certificate**.
1. Under the **Create new cluster** tab, select **Google GKE**.
diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md
index 0a58ac88f889ebd48a2f802950816e1d64e32bce..fb7c82a3998f94a32329105fc113fa13430e3c43 100644
--- a/doc/user/project/clusters/add_remove_clusters.md
+++ b/doc/user/project/clusters/add_remove_clusters.md
@@ -5,23 +5,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Add a cluster using cluster certificates (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0.
To create and manage a new cluster use [Infrastructure as Code](../../infrastructure/iac/_index.md).
+{{< /alert >}}
+
## Disable a cluster
When you successfully connect an existing cluster using cluster certificates, the cluster connection to GitLab becomes enabled. To disable it:
1. Go to your:
- - Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster.
- - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster.
+ - Project's {{< icon name="cloud-gear" >}} **Operate > Kubernetes clusters** page, for a project-level cluster.
+ - Group's {{< icon name="cloud-gear" >}} **Kubernetes** page, for a group-level cluster.
- The **Admin** area's **Kubernetes** page, for an instance-level cluster.
1. Select the name of the cluster you want to disable.
1. Toggle **GitLab Integration** off (in gray).
@@ -50,9 +60,12 @@ To remove the Kubernetes cluster integration:
### Remove clusters by using the Rails console
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session).
diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md
index 991cff643e639b1d2403ef96a9987dd45e493dc0..9b6405bd80a50ce2a4a91bb4601610ba61079a0f 100644
--- a/doc/user/project/clusters/cluster_access.md
+++ b/doc/user/project/clusters/cluster_access.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Access controls with cluster certificates (RBAC or ABAC) (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/_index.md)
instead.
+{{< /alert >}}
+
When creating a cluster in GitLab, you are asked if you would like to create either:
- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md
index 64a5cf6fada0ec55fda2f24beb99c31badc0bbc3..10cb0b6b32e23b56a3d881297f1605cb4a392b89 100644
--- a/doc/user/project/clusters/deploy_to_cluster.md
+++ b/doc/user/project/clusters/deploy_to_cluster.md
@@ -5,17 +5,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deploy to a Kubernetes cluster with cluster certificates (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/_index.md).
To deploy with the agent, use the [CI/CD workflow](../../clusters/agent/ci_cd_workflow.md).
+{{< /alert >}}
+
A Kubernetes cluster can be the destination for a deployment job. If
- The cluster is integrated with GitLab, special
@@ -139,8 +149,11 @@ Reasons for failure include:
[`environment:name`](../../../ci/environments/_index.md). If your job has no
`environment:name` set, the Kubernetes credentials are not passed to it.
-NOTE:
+{{< alert type="note" >}}
+
Project-level clusters upgraded from GitLab 12.0 or older may be configured
in a way that causes this error. Ensure you clear the
[GitLab-managed cluster](gitlab_managed_clusters.md) option if you want to manage
namespaces and service accounts yourself.
+
+{{< /alert >}}
diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md
index a809e6eb507b711a509270d22fca64601dc06080..943eb52cc158698b37cfbcf717f13d016a3f26af 100644
--- a/doc/user/project/clusters/gitlab_managed_clusters.md
+++ b/doc/user/project/clusters/gitlab_managed_clusters.md
@@ -5,20 +5,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab-managed clusters (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
> - [Disabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/353410) in GitLab 15.0.
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/_index.md).
To manage applications, use the [Cluster Project Management Template](../../clusters/management_project_template.md).
-FLAG:
+{{< /alert >}}
+
+{{< alert type="flag" >}}
+
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `certificate_based_clusters`.
+{{< /alert >}}
+
You can choose to allow GitLab to manage your cluster for you. If your cluster
is managed by GitLab, resources for your projects are automatically created. See
the [Access controls](cluster_access.md) section for
@@ -29,11 +38,14 @@ automatically. If you are using [Auto DevOps](../../../topics/autodevops/_index.
explicitly provide the `KUBE_NAMESPACE` [deployment variable](deploy_to_cluster.md#deployment-variables)
for your deployment jobs to use. Otherwise, a namespace is created for you.
-WARNING:
+{{< alert type="warning" >}}
+
Be aware that manually managing resources that have been created by GitLab, like
namespaces and service accounts, can cause unexpected errors. If this occurs, try
[clearing the cluster cache](#clearing-the-cluster-cache).
+{{< /alert >}}
+
## Clearing the cluster cache
If you allow GitLab to manage your cluster, GitLab stores a cached
diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md
index 971e2ed2831b317c002266997aee95fc2554ed0d..dbcacd65f6df09a527b6e7c59f93b0e89af063e4 100644
--- a/doc/user/project/clusters/multiple_kubernetes_clusters.md
+++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md
@@ -5,15 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Multiple clusters per project with cluster certificates (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
Using multiple Kubernetes clusters for a single project **with cluster
certificates** was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
To connect clusters to GitLab, use the [GitLab agent](../../clusters/agent/_index.md).
+{{< /alert >}}
+
You can associate more than one Kubernetes cluster to your
project. That way you can have different clusters for different environments,
like development, staging, production, and so on.
diff --git a/doc/user/project/clusters/runbooks/_index.md b/doc/user/project/clusters/runbooks/_index.md
index cacc9576faf203bca61f9ad4e027e4955ee04920..d2427ba1cd7085fc40b7c79777ac02ff53ec54fd 100644
--- a/doc/user/project/clusters/runbooks/_index.md
+++ b/doc/user/project/clusters/runbooks/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Runbooks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Runbooks are a collection of documented procedures that explain how to
carry out a particular process, be it starting, stopping, debugging,
diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md
index e1c656f680c2bd5e7388299440598618387249b8..4042ca842f59dbd582b1906d9e0c0feb70090fe8 100644
--- a/doc/user/project/code_intelligence.md
+++ b/doc/user/project/code_intelligence.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Code Review
-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"
-description: "Use code intelligence to find all uses of an object in your project."
+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
+description: Use code intelligence to find all uses of an object in your project.
title: Code intelligence
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Code intelligence adds code navigation features common to interactive
development environments (IDE), including:
@@ -49,7 +52,11 @@ To see how your language is best supported, review the
### With the CI/CD component
-> - Python support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301111) in GitLab 17.9.
+{{< history >}}
+
+- Python support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301111) in GitLab 17.9.
+
+{{< /history >}}
GitLab provides a [CI/CD component](../../ci/components/_index.md) to configure code intelligence
in your `.gitlab-ci.yml` file. The component supports these languages:
@@ -79,9 +86,9 @@ To contribute more languages to the component, open a merge request in the
To enable code intelligence for a project, add GitLab CI/CD jobs to your project's `.gitlab-ci.yml`.
-::Tabs
+{{< tabs >}}
-:::TabTitle With a SCIP indexer
+{{< tab title="With a SCIP indexer" >}}
1. Add a job to your `.gitlab-ci.yml` configuration. This job generates the
SCIP index and converts it to LSIF for use in GitLab:
@@ -114,7 +121,9 @@ SCIP index and converts it to LSIF for use in GitLab:
1. Depending on your CI/CD configuration, you might need to run the job manually,
or wait for it to run as part of an existing pipeline.
-:::TabTitle With a LSIF indexer
+{{< /tab >}}
+
+{{< tab title="With a LSIF indexer" >}}
1. Add a job (`code_navigation`) to your `.gitlab-ci.yml` configuration to generate the index:
@@ -134,14 +143,19 @@ SCIP index and converts it to LSIF for use in GitLab:
1. Depending on your CI/CD configuration, you might need to run the job manually,
or wait for it to run as part of an existing pipeline.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
+
+{{< alert type="note" >}}
-NOTE:
GitLab limits the artifact produced by the code generation jobs to 200 MB by the
[(`ci_max_artifact_size_lsif`)](../../administration/instance_limits.md#maximum-file-size-per-type-of-artifact)
artifact application limit. On GitLab Self-Managed instances, an instance administrator
can change this value.
+{{< /alert >}}
+
## View code intelligence results
After the job succeeds, browse your repository to see code intelligence information:
diff --git a/doc/user/project/codeowners/_index.md b/doc/user/project/codeowners/_index.md
index ca260bb3673e6f157d9a945954a542aad1bc708b..bc7aeaec820b33944400c128aac0672d9d83f8cc 100644
--- a/doc/user/project/codeowners/_index.md
+++ b/doc/user/project/codeowners/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Use Code Owners to define experts for your code base, and set review requirements based on file type or location."
+description: Use Code Owners to define experts for your code base, and set review requirements based on file type or location.
title: Code Owners
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the Code Owners feature to define who has expertise for specific parts of your project's codebase.
Define the owners of files and directories in a repository to:
diff --git a/doc/user/project/codeowners/advanced.md b/doc/user/project/codeowners/advanced.md
index 16d2cbb601ff3a81767c6d654b9d001b164465a5..26a832de3538537d57919de25eda5acc2b9efd0a 100644
--- a/doc/user/project/codeowners/advanced.md
+++ b/doc/user/project/codeowners/advanced.md
@@ -2,7 +2,7 @@
stage: Create
group: Source Code
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
-description: "Use Code Owners to define experts for your code base, and set review requirements based on file type or location."
+description: Use Code Owners to define experts for your code base, and set review requirements based on file type or location.
title: Advanced `CODEOWNERS` configuration
---
@@ -109,18 +109,25 @@ The Code Owner for `terms.md` would be `@legal-team`.
## Require multiple approvals from Code Owners
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335451) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335451) in GitLab 15.9.
+
+{{< /history >}}
You can require multiple approvals for the Code Owners sections in the Approvals area in merge requests.
Append the section name with a number `n` in brackets, for example, `[2]` or `[3]`.
This requires `n` approvals from the Code Owners in this section.
Valid entries for `n` are integers `≥ 1`. `[1]` is optional because it is the default. Invalid values for `n` are treated as `1`.
-WARNING:
+{{< alert type="warning" >}}
+
[Issue 384881](https://gitlab.com/gitlab-org/gitlab/-/issues/385881) proposes changes
to the behavior of this setting. Do not intentionally set invalid values. They may
become valid in the future and cause unexpected behavior.
+{{< /alert >}}
+
To require multiple approvals from Code Owners:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -173,12 +180,15 @@ Inviting **Subgroup Y** to a parent group of **Project A**
[is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/288851). To set **Subgroup Y** as
Code Owners, [invite this group directly to the project](#invite-subgroups-to-projects-in-parent-groups) itself.
-NOTE:
+{{< alert type="note" >}}
+
For approval to be required, groups as Code Owners must have a direct membership
(not inherited membership) in the project. Approval can only be optional for groups
that inherit membership. Members in the Code Owners group also must be direct members,
and not inherit membership from any parent groups.
+{{< /alert >}}
+
### Invite subgroups to projects in parent groups
You can [invite](../members/sharing_projects_groups.md) **Subgroup Y** to **Project A**
@@ -202,7 +212,11 @@ of the merge request becomes optional.
## Error handling
-> - Error validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216066) in GitLab 16.3.
+{{< history >}}
+
+- Error validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216066) in GitLab 16.3.
+
+{{< /history >}}
### Entries with spaces
@@ -280,10 +294,13 @@ If an entry includes no owners, or zero [accessible owners](#inaccessible-or-inc
exist, the entry is invalid. Because this rule can never be satisfied, GitLab
auto-approves it in merge requests.
-NOTE:
+{{< alert type="note" >}}
+
When a protected branch has `Require code owner approval` enabled, rules with
zero owners are still honored.
+{{< /alert >}}
+
### Minimum approvals
When [defining the number of approvals](advanced.md#require-multiple-approvals-from-code-owners) for a section,
diff --git a/doc/user/project/codeowners/reference.md b/doc/user/project/codeowners/reference.md
index cd6a1f214e79b347a01cf72d3f5b10f7630fc29c..c63b17b1fb9d678002eee16f5910f20ea0630a5d 100644
--- a/doc/user/project/codeowners/reference.md
+++ b/doc/user/project/codeowners/reference.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Syntax of `CODEOWNERS` file
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The `CODEOWNERS` file uses a syntax to define ownership rules.
Each line in the file represents a rule, and specifies a file path pattern and one or more owners.
@@ -18,9 +21,12 @@ The key elements are:
- **Comments**: Lines starting with `#` are ignored.
- **Sections**: Optional groupings of rules, defined using `[Section name]`.
-NOTE:
+{{< alert type="note" >}}
+
If an entry is duplicated in a section, [the last entry is used](advanced.md#define-code-owners-for-specific-files-or-directories). Rules defined later in the file take precedence over earlier rules.
+{{< /alert >}}
+
Here are some examples:
```plaintext
@@ -141,8 +147,12 @@ Examples:
### Set default Code Owner for a section
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371711) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `codeowners_default_owners`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115888) in GitLab 15.11. Feature flag `codeowners_default_owners` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371711) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `codeowners_default_owners`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115888) in GitLab 15.11. Feature flag `codeowners_default_owners` removed.
+
+{{< /history >}}
If multiple file paths inside a section share the same ownership, define default
Code Owners for the section.
@@ -209,9 +219,13 @@ section is marked as optional.
## Add a role as a Code Owner
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282438) in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `codeowner_role_approvers`.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/497504) in GitLab 17.8.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/512623) in GitLab 17.9 Feature flag `codeowner_role_approvers` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282438) in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `codeowner_role_approvers`.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/497504) in GitLab 17.8.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/512623) in GitLab 17.9 Feature flag `codeowner_role_approvers` removed.
+
+{{< /history >}}
You can add or set a role for direct project members as Code Owners:
@@ -277,9 +291,12 @@ In this example:
-NOTE:
+{{< alert type="note" >}}
+
When [Global SAML group memberships lock](../../group/saml_sso/group_sync.md#global-saml-group-memberships-lock) is enabled, you cannot set a group or subgroup as a Code Owner. For more information, see [Incompatibility with Global SAML group memberships lock](troubleshooting.md#incompatibility-with-global-saml-group-memberships-lock).
+{{< /alert >}}
+
If you encounter issues, refer to [User not shown as possible approver](troubleshooting.md#user-not-shown-as-possible-approver).
## Path matching
@@ -311,11 +328,14 @@ README.md @username
internal/README.md
```
-NOTE:
+{{< alert type="note" >}}
+
When using globstar paths, be cautious of unintended matches.
For example, `README.md` without a leading `/` matches any `README.md`
file in any directory or subdirectory of the repository.
+{{< /alert >}}
+
### Directory paths
Paths ending with `/` match any file in the directory:
diff --git a/doc/user/project/codeowners/troubleshooting.md b/doc/user/project/codeowners/troubleshooting.md
index 5aa1cb629b406912373bbb93c041e0f86b3a96b3..71d058a375d113ac8d1a96d81b25b0bbf909e769 100644
--- a/doc/user/project/codeowners/troubleshooting.md
+++ b/doc/user/project/codeowners/troubleshooting.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Use Code Owners to define experts for your code base, and set review requirements based on file type or location."
+description: Use Code Owners to define experts for your code base, and set review requirements based on file type or location.
title: Troubleshooting Code Owners
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with Code Owners, you might encounter the following issues.
diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md
index 753b3d7ecc2104025c9ba72105420b01571b393c..3ea5b2e63e530c3206195c91c47b83ec369f2d74 100644
--- a/doc/user/project/deploy_boards.md
+++ b/doc/user/project/deploy_boards.md
@@ -5,30 +5,42 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deploy boards (deprecated)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> - [Disabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/353410) in GitLab 15.0.
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
[An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/2493)
to add this functionality to the [agent](../clusters/agent/_index.md).
-FLAG:
+{{< /alert >}}
+
+{{< alert type="flag" >}}
+
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `certificate_based_clusters`.
+{{< /alert >}}
+
GitLab deploy boards offer a consolidated view of the current health and
status of each CI [environment](../../ci/environments/_index.md) running on [Kubernetes](https://kubernetes.io), displaying the status
of the pods in the deployment. Developers and other teammates can view the
progress and status of a rollout, pod by pod, in the workflow they already use
without any need to access Kubernetes.
-NOTE:
+{{< alert type="note" >}}
+
If you have a Kubernetes cluster, you can Auto Deploy applications to production
environments by using [Auto DevOps](../../topics/autodevops/_index.md).
+{{< /alert >}}
+
## Overview
With deploy boards you can gain more insight into deploys with benefits such as:
@@ -84,13 +96,16 @@ To display the deploy boards for a specific [environment](../../ci/environments/
1. Have a Kubernetes cluster up and running.
- NOTE:
- If you're using OpenShift, ensure that you're using the `Deployment` resource
+ {{< alert type="note" >}}
+
+If you're using OpenShift, ensure that you're using the `Deployment` resource
instead of `DeploymentConfiguration`. Otherwise, the deploy boards don't render
correctly. For more information, read the
[OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations)
and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584).
+ {{< /alert >}}
+
1. [Configure GitLab Runner](../../ci/runners/_index.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or
[`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes/) executor.
1. Configure the [Kubernetes integration](../infrastructure/clusters/_index.md) in your project for the
@@ -146,11 +161,14 @@ spec:
The annotations are applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board.
-NOTE:
+{{< alert type="note" >}}
+
The YAML file is static. If you apply it using `kubectl apply`, you must
manually provide the project and environment slugs, or create a script to
replace the variables in the YAML before applying.
+{{< /alert >}}
+
## Canary Deployments
A popular CI strategy, where a small portion of the fleet is updated to the new
diff --git a/doc/user/project/deploy_keys/_index.md b/doc/user/project/deploy_keys/_index.md
index 60af5cbbc4b8fa8d4d64abad3626fc93cfd76794..c680825b64a01b3f8aab53f9e1ce6ea0e45fbb7a 100644
--- a/doc/user/project/deploy_keys/_index.md
+++ b/doc/user/project/deploy_keys/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deploy keys
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use deploy keys to access repositories that are hosted in GitLab. In most cases, you use deploy keys
to access a repository from an external host, like a build server or Continuous Integration (CI) server.
@@ -111,9 +114,12 @@ name and permissions. If the deploy key is enabled in more than one project, you
## Create a public deploy key
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
@@ -146,7 +152,7 @@ To grant a public deploy key access to a project:
1. Select **Publicly accessible deploy keys**.
1. In the key's row, select **Enable**.
1. To grant read-write permission to the public deploy key:
- 1. In the key's row, select **Edit** (**{pencil}**).
+ 1. In the key's row, select **Edit** ({{< icon name="pencil" >}}).
1. Select the **Grant write permissions to this key** checkbox.
### Edit project access permissions of a deploy key
@@ -160,7 +166,7 @@ To edit the project access permissions of a deploy key:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > Repository**.
1. Expand **Deploy keys**.
-1. In the key's row, select **Edit** (**{pencil}**).
+1. In the key's row, select **Edit** ({{< icon name="pencil" >}}).
1. Select or clear the **Grant write permissions to this key** checkbox.
## Revoke project access of a deploy key
@@ -177,7 +183,7 @@ To disable a deploy key:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > Repository**.
1. Expand **Deploy keys**.
-1. Select **Disable** (**{cancel}**).
+1. Select **Disable** ({{< icon name="cancel" >}}).
What happens to the deploy key when it is disabled depends on the following:
diff --git a/doc/user/project/deploy_tokens/_index.md b/doc/user/project/deploy_tokens/_index.md
index 84c906ff5fd068b0560e23d33f53cc43ff62a184..0cb9bffdcef4376a14b0dd8649c1cb55454a9a5e 100644
--- a/doc/user/project/deploy_tokens/_index.md
+++ b/doc/user/project/deploy_tokens/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Deploy tokens
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use a deploy token to enable authentication of deployment tasks, independent of a user
account. In most cases you use a deploy token from an external host, like a build server or CI/CD
@@ -41,10 +44,13 @@ You can create deploy tokens at either the project or group level:
By default, a deploy token does not expire. You can optionally set an expiry date when you create
it. Expiry occurs at midnight UTC on that date.
-WARNING:
+{{< alert type="warning" >}}
+
You cannot use new or existing deploy tokens for Git operations and package registry operations if
[external authorization](../../../administration/settings/external_authorization.md) is enabled.
+{{< /alert >}}
+
## Scope
A deploy token's scope determines the actions it can perform.
@@ -59,8 +65,12 @@ A deploy token's scope determines the actions it can perform.
## GitLab deploy token
-> - Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default.
-> - [Feature flag `ci_variable_for_group_gitlab_deploy_token`](https://gitlab.com/gitlab-org/gitlab/-/issues/363621) removed in GitLab 15.4.
+{{< history >}}
+
+- Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default.
+- [Feature flag `ci_variable_for_group_gitlab_deploy_token`](https://gitlab.com/gitlab-org/gitlab/-/issues/363621) removed in GitLab 15.4.
+
+{{< /history >}}
A GitLab deploy token is a special type of deploy token. If you create a deploy token named
`gitlab-deploy-token`, the deploy token is automatically exposed to project CI/CD jobs as variables:
@@ -74,12 +84,15 @@ For example, to use a GitLab token to sign in to your GitLab container registry:
echo "$CI_DEPLOY_PASSWORD" | docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin
```
-NOTE:
+{{< alert type="note" >}}
+
In GitLab 15.0 and earlier, the special handling for the `gitlab-deploy-token` deploy token does not
work for group deploy tokens. To make a group deploy token available for CI/CD jobs, set the
`CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD` CI/CD variables in **Settings > CI/CD > Variables** to the
name and token of the group deploy token.
+{{< /alert >}}
+
When `gitlab-deploy-token` is defined in a group, the `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD`
CI/CD variables are available only to immediate child projects of the group.
diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md
index 955c110a8e6f6b891211dbe9664b9cd7ff6dbeb8..43c9cf0811c1cac3292a9fb859fc4d596777abc9 100644
--- a/doc/user/project/description_templates.md
+++ b/doc/user/project/description_templates.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Description templates
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can define templates to use as descriptions
for your [issues](issues/_index.md) and [merge requests](merge_requests/_index.md).
@@ -37,7 +40,7 @@ To create an issue description template:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Repository**.
-1. Next to the default branch, select **{plus}**.
+1. Next to the default branch, select {{< icon name="plus" >}}.
1. Select **New file**.
1. Next to the default branch, in the **File name** text box, enter `.gitlab/issue_templates/mytemplate.md`,
where `mytemplate` is the name of your issue template.
@@ -57,7 +60,7 @@ To create a merge request description template for a project:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Repository**.
-1. Next to the default branch, select **{plus}**.
+1. Next to the default branch, select {{< icon name="plus" >}}.
1. Select **New file**.
1. Next to the default branch, in the **File name** text box, enter `.gitlab/merge_request_templates/mytemplate.md`,
where `mytemplate` is the name of your merge request template.
@@ -83,18 +86,28 @@ To discard any changes to the description you've made after selecting the templa
-NOTE:
+{{< alert type="note" >}}
+
You can create shortcut links to create an issue using a designated template.
For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. Read more about [creating issues using a URL with prefilled values](issues/create_issues.md#using-a-url-with-prefilled-values).
+{{< /alert >}}
+
### Supported variables in merge request templates
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89810) in GitLab 15.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89810) in GitLab 15.7.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is available only for
[the default template](#set-a-default-template-for-merge-requests-and-issues).
+{{< /alert >}}
+
When you save a merge request for the first time, GitLab replaces these variables in
your merge request template with their values:
@@ -109,9 +122,12 @@ your merge request template with their values:
### Set instance-level description templates
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can set a description template at the **instance level** for issues
and merge requests by using an [instance template repository](../../administration/settings/instance_template_repository.md).
@@ -122,9 +138,12 @@ that you can use when creating a new project in the instance.
### Set group-level description templates
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With **group-level** description templates, you can select a project within the group to store
your templates. Then, you can access these templates in other projects in the group.
@@ -209,11 +228,14 @@ We use description templates for issues and merge requests in the
[`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/-/tree/master/.gitlab) of the
GitLab project, which you can refer to for some examples.
-NOTE:
+{{< alert type="note" >}}
+
It's possible to use [quick actions](quick_actions.md) in description templates to quickly add
labels, assignees, and milestones. The quick actions are only executed if the user submitting
the issue or merge request has the permissions to perform the relevant actions.
+{{< /alert >}}
+
Here is an example of a bug report template:
```markdown
diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md
index 2566192b86b6621c9d65b06cadf29db64d27a269..7b6077c3a3005c1686bd9c50e30bb8d22a47d27f 100644
--- a/doc/user/project/file_lock.md
+++ b/doc/user/project/file_lock.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: File Locking
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Preventing wasted work caused by unresolvable merge conflicts requires
a different way of working. This means explicitly requesting write permissions,
@@ -45,9 +48,12 @@ or any other means, and are shown an error like:
## Default branch file and directory locks
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This process allows you to lock one file at a time through the GitLab UI and
requires access to the [GitLab Premium or Ultimate tier](https://about.gitlab.com/pricing/).
diff --git a/doc/user/project/import/_index.md b/doc/user/project/import/_index.md
index fb3c6add8a68a439492404817d497c5ba142c84a..8b56af5cbfd8de8fa192c3e1c3fe0b78f2b4c70a 100644
--- a/doc/user/project/import/_index.md
+++ b/doc/user/project/import/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import and migrate groups and projects
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To bring existing projects to GitLab, or copy GitLab groups and projects to a different location, you can:
@@ -26,7 +29,11 @@ You can also copy GitLab projects by using a GitLab file export, which is a supp
## Supported import sources
-> - All importers default to disabled for GitLab Self-Managed installations. This change was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118970) in GitLab 16.0.
+{{< history >}}
+
+- All importers default to disabled for GitLab Self-Managed installations. This change was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118970) in GitLab 16.0.
+
+{{< /history >}}
The import sources that are available to you by default depend on which GitLab you use:
@@ -84,23 +91,36 @@ difficult, but several tools exist including:
## User contribution and membership mapping
-DETAILS:
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443557) in GitLab 17.4 for direct transfer [with flags](../../../administration/feature_flags.md) named `importer_user_mapping` and `bulk_import_importer_user_mapping`. Disabled by default.
-> - Introduced in GitLab 17.6 for [Gitea](https://gitlab.com/gitlab-org/gitlab/-/issues/467084) [with flags](../../../administration/feature_flags.md) named `importer_user_mapping` and `gitea_user_mapping`, and for [GitHub](https://gitlab.com/gitlab-org/gitlab/-/issues/466355) with flags named `importer_user_mapping` and `github_user_mapping`. Disabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/466356) in GitLab 17.7 for Bitbucket Server [with flags](../../../administration/feature_flags.md) named `importer_user_mapping` and `bitbucket_server_user_mapping`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/472735) in GitLab 17.7 for direct transfer.
-> - Enabled on GitLab.com in GitLab 17.7 for [Bitbucket Server](https://gitlab.com/gitlab-org/gitlab/-/issues/509897), [Gitea](https://gitlab.com/gitlab-org/gitlab/-/issues/498390), and [GitHub](https://gitlab.com/gitlab-org/gitlab/-/issues/499993).
-> - Enabled on GitLab Self-Managed in GitLab 17.8 for [Bitbucket Server](https://gitlab.com/gitlab-org/gitlab/-/issues/509897), [Gitea](https://gitlab.com/gitlab-org/gitlab/-/issues/498390), and [GitHub](https://gitlab.com/gitlab-org/gitlab/-/issues/499993).
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443557) in GitLab 17.4 for direct transfer [with flags](../../../administration/feature_flags.md) named `importer_user_mapping` and `bulk_import_importer_user_mapping`. Disabled by default.
+- Introduced in GitLab 17.6 for [Gitea](https://gitlab.com/gitlab-org/gitlab/-/issues/467084) [with flags](../../../administration/feature_flags.md) named `importer_user_mapping` and `gitea_user_mapping`, and for [GitHub](https://gitlab.com/gitlab-org/gitlab/-/issues/466355) with flags named `importer_user_mapping` and `github_user_mapping`. Disabled by default.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/466356) in GitLab 17.7 for Bitbucket Server [with flags](../../../administration/feature_flags.md) named `importer_user_mapping` and `bitbucket_server_user_mapping`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/472735) in GitLab 17.7 for direct transfer.
+- Enabled on GitLab.com in GitLab 17.7 for [Bitbucket Server](https://gitlab.com/gitlab-org/gitlab/-/issues/509897), [Gitea](https://gitlab.com/gitlab-org/gitlab/-/issues/498390), and [GitHub](https://gitlab.com/gitlab-org/gitlab/-/issues/499993).
+- Enabled on GitLab Self-Managed in GitLab 17.8 for [Bitbucket Server](https://gitlab.com/gitlab-org/gitlab/-/issues/509897), [Gitea](https://gitlab.com/gitlab-org/gitlab/-/issues/498390), and [GitHub](https://gitlab.com/gitlab-org/gitlab/-/issues/499993).
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by feature flags.
For more information, see the history.
-NOTE:
+{{< /alert >}}
+
+{{< alert type="note" >}}
+
To leave feedback about this feature, add a comment to [issue 502565](https://gitlab.com/gitlab-org/gitlab/-/issues/502565).
+{{< /alert >}}
+
This method of user contribution and membership mapping is available by default for
[direct transfer](../../group/import/_index.md), [GitHub importer](github.md),
[Bitbucket Server importer](bitbucket_server.md), and [Gitea importer](gitea.md) on
@@ -350,7 +370,7 @@ To keep placeholder users in bulk:
This group must be at the top level.
1. Select **Manage > Members**.
1. Select the **Placeholders** tab.
-1. Above the list, select the vertical ellipsis (**{ellipsis_v}**) > **Keep all as placeholders**.
+1. Above the list, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) > **Keep all as placeholders**.
1. On the confirmation dialog, select **Confirm**.
#### Cancel reassignment request
@@ -463,7 +483,7 @@ You can view all project imports created by you. This list includes the followin
To view project import history:
1. Sign in to GitLab.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Import project**.
1. In the upper-right corner, select the **History** link.
1. If there are any errors for a particular import, select **Details** to see them.
diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md
index 96c1e2dabdc2cd2e2346fbb29fb325c0ee9ccdac..d73a9f315b893a69d2ff3826a33a2f1797a60754 100644
--- a/doc/user/project/import/bitbucket.md
+++ b/doc/user/project/import/bitbucket.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import your project from Bitbucket Cloud
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Parallel imports from Bitbucket Cloud [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412614) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `bitbucket_parallel_importer`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423530) in GitLab 16.6.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/423530) in GitLab 16.7. Feature flag `bitbucket_parallel_importer` removed.
-> - An **Imported** badge on some imported items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461210) in GitLab 17.2.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Parallel imports from Bitbucket Cloud [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412614) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `bitbucket_parallel_importer`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423530) in GitLab 16.6.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/423530) in GitLab 16.7. Feature flag `bitbucket_parallel_importer` removed.
+- An **Imported** badge on some imported items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461210) in GitLab 17.2.
+
+{{< /history >}}
Import your projects from Bitbucket Cloud to GitLab.
@@ -40,11 +47,14 @@ When importing:
private in GitLab as well.
- Imported issues, merge requests, and comments have an **Imported** badge in GitLab.
-NOTE:
+{{< alert type="note" >}}
+
The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.org/), not with Bitbucket
Server (aka Stash). If you are trying to import projects from Bitbucket Server, use
[the Bitbucket Server importer](bitbucket_server.md).
+{{< /alert >}}
+
When issues, pull requests, and comments are imported, the Bitbucket importer uses the Bitbucket nickname of
the author/assignee and tries to find the same Bitbucket identity in GitLab. If they don't match or
the user is not found in the GitLab database, the project creator (most of the times the current
@@ -68,7 +78,11 @@ namespace that started the import process.
## Prerequisites
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
- [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator
to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com.
@@ -91,10 +105,14 @@ For user contributions to be mapped, each user must complete the following befor
## Import your Bitbucket repositories
-> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
+{{< history >}}
+
+- Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
+
+{{< /history >}}
1. Sign in to GitLab.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Import project**.
1. Select **Bitbucket Cloud**.
1. Sign in to Bitbucket and grant GitLab access to your Bitbucket account.
diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md
index f31e04352daf9b0fbe4162767f00da29ac16a615..a8f1ff3a66f0ff2128d12703e7ca3944facf9d02 100644
--- a/doc/user/project/import/bitbucket_server.md
+++ b/doc/user/project/import/bitbucket_server.md
@@ -5,20 +5,31 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import your project from Bitbucket Server
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
-> - Ability to import reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416611) in GitLab 16.3.
-> - Support for pull request approval imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135256) in GitLab 16.7.
-> - An **Imported** badge on some imported items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461211) in GitLab 17.2.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
+- Ability to import reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416611) in GitLab 16.3.
+- Support for pull request approval imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135256) in GitLab 16.7.
+- An **Imported** badge on some imported items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461211) in GitLab 17.2.
+
+{{< /history >}}
Import your projects from Bitbucket Server to GitLab.
## Prerequisites
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
- [Bitbucket Server import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources)
must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Server import source is enabled
@@ -32,7 +43,7 @@ Import your projects from Bitbucket Server to GitLab.
To import your Bitbucket repositories:
1. Sign in to GitLab.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Import project**.
1. Select **Bitbucket Server**.
1. Sign in to Bitbucket and grant GitLab access to your Bitbucket account.
@@ -86,11 +97,15 @@ The following items are changed when they are imported:
## User contribution and membership mapping
-> - User mapping by email address or username [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36885) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. Disabled by default.
-> - Mapping user mentions to GitLab users [added](https://gitlab.com/gitlab-org/gitlab/-/issues/433008) in GitLab 16.8.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153041) to map users only by email address in GitLab 17.1.
-> - [Changed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) to [user contribution and membership mapping](../import/_index.md#user-contribution-and-membership-mapping) in GitLab 17.8.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176675) in GitLab 17.8.
+{{< history >}}
+
+- User mapping by email address or username [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36885) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. Disabled by default.
+- Mapping user mentions to GitLab users [added](https://gitlab.com/gitlab-org/gitlab/-/issues/433008) in GitLab 16.8.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153041) to map users only by email address in GitLab 17.1.
+- [Changed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) to [user contribution and membership mapping](../import/_index.md#user-contribution-and-membership-mapping) in GitLab 17.8.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176675) in GitLab 17.8.
+
+{{< /history >}}
The Bitbucket Server importer uses an [improved method](../import/_index.md#user-contribution-and-membership-mapping)
of mapping user contributions for GitLab.com and GitLab Self-Managed.
diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md
index 90cb92ca61b6e7c511fe477f617338303ace9cf9..b7db5d76528f4f3c028a709b0068c039587f93ec 100644
--- a/doc/user/project/import/clearcase.md
+++ b/doc/user/project/import/clearcase.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from ClearCase
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[ClearCase](https://www.ibm.com/products/devops-code-clearcase) is a set of
tools developed by IBM which also include a centralized version control system
diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md
index cc1951a1d94c95e3bdf0dd0c6c027254d272e5a5..c61ff3c8ac23120a3f3eb5a6c3000fb64e1eb766 100644
--- a/doc/user/project/import/cvs.md
+++ b/doc/user/project/import/cvs.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from CVS
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version
control system similar to [SVN](https://subversion.apache.org/).
diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md
index dc66e989179b0790913cebf324024ffd3fff3888..48fbf30537808527f3ae5080268e29e1a3964e48 100644
--- a/doc/user/project/import/fogbugz.md
+++ b/doc/user/project/import/fogbugz.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import your project from FogBugz to GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
+
+{{< /history >}}
Using the importer, you can import your FogBugz project to GitLab.com
or to GitLab Self-Managed.
@@ -20,7 +27,11 @@ users.
## Prerequisites
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
- [FogBugz import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources)
must be enabled. If not enabled, ask your GitLab administrator to enable it. The FogBugz import source is enabled
@@ -32,7 +43,7 @@ users.
To import your project from FogBugz:
1. Sign in to GitLab.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Import project**.
1. Select **FogBugz**.
1. Enter your FogBugz URL, email address, and password.
diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md
index fd0488a790a7b4d1d209bf2d54c7f161d90e76c9..d3e006c800158c822bfd295145385348361acebb 100644
--- a/doc/user/project/import/gitea.md
+++ b/doc/user/project/import/gitea.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import your project from Gitea to GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken.
-> - Ability to import projects with a `.` in their path [added](https://gitlab.com/gitlab-org/gitlab/-/issues/434175) in GitLab 16.11.
-> - An **Imported** badge on some imported items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461208) in GitLab 17.2.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken.
+- Ability to import projects with a `.` in their path [added](https://gitlab.com/gitlab-org/gitlab/-/issues/434175) in GitLab 16.11.
+- An **Imported** badge on some imported items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461208) in GitLab 17.2.
+
+{{< /history >}}
Import your projects from Gitea to GitLab.
@@ -38,7 +45,11 @@ When importing:
## Prerequisites
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
- Gitea version 1.0.0 or later.
- [Gitea import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources)
@@ -50,7 +61,7 @@ When importing:
The Gitea importer page is visible when you create a new project. To begin a Gitea import:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Gitea** to start the import authorization process.
### Authorize access to your repositories using a personal access token
@@ -90,8 +101,12 @@ You also can:
## User contribution and membership mapping
-> - [Changed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) to [user contribution and membership mapping](../import/_index.md#user-contribution-and-membership-mapping) in GitLab 17.8.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176675) in GitLab 17.8.
+{{< history >}}
+
+- [Changed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) to [user contribution and membership mapping](../import/_index.md#user-contribution-and-membership-mapping) in GitLab 17.8.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176675) in GitLab 17.8.
+
+{{< /history >}}
The Gitea importer uses an [improved method](../import/_index.md#user-contribution-and-membership-mapping)
of mapping user contributions for GitLab.com and GitLab Self-Managed.
diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md
index fc183ddb734d57bc2c5cad26fb522929ab1ccff6..b1c25e0d248b3c3fa1ab428af3f9965c7d25fe85 100644
--- a/doc/user/project/import/github.md
+++ b/doc/user/project/import/github.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import your project from GitHub to GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10, you no longer need to add any users to the parent group in GitLab to successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** branch protection rule.
-> - An **Imported** badge on some imported items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461208) in GitLab 17.2.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10, you no longer need to add any users to the parent group in GitLab to successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** branch protection rule.
+- An **Imported** badge on some imported items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461208) in GitLab 17.2.
+
+{{< /history >}}
You can import your GitHub projects from either GitHub.com or GitHub Enterprise. Importing projects does not
migrate or import any types of groups or organizations from GitHub to GitLab.
@@ -48,7 +55,11 @@ by default on GitLab.com.
### Permissions and roles
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
To use the GitHub importer, you must have:
@@ -61,7 +72,11 @@ on the GitLab instance you import to.
### Accounts for user contribution mapping
-> - [Preparation requirement removed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) in GitLab 17.8.
+{{< history >}}
+
+- [Preparation requirement removed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) in GitLab 17.8.
+
+{{< /history >}}
Before using [the old method of user contribution mapping](#old-method-of-user-contribution-mapping) for imports to GitLab Self-Managed and GitLab
Dedicated, you must meet certain requirements. Imports to GitLab.com use an [improved method](../import/_index.md#user-contribution-and-membership-mapping)
@@ -112,7 +127,7 @@ If you are importing to GitLab.com or to a GitLab Self-Managed that has GitHub O
This method has an advantage over using a [personal access token (PAT)](#use-a-github-personal-access-token)
because the backend exchanges the access token with the appropriate permissions.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Import project** and then **GitHub**.
1. Select **Authorize with GitHub**.
1. Proceed to [selecting which repositories to import](#select-which-repositories-to-import).
@@ -130,7 +145,7 @@ To import your GitHub repository using a GitHub personal access token:
1. Select the `repo` scope.
1. Optional. To [import collaborators](#select-additional-items-to-import), or if your project has [Git LFS files](../../../topics/git/lfs/_index.md), select the `read:org` scope.
1. Select **Generate token**.
-1. On the GitLab left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the GitLab left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Import project** and then **GitHub**.
1. Select **Authorize with GitHub**.
1. In the **Personal access token** field, paste the GitHub personal access token.
@@ -163,7 +178,11 @@ To import your GitHub repository using the GitLab REST API:
### Filter repositories list
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385113) in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385113) in GitLab 16.0.
+
+{{< /history >}}
After you authorize access to your GitHub repositories, GitLab redirects you to the importer page and
your GitHub repositories are listed.
@@ -178,11 +197,15 @@ When the **Organization** tab is selected, you can further narrow down your sear
### Select additional items to import
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5.
-> - Importing collaborators as an additional item was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398154) in GitLab 16.0.
-> - Feature flag `github_import_extended_events` was introduced in GitLab 16.8. Disabled by default. This flag improves the performance of imports but removes the **Import issue and pull request events** option.
-> - Feature flag `github_import_extended_events` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/435089) in GitLab 16.9.
-> - Improved import performance made [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435089) in GitLab 16.11. Feature flag `github_import_extended_events` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5.
+- Importing collaborators as an additional item was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398154) in GitLab 16.0.
+- Feature flag `github_import_extended_events` was introduced in GitLab 16.8. Disabled by default. This flag improves the performance of imports but removes the **Import issue and pull request events** option.
+- Feature flag `github_import_extended_events` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/435089) in GitLab 16.9.
+- Improved import performance made [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435089) in GitLab 16.11. Feature flag `github_import_extended_events` removed.
+
+{{< /history >}}
To make imports as fast as possible, the following items aren't imported from GitHub by default:
@@ -201,8 +224,12 @@ You can choose to import these items, but this could significantly increase impo
### Select which repositories to import
-> - Ability to cancel pending or active imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247325) in GitLab 15.7.
-> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
+{{< history >}}
+
+- Ability to cancel pending or active imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247325) in GitLab 15.7.
+- Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
+
+{{< /history >}}
By default, the proposed repository namespaces match the names as they exist in GitHub, but based
on your permissions, you can choose to edit these names before you proceed to import any of them.
@@ -227,7 +254,11 @@ Completed imports can be re-imported by selecting **Re-import** and specifying n
### Check status of imports
-> - Details of partially completed imports with a list of entities that failed to import [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386748) in GitLab 16.1.
+{{< history >}}
+
+- Details of partially completed imports with a list of entities that failed to import [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386748) in GitLab 16.1.
+
+{{< /history >}}
After imports are completed, they can be in one of three states:
@@ -239,15 +270,23 @@ Expand **Details** to see a list of [repository entities](#imported-data) that f
## Username mentions
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/477553) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/477553) in GitLab 17.5.
+
+{{< /history >}}
GitLab adds backticks to username mentions in issues, merge requests, and notes.
These backticks prevent linking to an incorrect user with the same username on the GitLab instance.
## User contribution and membership mapping
-> - [Changed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) to [user contribution and membership mapping](../import/_index.md#user-contribution-and-membership-mapping) in GitLab 17.8.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176675) in GitLab 17.8.
+{{< history >}}
+
+- [Changed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) to [user contribution and membership mapping](../import/_index.md#user-contribution-and-membership-mapping) in GitLab 17.8.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176675) in GitLab 17.8.
+
+{{< /history >}}
The GitHub importer uses an [improved method](../import/_index.md#user-contribution-and-membership-mapping)
of mapping user contributions for GitLab.com and GitLab Self-Managed.
@@ -272,8 +311,11 @@ If the requirements are not met, the importer can't map the particular user's co
## Mirror a repository and share pipeline status
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
Depending on your GitLab tier, [repository mirroring](../repository/mirror/_index.md) can be set up to keep
your imported repository in sync with its GitHub copy.
@@ -284,9 +326,12 @@ Additionally, you can configure GitLab to send pipeline status updates back to G
If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/_index.md), then both
of the above are automatically configured.
-NOTE:
+{{< alert type="note" >}}
+
Mirroring does not sync any new or updated pull requests from your GitHub project.
+{{< /alert >}}
+
## Improve the speed of imports on self-managed instances
Administrator access on the GitLab server is required for these steps.
@@ -397,7 +442,11 @@ manually.
### Collaborators (members)
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10.
+
+{{< /history >}}
These GitHub collaborator roles are mapped to these GitLab [member roles](../../permissions.md#roles):
@@ -481,10 +530,13 @@ git clone -c http.extraHeader="Authorization: basic <base64 encode YOUR-TOKEN>"
The following configuration is an example on how to configure Apache HTTP Server as a reverse proxy
-WARNING:
+{{< alert type="warning" >}}
+
For simplicity, the snippet does not have configuration to encrypt the connection between the client and the proxy. However, for security reasons you should include that
configuration. See [sample Apache TLS/SSL configuration](https://ssl-config.mozilla.org/#server=apache&version=2.4.41&config=intermediate&openssl=1.1.1k&guideline=5.6).
+{{< /alert >}}
+
```plaintext
# Required modules
LoadModule filter_module lib/httpd/modules/mod_filter.so
diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md
index 61cef074f5518dbe29674c59ef99f757a41832c4..e9e8ad5578b52817fe6b26fde2bd13d50df4e769 100644
--- a/doc/user/project/import/gitlab_com.md
+++ b/doc/user/project/import/gitlab_com.md
@@ -1,15 +1,18 @@
---
+redirect_to: ../../group/import/index.md
+remove_date: "2025-01-25"
stage: Foundations
group: Import and Integrate
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
-remove_date: '2025-01-25'
-redirect_to: '../../group/import/index.md'
title: Import a project from GitLab.com to GitLab Self-Managed (removed)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108502) in GitLab 15.8
and removed in 16.0.
diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md
index eecf3d8a49833fba4470e778db2691b8b21772d0..97029b610120e0fa98f49cb85659c0da24a9f769 100644
--- a/doc/user/project/import/jira.md
+++ b/doc/user/project/import/jira.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import your Jira project issues to GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Using GitLab Jira importer, you can import your Jira issues to GitLab.com or to
GitLab Self-Managed.
@@ -41,14 +44,17 @@ iterations of the GitLab Jira importer.
## Import Jira issues to GitLab
-NOTE:
+{{< alert type="note" >}}
+
Importing Jira issues is done as an asynchronous background job, which
may result in delays based on import queues load, system load, or other factors.
Importing large projects may take several minutes depending on the size of the import.
+{{< /alert >}}
+
To import Jira issues to a GitLab project:
-1. On the **{issues}** **Issues** page, select **Actions** (**{ellipsis_v}**) **> Import from Jira**.
+1. On the {{< icon name="issues" >}} **Issues** page, select **Actions** ({{< icon name="ellipsis_v" >}}) **> Import from Jira**.
diff --git a/doc/user/project/import/jira_migration_options.md b/doc/user/project/import/jira_migration_options.md
index 5fc111c93ec18c6d131c4caab6021fe4fe3a345a..26addd9f1c9438602aa2bd8911adf07be88b7683 100644
--- a/doc/user/project/import/jira_migration_options.md
+++ b/doc/user/project/import/jira_migration_options.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Jira migration options
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You have several options to migrate your Jira projects to GitLab. Before you decide on a migration strategy,
first decide if you even need to move your Jira issues to GitLab. In many cases, the Jira issue data is no longer
@@ -48,7 +51,7 @@ To import the Jira issue data from a CSV file into your GitLab project:
1. In the new group, [create a new project](../_index.md#create-a-blank-project) to hold the migrated Jira issues.
1. Import the Jira data into GitLab:
1. In your new GitLab project, on the left sidebar, select **Plan > Issues**.
- 1. Select **Actions** (**{ellipsis_v}**) **> Import from Jira**.
+ 1. Select **Actions** ({{< icon name="ellipsis_v" >}}) **> Import from Jira**.
1. Follow the on-screen instructions to complete the import process.
1. Verify the migration:
1. Review the imported issues to ensure the project migrated to GitLab successfully.
diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md
index 2f7b6e6857cfc7e4abfdc8135309b6c92882e564..acc7a21cf8e7254a0c5aa0eac639921c9e30a9ce 100644
--- a/doc/user/project/import/manifest.md
+++ b/doc/user/project/import/manifest.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import multiple repositories by uploading a manifest file
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9.
+
+{{< /history >}}
GitLab allows you to import all the required Git repositories
based on a manifest file like the one used by the
@@ -19,7 +26,11 @@ repositories like the Android Open Source Project (AOSP).
## Prerequisites
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
- [Manifest import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources)
must be enabled. If not enabled, ask your GitLab administrator to enable it. The Manifest import source is enabled
diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md
index 3112601d71a2529477da03c93a494eb0af53c009..93e1560b3f1f4a450752672ca013486cb0ce00dd 100644
--- a/doc/user/project/import/perforce.md
+++ b/doc/user/project/import/perforce.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrating from Perforce Helix
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Perforce Helix](https://www.perforce.com/) provides a set of tools which also
include a centralized, proprietary version control system similar to Git.
diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md
index d4adb315272037bac9ccdb29ec7f794757521228..16d0d4971a74d4f3efda95fa3e45aa62c1ece821 100644
--- a/doc/user/project/import/repo_by_url.md
+++ b/doc/user/project/import/repo_by_url.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Import project from repository by URL
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can import your existing repositories by providing the Git URL. You can't import GitLab issues and merge requests
this way. Other methods provide more complete import methods.
@@ -16,7 +19,11 @@ If the repository is too large, the import can timeout.
## Prerequisites
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
- [Repository by URL import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources)
must be enabled. If not enabled, ask your GitLab administrator to enable it. The Repository by URL import source is enabled
@@ -27,7 +34,7 @@ If the repository is too large, the import can timeout.
## Import project by URL
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Import project**.
1. Select **Repository by URL**.
1. Enter a **Git repository URL**.
diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md
index ec409a28473101c63d4fc6ebfc1e3eba5107a869..4f573ea77122f0c1eb280d07b8e1b70785f69ca4 100644
--- a/doc/user/project/import/tfvc.md
+++ b/doc/user/project/import/tfvc.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Migrate from TFVC to Git
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/products/devops/server/)
in 2019, is a set of tools developed by Microsoft which also includes
diff --git a/doc/user/project/import/troubleshooting_github_import.md b/doc/user/project/import/troubleshooting_github_import.md
index bce1ec2f82b71f2b1f61898e69ac75398419155c..625b794f449e36d88b2b7e2a78e30aedffd28be4 100644
--- a/doc/user/project/import/troubleshooting_github_import.md
+++ b/doc/user/project/import/troubleshooting_github_import.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting importing a project from GitHub to GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When importing a project from GitHub to GitLab, you might encounter the following issues.
diff --git a/doc/user/project/insights/_index.md b/doc/user/project/insights/_index.md
index cc5c6deb58a6d5c1e7f06b4afcb739d2e3223883..9f9663d476de0c61ab6066b908ad6fc1ebfe39e5 100644
--- a/doc/user/project/insights/_index.md
+++ b/doc/user/project/insights/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Insights
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Insights are interactive bar charts that display the number of items (for example, bugs created) per month.
@@ -57,7 +60,7 @@ To view annotations:
Insights display data from the last 90 days. You can zoom in to display data only from a subset of the 90-day range.
-To do this, select the pause icons (**{status-paused}**) and slide them along the horizontal axis:
+To do this, select the pause icons ({{< icon name="status-paused" >}}) and slide them along the horizontal axis:
- To change the start date, slide the left pause icon to the left or right.
- To change the end date, slide the right pause icon to the left or right.
@@ -70,8 +73,12 @@ To exclude a dimension, from the legend below the chart, select the name of the
### Drill down on charts
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372215/) in GitLab 16.7.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/436704) to extend support to all `issuables` charts in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372215/) in GitLab 16.7.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/436704) to extend support to all `issuables` charts in GitLab 16.9.
+
+{{< /history >}}
You can drill down into the data of all charts whose `query.data_source` is `issuables`.
@@ -253,7 +260,11 @@ monthlyBugsCreated:
#### `query.data_source`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 15.3.
+
+{{< /history >}}
Use `data_source` to define the data source that exposes the data.
@@ -377,13 +388,20 @@ The `period_field` is automatically set to:
- `merged_at` if `query.issuable_state` is `merged`
- `created_at` otherwise
-NOTE:
+{{< alert type="note" >}}
+
Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved,
you may see `created_at` in place of `merged_at`. `created_at` is used instead.
+{{< /alert >}}
+
#### `DORA` query parameters
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367248) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367248) in GitLab 15.3.
+
+{{< /history >}}
Use DORA-specific queries with the `dora` data source to create a DORA chart definition.
diff --git a/doc/user/project/integrations/_index.md b/doc/user/project/integrations/_index.md
index de15dae3fd4ccbc203fc147b6faefb604250a4a7..de4f612ed4d061a72442e599aa21fce9a4df12e1 100644
--- a/doc/user/project/integrations/_index.md
+++ b/doc/user/project/integrations/_index.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project integrations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This page contains user documentation for project integrations. For administrator documentation, see [Project integration administration](../../../administration/settings/project_integration_management.md).
+{{< /alert >}}
+
You can integrate with external applications to add functionality to GitLab.
You can view and manage integrations for the:
@@ -38,9 +44,12 @@ To manage the group default settings for a project integration:
1. Complete the fields.
1. Select **Save changes**.
-WARNING:
+{{< alert type="warning" >}}
+
This may affect all or most of the subgroups and projects belonging to the group. Review the details below.
+{{< /alert >}}
+
If this is the first time you are setting up group settings for an integration:
- The integration is enabled for all subgroups and projects belonging to the group that don't already have
@@ -119,53 +128,53 @@ only those integrations are available.
| Integration | Description | Integration hooks |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ----------------- |
-| [Apple App Store Connect](apple_app_store.md) | Use GitLab to build and release an app in the Apple App Store. | **{dotted-circle}** No |
-| [Asana](asana.md) | Add commit messages as comments to Asana tasks. | **{dotted-circle}** No |
-| Assembla | Manage projects with Assembla. | **{dotted-circle}** No |
-| [Atlassian Bamboo](bamboo.md) | Run CI/CD pipelines with Atlassian Bamboo. | **{check-circle}** Yes |
-| [Bugzilla](bugzilla.md) | Use Bugzilla as an issue tracker. | **{dotted-circle}** No |
-| [Beyond Identity](beyond_identity.md) | Verify that GPG keys are authorized by Beyond Identity Authenticator. | **{dotted-circle}** No |
-| Buildkite | Run CI/CD pipelines with Buildkite. | **{check-circle}** Yes |
-| Campfire | Connect Campfire to chat. | **{dotted-circle}** No |
-| [ClickUp](clickup.md) | Use ClickUp as an issue tracker. | **{dotted-circle}** No |
-| [Confluence Workspace](confluence.md) | Use Confluence Cloud Workspace as an internal wiki. | **{dotted-circle}** No |
-| [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | **{dotted-circle}** No |
-| [Datadog](../../../integration/datadog.md) | Trace your GitLab pipelines with Datadog. | **{check-circle}** Yes |
-| [Diffblue Cover](../../../integration/diffblue_cover.md) | Automatically write comprehensive, human-like Java unit tests. | **{check-circle}** No |
-| [Discord Notifications](discord_notifications.md) | Send notifications about project events to a Discord channel. | **{dotted-circle}** No |
-| Drone | Run CI/CD pipelines with Drone. | **{check-circle}** Yes |
-| [Emails on push](emails_on_push.md) | Send commits and diffs on push by email. | **{dotted-circle}** No |
-| [Engineering Workflow Management (EWM)](ewm.md) | Use EWM as an issue tracker. | **{dotted-circle}** No |
-| [External wiki](../wiki/_index.md#link-an-external-wiki) | Link an external wiki. | **{dotted-circle}** No |
-| [GitGuardian](git_guardian.md) | Reject commits based on GitGuardian policies. | **{dotted-circle}** No |
-| [GitHub](github.md) | Receive statuses for commits and pull requests. | **{dotted-circle}** No |
-| [GitLab for Slack app](gitlab_slack_application.md) | Use the native Slack app to receive notifications and run commands. | **{dotted-circle}** No |
-| [Google Artifact Management](google_artifact_management.md) | Manage your artifacts in Google Artifact Registry. | **{dotted-circle}** No |
-| [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a space in Google Chat. | **{dotted-circle}** No |
-| [Google Cloud IAM](../../../integration/google_cloud_iam.md) | Manage permissions for Google Cloud resources with Identity and Access Management (IAM). | **{dotted-circle}** No |
-| [Google Play](google_play.md) | Use GitLab to build and release an app in Google Play. | **{dotted-circle}** No |
-| [Harbor](harbor.md) | Use Harbor as the container registry for GitLab. | **{dotted-circle}** No |
-| [irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No |
-| [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes |
-| JetBrains TeamCity | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes |
-| [JetBrains YouTrack](youtrack.md) | Use JetBrains YouTrack as your project's issue tracker. | **{dotted-circle}** No |
-| [Jira](../../../integration/jira/_index.md) | Use Jira as an issue tracker. | **{dotted-circle}** No |
-| [Matrix notifications](matrix.md) | Send notifications about project events to Matrix. | **{dotted-circle}** No |
-| [Mattermost notifications](mattermost.md) | Send notifications about project events to Mattermost channels. | **{dotted-circle}** No |
-| [Mattermost slash commands](mattermost_slash_commands.md) | Run slash commands from a Mattermost chat environment. | **{dotted-circle}** No |
-| [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications in Microsoft Teams. | **{dotted-circle}** No |
-| Packagist | Update your PHP dependencies in Packagist. | **{check-circle}** Yes |
-| [Phorge](phorge.md) | Use Phorge as an issue tracker. | **{dotted-circle}** No |
-| [Pipeline status emails](pipeline_status_emails.md) | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No |
-| [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No |
-| [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No |
-| Pushover | Get real-time notifications on your device. | **{dotted-circle}** No |
-| [Redmine](redmine.md) | Use Redmine as an issue tracker. | **{dotted-circle}** No |
-| [Slack slash commands](slack_slash_commands.md) | Run slash commands from a Slack chat environment. | **{dotted-circle}** No |
-| [Squash TM](squash_tm.md) | Update Squash TM requirements when GitLab issues are modified. | **{check-circle}** Yes |
-| [Telegram](telegram.md) | Send notifications about project events to Telegram. | **{dotted-circle}** No |
-| [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No |
-| [Webex Teams](webex_teams.md) | Receive event notifications in Webex Teams. | **{dotted-circle}** No |
+| [Apple App Store Connect](apple_app_store.md) | Use GitLab to build and release an app in the Apple App Store. | {{< icon name="dotted-circle" >}} No |
+| [Asana](asana.md) | Add commit messages as comments to Asana tasks. | {{< icon name="dotted-circle" >}} No |
+| Assembla | Manage projects with Assembla. | {{< icon name="dotted-circle" >}} No |
+| [Atlassian Bamboo](bamboo.md) | Run CI/CD pipelines with Atlassian Bamboo. | {{< icon name="check-circle" >}} Yes |
+| [Bugzilla](bugzilla.md) | Use Bugzilla as an issue tracker. | {{< icon name="dotted-circle" >}} No |
+| [Beyond Identity](beyond_identity.md) | Verify that GPG keys are authorized by Beyond Identity Authenticator. | {{< icon name="dotted-circle" >}} No |
+| Buildkite | Run CI/CD pipelines with Buildkite. | {{< icon name="check-circle" >}} Yes |
+| Campfire | Connect Campfire to chat. | {{< icon name="dotted-circle" >}} No |
+| [ClickUp](clickup.md) | Use ClickUp as an issue tracker. | {{< icon name="dotted-circle" >}} No |
+| [Confluence Workspace](confluence.md) | Use Confluence Cloud Workspace as an internal wiki. | {{< icon name="dotted-circle" >}} No |
+| [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | {{< icon name="dotted-circle" >}} No |
+| [Datadog](../../../integration/datadog.md) | Trace your GitLab pipelines with Datadog. | {{< icon name="check-circle" >}} Yes |
+| [Diffblue Cover](../../../integration/diffblue_cover.md) | Automatically write comprehensive, human-like Java unit tests. | {{< icon name="check-circle" >}} No |
+| [Discord Notifications](discord_notifications.md) | Send notifications about project events to a Discord channel. | {{< icon name="dotted-circle" >}} No |
+| Drone | Run CI/CD pipelines with Drone. | {{< icon name="check-circle" >}} Yes |
+| [Emails on push](emails_on_push.md) | Send commits and diffs on push by email. | {{< icon name="dotted-circle" >}} No |
+| [Engineering Workflow Management (EWM)](ewm.md) | Use EWM as an issue tracker. | {{< icon name="dotted-circle" >}} No |
+| [External wiki](../wiki/_index.md#link-an-external-wiki) | Link an external wiki. | {{< icon name="dotted-circle" >}} No |
+| [GitGuardian](git_guardian.md) | Reject commits based on GitGuardian policies. | {{< icon name="dotted-circle" >}} No |
+| [GitHub](github.md) | Receive statuses for commits and pull requests. | {{< icon name="dotted-circle" >}} No |
+| [GitLab for Slack app](gitlab_slack_application.md) | Use the native Slack app to receive notifications and run commands. | {{< icon name="dotted-circle" >}} No |
+| [Google Artifact Management](google_artifact_management.md) | Manage your artifacts in Google Artifact Registry. | {{< icon name="dotted-circle" >}} No |
+| [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a space in Google Chat. | {{< icon name="dotted-circle" >}} No |
+| [Google Cloud IAM](../../../integration/google_cloud_iam.md) | Manage permissions for Google Cloud resources with Identity and Access Management (IAM). | {{< icon name="dotted-circle" >}} No |
+| [Google Play](google_play.md) | Use GitLab to build and release an app in Google Play. | {{< icon name="dotted-circle" >}} No |
+| [Harbor](harbor.md) | Use Harbor as the container registry for GitLab. | {{< icon name="dotted-circle" >}} No |
+| [irker (IRC gateway)](irker.md) | Send IRC messages. | {{< icon name="dotted-circle" >}} No |
+| [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | {{< icon name="check-circle" >}} Yes |
+| JetBrains TeamCity | Run CI/CD pipelines with TeamCity. | {{< icon name="check-circle" >}} Yes |
+| [JetBrains YouTrack](youtrack.md) | Use JetBrains YouTrack as your project's issue tracker. | {{< icon name="dotted-circle" >}} No |
+| [Jira](../../../integration/jira/_index.md) | Use Jira as an issue tracker. | {{< icon name="dotted-circle" >}} No |
+| [Matrix notifications](matrix.md) | Send notifications about project events to Matrix. | {{< icon name="dotted-circle" >}} No |
+| [Mattermost notifications](mattermost.md) | Send notifications about project events to Mattermost channels. | {{< icon name="dotted-circle" >}} No |
+| [Mattermost slash commands](mattermost_slash_commands.md) | Run slash commands from a Mattermost chat environment. | {{< icon name="dotted-circle" >}} No |
+| [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications in Microsoft Teams. | {{< icon name="dotted-circle" >}} No |
+| Packagist | Update your PHP dependencies in Packagist. | {{< icon name="check-circle" >}} Yes |
+| [Phorge](phorge.md) | Use Phorge as an issue tracker. | {{< icon name="dotted-circle" >}} No |
+| [Pipeline status emails](pipeline_status_emails.md) | Send the pipeline status to a list of recipients by email. | {{< icon name="dotted-circle" >}} No |
+| [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | {{< icon name="dotted-circle" >}} No |
+| [Pumble](pumble.md) | Send event notifications to a Pumble channel. | {{< icon name="dotted-circle" >}} No |
+| Pushover | Get real-time notifications on your device. | {{< icon name="dotted-circle" >}} No |
+| [Redmine](redmine.md) | Use Redmine as an issue tracker. | {{< icon name="dotted-circle" >}} No |
+| [Slack slash commands](slack_slash_commands.md) | Run slash commands from a Slack chat environment. | {{< icon name="dotted-circle" >}} No |
+| [Squash TM](squash_tm.md) | Update Squash TM requirements when GitLab issues are modified. | {{< icon name="check-circle" >}} Yes |
+| [Telegram](telegram.md) | Send notifications about project events to Telegram. | {{< icon name="dotted-circle" >}} No |
+| [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | {{< icon name="dotted-circle" >}} No |
+| [Webex Teams](webex_teams.md) | Receive event notifications in Webex Teams. | {{< icon name="dotted-circle" >}} No |
## Project webhooks
diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md
index a0e048cda18e6774cbb13332720823778fd38ffe..d388ff2c02cbbc18216fb012b4cc432eef2b2803 100644
--- a/doc/user/project/integrations/apple_app_store.md
+++ b/doc/user/project/integrations/apple_app_store.md
@@ -5,12 +5,19 @@ info: This is a GitLab Incubation Engineering program. No technical writer assig
title: Apple App Store Connect
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385335) in GitLab 15.10. Feature flag `apple_app_store_integration` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385335) in GitLab 15.10. Feature flag `apple_app_store_integration` removed.
+
+{{< /history >}}
This feature is part of [Mobile DevOps](../../../ci/mobile_devops/_index.md) developed by [GitLab Incubation Engineering](https://handbook.gitlab.com/handbook/engineering/development/incubation/).
The feature is still in development, but you can:
diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md
index 0c82b8a262ab6870b9e4d3e6b8f6858933f81d70..95b0833bea0b23b883534caf4a491cc24c16f810 100644
--- a/doc/user/project/integrations/asana.md
+++ b/doc/user/project/integrations/asana.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Asana
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Asana integration adds commit messages as comments to Asana tasks.
Once enabled, commit messages are checked for Asana task URLs (for example,
diff --git a/doc/user/project/integrations/aws_codepipeline.md b/doc/user/project/integrations/aws_codepipeline.md
index 0b8740e242870829703b2774a3253f920aafbd45..1d6beb66460815176976ce6fce79e7105c484f50 100644
--- a/doc/user/project/integrations/aws_codepipeline.md
+++ b/doc/user/project/integrations/aws_codepipeline.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: AWS CodePipeline
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-com/alliances/aws/wip/aws-cs-collab/aws-gitlab-collaboration/-/issues/25) in GitLab 16.5.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-com/alliances/aws/wip/aws-cs-collab/aws-gitlab-collaboration/-/issues/25) in GitLab 16.5.
+
+{{< /history >}}
You can use your GitLab project to build, test, and deploy code changes using [AWS CodePipeline](https://aws.amazon.com/codepipeline/). To do so, you use:
diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md
index ba6b8b0593e4dd5497e79e5bab0399174b7ff973..97cca4a3a826858f6ff0d16dea4b4522a5bd1ae5 100644
--- a/doc/user/project/integrations/bamboo.md
+++ b/doc/user/project/integrations/bamboo.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Atlassian Bamboo
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can automatically trigger builds in Atlassian Bamboo when you push changes
to your project in GitLab.
diff --git a/doc/user/project/integrations/beyond_identity.md b/doc/user/project/integrations/beyond_identity.md
index 233365edcedc793d1f72521819c6dd280fdbe580..3a042bc530b98c250451fbe1facf56e3f66753d5 100644
--- a/doc/user/project/integrations/beyond_identity.md
+++ b/doc/user/project/integrations/beyond_identity.md
@@ -2,15 +2,22 @@
stage: Create
group: Source Code
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
-description: "Integrate GitLab with Beyond Identity to verify GPG keys added to user accounts."
+description: Integrate GitLab with Beyond Identity to verify GPG keys added to user accounts.
title: Beyond Identity
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431433) in GitLab 16.9.
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431433) in GitLab 16.9.
+
+{{< /history >}}
Configure GitLab to verify GPG keys issued by [Beyond Identity](https://www.beyondidentity.com/)
added to a user profile.
@@ -68,9 +75,13 @@ To skip the push check for [service accounts](../../profile/service_accounts.md)
## Exclude groups or projects from the Beyond Identity check
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/454372) in GitLab 17.0 [with a flag](../../../administration/feature_flags.md) named `beyond_identity_exclusions`. Enabled by default.
-> - Option to exclude groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/454372) in GitLab 17.1.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/457893) in GitLab 17.7. Feature flag `beyond_identity_exclusions` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/454372) in GitLab 17.0 [with a flag](../../../administration/feature_flags.md) named `beyond_identity_exclusions`. Enabled by default.
+- Option to exclude groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/454372) in GitLab 17.1.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/457893) in GitLab 17.7. Feature flag `beyond_identity_exclusions` removed.
+
+{{< /history >}}
Prerequisites:
diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md
index f24e7e0b77f8c1c44b1648f629f1c9ee68f3fd70..7037ef58a9b8163cb0d318fa7c8b71ec4341909c 100644
--- a/doc/user/project/integrations/bugzilla.md
+++ b/doc/user/project/integrations/bugzilla.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Bugzilla
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Bugzilla](https://www.bugzilla.org/) is a web-based general-purpose bug tracking system and testing
tool.
diff --git a/doc/user/project/integrations/clickup.md b/doc/user/project/integrations/clickup.md
index b21b35e328fb143cf8b6071014cb73990254a979..c50663cc9efb93c68d86d8c350d1d265a261f295 100644
--- a/doc/user/project/integrations/clickup.md
+++ b/doc/user/project/integrations/clickup.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: ClickUp
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120732) in GitLab 16.1.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120732) in GitLab 16.1.
+
+{{< /history >}}
You can use [ClickUp](https://clickup.com/) as an external issue tracker.
To enable the ClickUp integration in a project:
diff --git a/doc/user/project/integrations/confluence.md b/doc/user/project/integrations/confluence.md
index 55177204eb177fb4a16a53404b9236180ec223bb..29515644caec4faeeb31522b49380bfc68e39a63 100644
--- a/doc/user/project/integrations/confluence.md
+++ b/doc/user/project/integrations/confluence.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Confluence Workspace
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use a Confluence Cloud Workspace as your project wiki.
@@ -51,8 +54,11 @@ If the integration has been turned on for the group, you can still turn it off f
### For all projects on the instance
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Prerequisites:
diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md
index 910c0f074ff9a60a6d30ede7a437a43ff25260de..212b3b504daa26fac027813e699eca6a69e97dd2 100644
--- a/doc/user/project/integrations/custom_issue_tracker.md
+++ b/doc/user/project/integrations/custom_issue_tracker.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Custom issue tracker
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can integrate an [external issue tracker](../../../integration/external-issue-tracker.md)
with GitLab. If your preferred issue tracker is not listed in the
diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md
index 119a2be403896bcc9bc61a7034ec2ec102b0b83e..c51e60487789164d1c29e9303e94ec5f1cec33be 100644
--- a/doc/user/project/integrations/discord_notifications.md
+++ b/doc/user/project/integrations/discord_notifications.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Discord Notifications
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Discord Notifications integration sends event notifications from GitLab to the channel for which the webhook was created.
@@ -27,7 +30,11 @@ and configure it in GitLab.
## Configure created webhook in GitLab
-> - Event webhook overrides [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125621) in GitLab 16.3.
+{{< history >}}
+
+- Event webhook overrides [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125621) in GitLab 16.3.
+
+{{< /history >}}
With the webhook URL created in the Discord channel, you can set up the Discord Notifications integration in GitLab.
diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md
index 3ff66d804cb14235f52c8ff32e5b4ba0d6d91729..816678d957c67b61881921c0a1918a7f5a9bf098 100644
--- a/doc/user/project/integrations/emails_on_push.md
+++ b/doc/user/project/integrations/emails_on_push.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Emails on push
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use emails on push to receive email notifications for changes pushed to your GitLab project.
You can select the push events that trigger these notifications.
diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md
index 57092b5c457c411616222992db7fab5b79d566ff..e2fcf69fa65a2d65854b5a0a7f26c1485a104a06 100644
--- a/doc/user/project/integrations/ewm.md
+++ b/doc/user/project/integrations/ewm.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Engineering Workflow Management (EWM)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The EWM integration allows you to go from GitLab to EWM work items mentioned in merge request
descriptions and commit messages.
diff --git a/doc/user/project/integrations/git_guardian.md b/doc/user/project/integrations/git_guardian.md
index 9a9dd1358e6d08e4a66c3d578cfef25bdbd3f63a..848f70270e1da272d392f925286e9e88df975546 100644
--- a/doc/user/project/integrations/git_guardian.md
+++ b/doc/user/project/integrations/git_guardian.md
@@ -2,17 +2,24 @@
stage: Create
group: Source Code
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
-description: "Integrate GitLab with GitGuardian to get alerts for policy violations and security issues before they can be exploited."
+description: Integrate GitLab with GitGuardian to get alerts for policy violations and security issues before they can be exploited.
title: GitGuardian
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435706) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `git_guardian_integration`. Enabled by default. Disabled on GitLab.com.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/438695#note_2226917025) in GitLab 17.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176391) in GitLab 17.8. Feature flag `git_guardian_integration` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435706) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `git_guardian_integration`. Enabled by default. Disabled on GitLab.com.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/438695#note_2226917025) in GitLab 17.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176391) in GitLab 17.8. Feature flag `git_guardian_integration` removed.
+
+{{< /history >}}
[GitGuardian](https://www.gitguardian.com/) is a cybersecurity service that detects sensitive data such as API keys
and passwords in source code repositories.
@@ -72,7 +79,11 @@ GitLab is now ready to reject commits based on GitGuardian policies.
## Skip secret detection
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152064) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152064) in GitLab 17.0.
+
+{{< /history >}}
You can skip GitGuardian secret detection, if needed. The options to skip
secret detection for all commits in a push are identical to the options for
diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md
index d15a5e28c0dcd462ac61f2758c40d8fabbfa4dc3..c572bd38f3608ca1e42abbea55a4a5aa6babb90f 100644
--- a/doc/user/project/integrations/github.md
+++ b/doc/user/project/integrations/github.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitHub
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can update GitHub with pipeline status updates from GitLab.
The GitHub integration can help you if you use GitLab for CI/CD.
diff --git a/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md b/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md
index b1c5cd4519d7befb36fc57e39e9be2a2fa5f0a8a..53eae72ce7d40a3328206eb531a52f872cfe519b 100644
--- a/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md
+++ b/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Troubleshooting GitLab for Slack app
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with the GitLab for Slack app, you might encounter the following issues.
diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md
index 6cf590fd27bae485850747805881b54ef24ab3b3..f92a03c32adc4a6e2bc0573627ba3e9e1ac75b1d 100644
--- a/doc/user/project/integrations/gitlab_slack_application.md
+++ b/doc/user/project/integrations/gitlab_slack_application.md
@@ -5,15 +5,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab for Slack app
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for GitLab Self-Managed in GitLab 16.2.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for GitLab Self-Managed in GitLab 16.2.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
This page contains user documentation for the GitLab for Slack app. For administrator documentation, see [GitLab for Slack app administration](../../../administration/settings/slack_app.md).
+{{< /alert >}}
+
The GitLab for Slack app is a native Slack app that provides [slash commands](#slash-commands) and [notifications](#slack-notifications)
in your Slack workspace. GitLab links your Slack user with your GitLab user so that any command
you run in Slack is run by your linked GitLab user.
@@ -31,9 +41,13 @@ Although functionality has not changed, you should [reinstall the app](#reinstal
### From the project or group settings
-> - Installation at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391526) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `gitlab_for_slack_app_instance_and_group_level`. Disabled by default.
-> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147820) in GitLab 16.11.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175803) in GitLab 17.8. Feature flag `gitlab_for_slack_app_instance_and_group_level` removed.
+{{< history >}}
+
+- Installation at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391526) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `gitlab_for_slack_app_instance_and_group_level`. Disabled by default.
+- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147820) in GitLab 16.11.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175803) in GitLab 17.8. Feature flag `gitlab_for_slack_app_instance_and_group_level` removed.
+
+{{< /history >}}
To install the GitLab for Slack app from the project or group settings:
@@ -45,9 +59,12 @@ To install the GitLab for Slack app from the project or group settings:
### From the Slack App Directory
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
On GitLab.com, you can also install the GitLab for Slack app from the
[Slack App Directory](https://slack-platform.slack.com/apps/A676ADMV5-gitlab).
@@ -129,7 +146,11 @@ To create a project alias for slash commands in the GitLab for Slack app:
## Slack notifications
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381012) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381012) in GitLab 15.9.
+
+{{< /history >}}
You can receive notifications to Slack channels for certain GitLab [events](#notification-events).
@@ -145,8 +166,11 @@ To configure Slack notifications:
- For each checkbox you select, enter the names of the Slack channels you want to receive notifications.
You can enter up to 10 channel names separated by commas (for example, `#channel-one, #channel-two`).
- NOTE:
- If the Slack channel is private, you must [add the GitLab for Slack app to the channel](#receive-notifications-to-a-private-channel).
+ {{< alert type="note" >}}
+
+ If the Slack channel is private, you must [add the GitLab for Slack app to the channel](#receive-notifications-to-a-private-channel).
+
+ {{< /alert >}}
1. Optional. In the **Notification settings** section:
- Select the **Notify only broken pipelines** checkbox
@@ -193,9 +217,13 @@ The following GitLab events can trigger notifications in Slack:
### Trigger notifications for group mentions
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391526) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `gitlab_for_slack_app_instance_and_group_level`. Disabled by default.
-> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147820) in GitLab 16.11.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175803) in GitLab 17.8. Feature flag `gitlab_for_slack_app_instance_and_group_level` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391526) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `gitlab_for_slack_app_instance_and_group_level`. Disabled by default.
+- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147820) in GitLab 16.11.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175803) in GitLab 17.8. Feature flag `gitlab_for_slack_app_instance_and_group_level` removed.
+
+{{< /history >}}
To trigger a [notification event](#notification-events) for a group mention, use `@<group_name>` in:
diff --git a/doc/user/project/integrations/google_artifact_management.md b/doc/user/project/integrations/google_artifact_management.md
index 8d0960d032e24c706c73cc75d72130c53c5cac35..ab61d667fe5d784f6616c204ee9ff5bf9672ba1f 100644
--- a/doc/user/project/integrations/google_artifact_management.md
+++ b/doc/user/project/integrations/google_artifact_management.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Google Artifact Management
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141127) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `google_cloud_support_feature_flag`. This feature is in [beta](../../../policy/development_stages_support.md).
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141127) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `google_cloud_support_feature_flag`. This feature is in [beta](../../../policy/development_stages_support.md).
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150472) in GitLab 17.1. Feature flag `google_cloud_support_feature_flag` removed.
+
+{{< /history >}}
You can use the Google Artifact Management integration to
configure and connect a [Google Artifact Registry](https://cloud.google.com/artifact-registry) repository to your GitLab project.
diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md
index dc01548c219574f6a1a3baf56e8addae58d2062d..a975b7b3c0f5342806e4a44ed15dafe7cee2a4dd 100644
--- a/doc/user/project/integrations/google_play.md
+++ b/doc/user/project/integrations/google_play.md
@@ -5,12 +5,19 @@ info: This is a GitLab Incubation Engineering program. No technical writer assig
title: Google Play
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111621) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `google_play_integration`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389611) in GitLab 15.11. Feature flag `google_play_integration` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111621) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `google_play_integration`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389611) in GitLab 15.11. Feature flag `google_play_integration` removed.
+
+{{< /history >}}
This feature is part of [Mobile DevOps](../../../ci/mobile_devops/_index.md) developed by [GitLab Incubation Engineering](https://handbook.gitlab.com/handbook/engineering/development/incubation/).
The feature is still in development, but you can:
diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md
index 033e5ee74608bfcd53ac8dd13c8c837a4c092096..638851b550587faaaa5429c601bab75213026d04 100644
--- a/doc/user/project/integrations/hangouts_chat.md
+++ b/doc/user/project/integrations/hangouts_chat.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Google Chat
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can configure your project in GitLab to send notifications to a
space of your choice in [Google Chat](https://chat.google.com/).
@@ -23,13 +26,13 @@ For more information, see [issue 438452](https://gitlab.com/gitlab-org/gitlab/-/
To configure the integration in Google Chat:
1. Go to the space where you want to receive notifications from GitLab.
-1. In the upper left, next to the space name, select the down arrow (**{chevron-down}**) > **Apps & integrations**.
+1. In the upper left, next to the space name, select the down arrow ({{< icon name="chevron-down" >}}) > **Apps & integrations**.
1. In the **Webhooks** section, select **Add webhooks**.
1. On the **Incoming webhooks** dialog:
- In **Name**, enter a name for your webhook (for example, `GitLab integration`).
- Optional. In **Avatar URL**, enter an avatar for your bot.
1. Select **Save**.
-1. Next to the webhook URL, select the vertical ellipsis (**{ellipsis_v}**) > **Copy link**.
+1. Next to the webhook URL, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) > **Copy link**.
For more information about webhooks, see the
[Google Chat documentation](https://developers.google.com/workspace/chat/quickstart/webhooks).
diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md
index 2d34441f282542b22d34532a5df73f3f55a379d2..edc69850451ba3d65af1a9174bcbb157a5ac0aea 100644
--- a/doc/user/project/integrations/harbor.md
+++ b/doc/user/project/integrations/harbor.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Harbor
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use Harbor as the container registry for your GitLab project.
diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md
index 0cca64c331c753ebea0b0dda4162d8ac09b914aa..681bcc107db859255c4ba0725ae2a300b10a9912 100644
--- a/doc/user/project/integrations/irker.md
+++ b/doc/user/project/integrations/irker.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: irker (IRC gateway)
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides a way to push update messages to an irker server. After you configure
the integration, each push to a project triggers the integration to send data directly
@@ -34,12 +37,15 @@ You need to set up an irker daemon. To do so:
If the irker server runs on the same machine, you are done. If not, you
need to follow the first steps of the next section.
-WARNING:
+{{< alert type="warning" >}}
+
irker does **not** have built-in authentication, which makes it vulnerable to spamming IRC channels if
it is hosted outside of a firewall. To prevent abuse, make sure you run the daemon on a secured
network. For more details, read
[Security analysis of irker](http://www.catb.org/~esr/irker/security.html).
+{{< /alert >}}
+
## Complete these steps in GitLab
1. On the left sidebar, select **Search or go to** and find your project.
diff --git a/doc/user/project/integrations/matrix.md b/doc/user/project/integrations/matrix.md
index e4dbbc384583b46cf8601fa78d81b59c3bd3135b..15350afdbab38281fdfdd954f88be889a64dc094 100644
--- a/doc/user/project/integrations/matrix.md
+++ b/doc/user/project/integrations/matrix.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Matrix
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 17.3.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 17.3.
+
+{{< /history >}}
You can configure GitLab to send notifications to a Matrix room.
diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md
index e5afab9810bea02b5a118c2be0524d2bba35ace1..cc41ea5e483b61a60424ec17f90b7f665f55b9ad 100644
--- a/doc/user/project/integrations/mattermost.md
+++ b/doc/user/project/integrations/mattermost.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Mattermost notifications
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use the Mattermost notifications integration to send notifications for GitLab events
(for example, `issue created`) to Mattermost. You must configure both [Mattermost](#configure-mattermost-to-receive-gitlab-notifications)
@@ -39,7 +42,11 @@ Display name override is not enabled by default, you need to ask your administra
## Configure GitLab to send notifications to Mattermost
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Mattermost channels to 10 per event.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Mattermost channels to 10 per event.
+
+{{< /history >}}
After the Mattermost instance has an incoming webhook set up, you can set up GitLab
to send the notifications:
diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md
index 0c25d71b632d2b16e969820ffb5ece3facc295bc..483bc32775a5d39a316b527db494b2a0fee95683 100644
--- a/doc/user/project/integrations/mattermost_slash_commands.md
+++ b/doc/user/project/integrations/mattermost_slash_commands.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Mattermost slash commands
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations,
like creating an issue, from a [Mattermost](https://mattermost.com/) chat environment.
@@ -55,7 +58,7 @@ To manually configure slash commands in Mattermost, you must:
To enable custom slash commands from the Mattermost administrator console:
1. Sign in to Mattermost as a user with administrator privileges.
-1. Next to your username, select the **{ellipsis_v}** **Settings** icon, and
+1. Next to your username, select the {{< icon name="ellipsis_v" >}} **Settings** icon, and
select **System Console**.
1. Select **Integration Management**, and set these values to `TRUE`:
- **Enable Custom Slash Commands**
@@ -82,7 +85,7 @@ To create a slash command in Mattermost:
1. [In the Mattermost browser tab](#enable-custom-slash-commands-in-mattermost),
go to your team page.
-1. Select the **{ellipsis_v}** **Settings** icon, and select **Integrations**.
+1. Select the {{< icon name="ellipsis_v" >}} **Settings** icon, and select **Integrations**.
1. On the left sidebar, select **Slash commands**.
1. Select **Add Slash Command**.
1. Provide a **Display Name** and **Description** for your new command.
diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md
index fb20088c180b0a2bb41bc369f0e0f2ada0fa68b1..0bd10e489014d94d820af053bad48bc0b199ef75 100644
--- a/doc/user/project/integrations/microsoft_teams.md
+++ b/doc/user/project/integrations/microsoft_teams.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Microsoft Teams notifications
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can integrate Microsoft Teams notifications with GitLab and display notifications about GitLab projects
in Microsoft Teams. To integrate the services, you must:
@@ -19,11 +22,14 @@ in Microsoft Teams. To integrate the services, you must:
## Configure Microsoft Teams
-WARNING:
+{{< alert type="warning" >}}
+
New Microsoft Teams integrations using Microsoft Connectors can no longer be created and
existing integrations must be transitioned to workflow apps by December 2025.
Microsoft [announced](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/) the retirement of Microsoft Teams integrations using Microsoft Connectors.
+{{< /alert >}}
+
To configure Microsoft Teams to listen for notifications from GitLab:
1. In Microsoft Teams, find and select the workflow template "Post to a channel when a webhook request is received".
diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md
index 7a3d7ebfde03fa8d2231e71c7767ce3e6256bea6..1e406d79e3aa047f69544be31c4dfb830259457c 100644
--- a/doc/user/project/integrations/mock_ci.md
+++ b/doc/user/project/integrations/mock_ci.md
@@ -5,13 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Mock CI
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This integration is only available in a development environment.
+{{< /alert >}}
+
To set up the mock CI service server, respond to the following endpoints:
- `commit_status`: `#{project.namespace.path}/#{project.path}/status/#{sha}.json`
diff --git a/doc/user/project/integrations/phorge.md b/doc/user/project/integrations/phorge.md
index ab31e1dde60e614b4c43a75dfa22cb6f5772cc4f..0d36f062a37d249b0eae9947d46ea6ec43212ac6 100644
--- a/doc/user/project/integrations/phorge.md
+++ b/doc/user/project/integrations/phorge.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Phorge
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145863) in GitLab 16.11.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145863) in GitLab 16.11.
+
+{{< /history >}}
You can use [Phorge](https://we.phorge.it/) as an external issue tracker in GitLab.
diff --git a/doc/user/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md
index d0f3b4dbde08730eea8923489bc22f8e2ea8999e..fe66ee7379d367b86dc4c4f3ef1785719a5a5515 100644
--- a/doc/user/project/integrations/pipeline_status_emails.md
+++ b/doc/user/project/integrations/pipeline_status_emails.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pipeline status emails
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can send notifications about pipeline status changes in a group or
project to a list of email addresses.
diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md
index 301ffaa76037bfb711c6636869027fd45fa8e67a..74a0d8eb15e0d79abe32665f781632c4289362f5 100644
--- a/doc/user/project/integrations/pivotal_tracker.md
+++ b/doc/user/project/integrations/pivotal_tracker.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pivotal Tracker
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Pivotal Tracker integration adds commit messages as comments to Pivotal Tracker stories.
diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md
index 7bcee956069deb6f8609eb19f32ab24bac372901..22421d0bf0b51f339642436de093b68eb1c4f4d1 100644
--- a/doc/user/project/integrations/pumble.md
+++ b/doc/user/project/integrations/pumble.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Pumble
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93623) in GitLab 15.3.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93623) in GitLab 15.3.
+
+{{< /history >}}
You can configure GitLab to send notifications to a Pumble channel:
diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md
index f9d8d5fae609435d772cf09568e60101fa56d305..04e0a264a3c3cef4e3002fede036af3cbdaf4a6b 100644
--- a/doc/user/project/integrations/redmine.md
+++ b/doc/user/project/integrations/redmine.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Redmine
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md
index 1f0c8cc49c6e188b200d5fc438e28df9a1343e42..e5711c484029da86236442f96c15d8ecffabae45 100644
--- a/doc/user/project/integrations/slack.md
+++ b/doc/user/project/integrations/slack.md
@@ -7,15 +7,21 @@ title: Slack notifications (deprecated)
<!--- start_remove The following content will be removed on remove_date: '2025-05-15' -->
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/435909) in GitLab 15.9
and is planned for removal in 19.0. Use the [GitLab for Slack app](gitlab_slack_application.md) instead.
This change is a breaking change.
+{{< /alert >}}
+
The Slack notifications integration enables your GitLab project to send events
(such as issue creation) to your existing Slack team as notifications. Setting up
Slack notifications requires configuration changes for both Slack and GitLab.
@@ -32,7 +38,11 @@ to control GitLab from Slack. Slash commands are configured separately.
## Configure GitLab
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Slack channels to 10 per event.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Slack channels to 10 per event.
+
+{{< /history >}}
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > Integrations**.
@@ -87,7 +97,11 @@ The following triggers are available for Slack notifications:
## Trigger notifications for group mentions
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417751) in GitLab 16.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417751) in GitLab 16.4.
+
+{{< /history >}}
To trigger a [notification event](#triggers-for-slack-notifications) for a group mention, use `@<group_name>` in:
@@ -153,9 +167,12 @@ the GitLab OpenSSL trust store is incorrect. Typical causes are:
To disable notifications for all projects that have Slack integration enabled,
[start a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and use a script similar to the following:
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
# Grab all projects that have the Slack notifications enabled
p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN integrations s ON p.id = s.project_id WHERE s.type_new = 'Integrations::Slack' AND s.active = true")
diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md
index a0c30be8f26b96933d7a31086869982c045ea60b..969f3ae9cf686effa00b6bc0fae1a1f6d6b8100c 100644
--- a/doc/user/project/integrations/slack_slash_commands.md
+++ b/doc/user/project/integrations/slack_slash_commands.md
@@ -5,14 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Slack slash commands
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is only configurable on GitLab Self-Managed.
For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead.
+{{< /alert >}}
+
You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations,
like creating an issue, from a [Slack](https://slack.com/) chat environment.
To run slash commands in Slack, you must configure both Slack and GitLab.
diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md
index de4ad99c3e07db7537e4e2c061d361460c695ad9..ec05b778f1acbc79682d97a3700f1e5cf2408e31 100644
--- a/doc/user/project/integrations/squash_tm.md
+++ b/doc/user/project/integrations/squash_tm.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Squash TM
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337855) in GitLab 15.10.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337855) in GitLab 15.10.
+
+{{< /history >}}
When [Squash TM](https://www.squashtest.com/en/squash-gitlab-platform) (Test Management)
integration is enabled and configured in GitLab, issues (typically user stories) created in GitLab
diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md
index d66d1678d1662d42df391339facb4001b4922b27..a6e80e1fd306b2f5a24dac3d4a674cdf5013fb0b 100644
--- a/doc/user/project/integrations/telegram.md
+++ b/doc/user/project/integrations/telegram.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Telegram
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122879) in GitLab 16.1.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122879) in GitLab 16.1.
+
+{{< /history >}}
You can configure GitLab to send notifications to a Telegram chat or channel.
To set up the Telegram integration, you must:
@@ -39,8 +46,12 @@ To configure the bot in Telegram:
## Set up the Telegram integration in GitLab
-> - **Message thread ID** [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/441097) in GitLab 16.11.
-> - **Hostname** [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461313) in GitLab 17.1.
+{{< history >}}
+
+- **Message thread ID** [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/441097) in GitLab 16.11.
+- **Hostname** [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461313) in GitLab 17.1.
+
+{{< /history >}}
After you invite the bot to a Telegram channel, you can configure GitLab to send notifications:
diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md
index dc26e58bc7048b67ec7e94bab03c4fdcf258e196..11c778a28403e5980fc866f63ea36691e800f8a8 100644
--- a/doc/user/project/integrations/unify_circuit.md
+++ b/doc/user/project/integrations/unify_circuit.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Unify Circuit
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The Unify Circuit integration sends notifications from GitLab to a Circuit conversation.
diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md
index 083265c26dd89e8386be367c4f9097ab6250b68f..41f07020259a35fc0f9ae4168f7615e126f6a24d 100644
--- a/doc/user/project/integrations/webex_teams.md
+++ b/doc/user/project/integrations/webex_teams.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Webex Teams
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can configure GitLab to send notifications to a Webex Teams space:
diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md
index 322cc1fc49fd6cc0f5342b8e49f0b6da10b39a8b..df8a47a128447cb823369331c793fe9d8cf6e735 100644
--- a/doc/user/project/integrations/webhook_events.md
+++ b/doc/user/project/integrations/webhook_events.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Webhook events
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page lists the events that are triggered for [project webhooks](webhooks.md) and [group webhooks](webhooks.md#group-webhooks).
@@ -44,11 +47,14 @@ Event type | Trigger
[Project event](#project-events) | A project is created or deleted in a group.
[Subgroup event](#subgroup-events) | A subgroup is created or removed from a group.
-NOTE:
+{{< alert type="note" >}}
+
If an author has no public email listed in their
[GitLab profile](https://gitlab.com/-/user_settings/profile), the `email` attribute in the
webhook payload displays a value of `[REDACTED]`.
+{{< /alert >}}
+
## Push events
Push events are triggered when you push to the repository, except when:
@@ -210,8 +216,12 @@ Payload example:
## Work item events
-> - `type` attribute in `object_attributes` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467415) in GitLab 17.2.
-> - Support for epics [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13056) in GitLab 17.3. Your administrator must have [enabled the new look for epics](../../group/epics/epic_work_items.md).
+{{< history >}}
+
+- `type` attribute in `object_attributes` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/467415) in GitLab 17.2.
+- Support for epics [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13056) in GitLab 17.3. Your administrator must have [enabled the new look for epics](../../group/epics/epic_work_items.md).
+
+{{< /history >}}
Work item events are triggered when a work item is created, edited, closed, or reopened.
The supported work item types are:
@@ -402,7 +412,11 @@ Payload example:
## Comment events
-> - `object_attributes.action` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147856) in GitLab 16.11.
+{{< history >}}
+
+- `object_attributes.action` property [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147856) in GitLab 16.11.
+
+{{< /history >}}
Comment events are triggered when a new comment is made or edited on commits,
merge requests, issues, and code snippets.
@@ -1098,9 +1112,12 @@ Payload example:
}
```
-NOTE:
+{{< alert type="note" >}}
+
The fields `assignee_id` and `merge_status` are [deprecated](../../../api/merge_requests.md).
+{{< /alert >}}
+
## Wiki page events
Wiki page events are triggered when a wiki page is created, updated, or deleted.
@@ -1548,15 +1565,23 @@ Payload example:
### Number of retries
-> - `retries_count` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `job_webhook_retries_count`. Disabled by default.
-> - `retries_count` [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 16.2.
+{{< history >}}
+
+- `retries_count` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `job_webhook_retries_count`. Disabled by default.
+- `retries_count` [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 16.2.
+
+{{< /history >}}
`retries_count` is an integer that indicates if the job is a retry. `0` means that the job
has not been retried. `1` means that it's the first retry.
### Pipeline name
-> - `commit.name` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107963) in GitLab 15.8.
+{{< history >}}
+
+- `commit.name` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107963) in GitLab 15.8.
+
+{{< /history >}}
You can set custom names for pipelines with [`workflow:name`](../../../ci/yaml/_index.md#workflowname).
If the pipeline has a name, that name is the value of `commit.name`.
@@ -1627,10 +1652,17 @@ Payload example:
## Group member events
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
+
+{{< history >}}
+
+- Access request events [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163094) in GitLab 17.4.
-> - Access request events [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163094) in GitLab 17.4.
+{{< /history >}}
These events are triggered for [group webhooks](webhooks.md#group-webhooks) only.
@@ -1729,8 +1761,12 @@ Payload example:
### A user requests access
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163094) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `group_access_request_webhooks`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/479877) in GitLab 17.5. Feature flag `group_access_request_webhooks` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163094) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `group_access_request_webhooks`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/479877) in GitLab 17.5. Feature flag `group_access_request_webhooks` removed.
+
+{{< /history >}}
Request header:
@@ -1760,8 +1796,12 @@ Payload example:
### An access request is denied
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163094) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `group_access_request_webhooks`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/479877) in GitLab 17.5. Feature flag `group_access_request_webhooks` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163094) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `group_access_request_webhooks`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/479877) in GitLab 17.5. Feature flag `group_access_request_webhooks` removed.
+
+{{< /history >}}
Request header:
@@ -1791,10 +1831,17 @@ Payload example:
## Project events
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/359044) in GitLab 17.6.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/359044) in GitLab 17.6.
+
+{{< /history >}}
These events are triggered for [group webhooks](webhooks.md#group-webhooks) only.
@@ -1861,8 +1908,11 @@ Payload example:
## Subgroup events
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
These events are triggered for [group webhooks](webhooks.md#group-webhooks) only.
@@ -1981,7 +2031,11 @@ Payload example:
## Release events
-> - Delete release event [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418113) in GitLab 16.5.
+{{< history >}}
+
+- Delete release event [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418113) in GitLab 16.5.
+
+{{< /history >}}
Release events are triggered when a release is created, updated, or deleted.
@@ -2074,10 +2128,14 @@ Payload example:
## Emoji events
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123952) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `emoji_webhooks`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 16.3.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 16.4.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 17.5. Feature flag `emoji_webhooks` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123952) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `emoji_webhooks`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 16.3.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 16.4.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 17.5. Feature flag `emoji_webhooks` removed.
+
+{{< /history >}}
An emoji event is triggered when an [emoji reaction](../../emoji_reactions.md) is added or removed on:
@@ -2215,10 +2273,14 @@ Payload example:
## Project and group access token events
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141907) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `access_token_webhooks`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/439379) in GitLab 16.11.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/454642) in GitLab 16.11. Feature flag `access_token_webhooks` removed.
-> - `full_path` attribute [added](https://gitlab.com/gitlab-org/gitlab/-/issues/465421) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141907) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `access_token_webhooks`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/439379) in GitLab 16.11.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/454642) in GitLab 16.11. Feature flag `access_token_webhooks` removed.
+- `full_path` attribute [added](https://gitlab.com/gitlab-org/gitlab/-/issues/465421) in GitLab 17.4.
+
+{{< /history >}}
Two access token expiration events are generated:
@@ -2293,8 +2355,12 @@ Payload example for group:
## Vulnerability events
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169701) in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `vulnerabilities_as_webhook_events`. Disabled by default.
-> - Creating an event when a vulnerability is created or when an issue is linked to a vulnerability [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176064) in GitLab 17.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169701) in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `vulnerabilities_as_webhook_events`. Disabled by default.
+- Creating an event when a vulnerability is created or when an issue is linked to a vulnerability [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176064) in GitLab 17.8.
+
+{{< /history >}}
A vulnerability event is triggered when:
diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md
index df7f377765fe054b99bae2558c9bb36e3b8c3fa3..4bc4eca5d362a7e32338f005367f7dda9db8b3ff 100644
--- a/doc/user/project/integrations/webhooks.md
+++ b/doc/user/project/integrations/webhooks.md
@@ -1,14 +1,17 @@
---
stage: Foundations
group: Import and Integrate
-description: Custom HTTP callbacks, used to send events.
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
+description: Custom HTTP callbacks, used to send events.
title: Webhooks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Webhooks are custom HTTP callbacks that send JSON data about events in GitLab to a configured URI.
@@ -43,8 +46,11 @@ For GitLab Self-Managed, administrators can modify these limits.
## Group webhooks
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
Group webhooks are custom HTTP callbacks that send notifications for events across all projects in a group and its subgroups.
@@ -71,7 +77,11 @@ Use these features to set up webhooks that meet your specific requirements.
### Create a webhook
-> - **Name** and **Description** [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141977) in GitLab 16.9.
+{{< history >}}
+
+- **Name** and **Description** [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/141977) in GitLab 16.9.
+
+{{< /history >}}
Create a webhook to send notifications about events in your project or group.
@@ -98,8 +108,12 @@ Your webhook endpoint can use this token to verify the legitimacy of the request
### Mask sensitive portions of webhook URLs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/99995) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `webhook_form_mask_url`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/376106) in GitLab 15.7. Feature flag `webhook_form_mask_url` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/99995) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `webhook_form_mask_url`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/376106) in GitLab 15.7. Feature flag `webhook_form_mask_url` removed.
+
+{{< /history >}}
Mask sensitive portions of webhook URLs to enhance security.
Masked portions are replaced with configured values when webhooks are executed, are not logged, and
@@ -125,8 +139,12 @@ https://webhook.example.com/{path}?key={value}
### Custom headers
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146702) in GitLab 16.11 [with a flag](../../../administration/feature_flags.md) named `custom_webhook_headers`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/448604) in GitLab 17.0. Feature flag `custom_webhook_headers` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/146702) in GitLab 16.11 [with a flag](../../../administration/feature_flags.md) named `custom_webhook_headers`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/448604) in GitLab 17.0. Feature flag `custom_webhook_headers` removed.
+
+{{< /history >}}
Add custom headers to webhook requests for authentication to external services.
You can configure up to 20 custom headers per webhook.
@@ -142,8 +160,12 @@ Custom headers show in [**Recent events**](#view-webhook-request-history) with m
### Custom webhook template
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142738) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `custom_webhook_template`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/439610) in GitLab 17.0. Feature flag `custom_webhook_template` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142738) in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `custom_webhook_template`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/439610) in GitLab 17.0. Feature flag `custom_webhook_template` removed.
+
+{{< /history >}}
Create a custom payload template for your webhook to control the data sent in the request body.
@@ -222,10 +244,17 @@ For example, to exclude the `main` branch, use:
### Configure webhooks to support mutual TLS
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27450) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27450) in GitLab 16.9.
+
+{{< /history >}}
Configure webhooks to support mutual TLS by setting a global client certificate in PEM format.
@@ -239,9 +268,9 @@ To configure mutual TLS for webhooks:
1. Optional: Protect the certificate with a PEM passphrase.
1. Configure GitLab to use the certificate.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`:
@@ -256,7 +285,9 @@ To configure mutual TLS for webhooks:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -279,7 +310,9 @@ To configure mutual TLS for webhooks:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -300,7 +333,9 @@ To configure mutual TLS for webhooks:
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
After configuration, GitLab presents this certificate to the server during TLS handshakes for webhook connections.
@@ -324,7 +359,11 @@ Monitor and maintain your configured webhooks in GitLab.
### View webhook request history
-> - **Recent events** for group webhooks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325642) in GitLab 15.3.
+{{< history >}}
+
+- **Recent events** for group webhooks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325642) in GitLab 15.3.
+
+{{< /history >}}
View the history of webhook requests to monitor their performance and troubleshoot issues.
@@ -437,14 +476,21 @@ To optimize your webhook receivers:
### Auto-disabled webhooks
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) for project webhooks in GitLab 15.7. Feature flag `web_hooks_disable_failed` removed.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385902) for group webhooks in GitLab 15.10.
-> - [Disabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/390157) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`.
+{{< history >}}
+
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) for project webhooks in GitLab 15.7. Feature flag `web_hooks_disable_failed` removed.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385902) for group webhooks in GitLab 15.10.
+- [Disabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/390157) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
GitLab automatically disables project or group webhooks that fail four consecutive times.
To view auto-disabled webhooks:
@@ -475,8 +521,12 @@ Webhooks are permanently disabled if they return response codes in the `4xx` ran
#### Re-enable disabled webhooks
-> - Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed.
+{{< history >}}
+
+- Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed.
+
+{{< /history >}}
To re-enable a temporarily or permanently disabled webhook:
@@ -486,10 +536,14 @@ The webhook is re-enabled if the test request returns a response code in the `2x
### Delivery headers
-> - `X-Gitlab-Event-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8.
-> - `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5.
-> - `X-Gitlab-Webhook-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230830) in GitLab 16.2.
-> - `Idempotency-Key` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388692) in GitLab 17.4.
+{{< history >}}
+
+- `X-Gitlab-Event-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8.
+- `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5.
+- `X-Gitlab-Webhook-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230830) in GitLab 16.2.
+- `Idempotency-Key` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388692) in GitLab 17.4.
+
+{{< /history >}}
GitLab includes the following headers in webhook requests to your endpoint:
diff --git a/doc/user/project/integrations/webhooks_troubleshooting.md b/doc/user/project/integrations/webhooks_troubleshooting.md
index 78adcd7da8cf6216f93cd7d6106dfc3fe13e1e82..b0645d8f17735487017c91ad654087372befdd71 100644
--- a/doc/user/project/integrations/webhooks_troubleshooting.md
+++ b/doc/user/project/integrations/webhooks_troubleshooting.md
@@ -1,14 +1,17 @@
---
stage: Foundations
group: Import and Integrate
-description: Custom HTTP callbacks, used to send events.
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
+description: Custom HTTP callbacks, used to send events.
title: Troubleshooting webhooks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Troubleshoot and resolve common issues with GitLab webhooks.
@@ -28,11 +31,14 @@ For information about webhook events and JSON payloads, see [webhook events](web
Use public tools to inspect and test webhook payloads.
These tools provide catch-all endpoints for HTTP requests and respond with a `200 OK` status code.
-WARNING:
+{{< alert type="warning" >}}
+
Exercise caution when using public tools, as you might send sensitive data to external services.
Use test tokens and rotate any secrets inadvertently sent to third parties.
For enhanced privacy, [create a private webhook receiver](#create-a-private-webhook-receiver).
+{{< /alert >}}
+
Public webhook inspection tools include:
<!-- vale gitlab_base.Spelling = NO -->
@@ -93,9 +99,12 @@ To create a private webhook receiver:
- -> /
```
-NOTE:
+{{< alert type="note" >}}
+
To add this receiver, you might need to [allow requests to the local network](../../../security/webhooks.md).
+{{< /alert >}}
+
## Resolve SSL certificate verification errors
When SSL verification is enabled, GitLab might fail to verify the SSL certificate of the webhook endpoint with the following error:
@@ -114,7 +123,11 @@ To resolve this issue:
## Webhook not triggered
-> - Webhooks not triggered in Silent Mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393639) in GitLab 16.3.
+{{< history >}}
+
+- Webhooks not triggered in Silent Mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393639) in GitLab 16.3.
+
+{{< /history >}}
If a webhook is not triggered, verify that:
diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md
index 9962143d235d49c6ee101574eced968e5e070586..9c805081ebe28d5da923a82e04a87448e9f63f9f 100644
--- a/doc/user/project/integrations/youtrack.md
+++ b/doc/user/project/integrations/youtrack.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: YouTrack
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
JetBrains [YouTrack](https://www.jetbrains.com/youtrack/) is a web-based issue tracking and project
management platform.
diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md
index e79ec2f75ccbe26dd3b76f6e1048cc39a85fbbdd..4dff9d3860081b094e9717fe70c29f3f214e5f66 100644
--- a/doc/user/project/integrations/zentao.md
+++ b/doc/user/project/integrations/zentao.md
@@ -7,15 +7,21 @@ title: ZenTao (deprecated)
<!--- start_remove The following content will be removed on remove_date: '2025-08-01' -->
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377825) in GitLab 15.7
and is planned for removal in 18.0.
This change is a breaking change.
+{{< /alert >}}
+
[ZenTao](https://www.zentao.net/) is a web-based project management platform.
The following versions of ZenTao are supported:
diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md
index 480d5d60dc842b021648f1dd9dfce25ad65fc7e0..f506d8e9385614dd065cc8c76a8b3ba38d27e59b 100644
--- a/doc/user/project/issue_board.md
+++ b/doc/user/project/issue_board.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Issue boards
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Milestones and iterations shown on issue cards [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25758) in GitLab 16.11.
-> - Ability to delete the last board in a group or project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/499579) in GitLab 17.6.
-> - Minimum role to manage issue boards [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Milestones and iterations shown on issue cards [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25758) in GitLab 16.11.
+- Ability to delete the last board in a group or project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/499579) in GitLab 17.6.
+- Minimum role to manage issue boards [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
The issue board is a tool used to plan, organize, and visualize workflows for a product release, a team, or a project.
@@ -41,9 +48,9 @@ Different issue board features are available in different [GitLab tiers](https:/
| Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) |
| -------- | ------------------------------ | --------------------------------------------------- | ------------------------------------------------------- | --------------------------------- |
-| Free | Multiple | 1 | **{dotted-circle}** No | **{dotted-circle}** No |
-| Premium | Multiple | Multiple | **{check-circle}** Yes | **{check-circle}** Yes |
-| Ultimate | Multiple | Multiple | **{check-circle}** Yes | **{check-circle}** Yes |
+| Free | Multiple | 1 | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Premium | Multiple | Multiple | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Ultimate | Multiple | Multiple | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
Read more about [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards).
@@ -95,7 +102,7 @@ Prerequisites:
To delete the open issue board:
-1. In the upper-right corner of the issue board page, select **Configure board** (**{settings}**).
+1. In the upper-right corner of the issue board page, select **Configure board** ({{< icon name="settings" >}}).
1. Select **Delete board**.
1. Select **Delete** to confirm.
@@ -207,7 +214,7 @@ and vice versa.
## Focus mode
In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board.
-To enable or disable focus mode, in the upper-right corner, select **Toggle focus mode** (**{maximize}**).
+To enable or disable focus mode, in the upper-right corner, select **Toggle focus mode** ({{< icon name="maximize" >}}).
## Group issue boards
@@ -223,9 +230,12 @@ advanced functionality is present in [higher tiers only](https://about.gitlab.co
### Configurable issue boards
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
An issue board can be associated with a [milestone](milestones/_index.md),
[labels](labels.md), assignee, weight, and current [iteration](../group/iterations/_index.md),
@@ -234,19 +244,22 @@ This allows you to create unique boards according to your team's need.
-You can define the scope of your board when creating it or by selecting the **Configure board** (**{settings}**) button.
+You can define the scope of your board when creating it or by selecting the **Configure board** ({{< icon name="settings" >}}) button.
After a milestone, iteration, assignee, or weight is assigned to an issue board, you can no longer
filter through these in the search bar. To do that, you need to remove the desired scope
(for example, milestone, assignee, or weight) from the issue board.
If you don't have editing permission in a board, you're still able to see the configuration by
-selecting **Board configuration** (**{settings}**).
+selecting **Board configuration** ({{< icon name="settings" >}}).
### Assignee lists
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
As in a regular list showing all issues with a chosen label, you can add
an assignee list that shows all issues assigned to a user.
@@ -271,9 +284,12 @@ To remove an assignee list, just as with a label list, select the trash icon.
### Milestone lists
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can create milestone lists that filter issues by the assigned
milestone, giving you more freedom and visibility on the issue board.
@@ -297,9 +313,12 @@ As in other list types, select the trash icon to remove a list.
### Iteration lists
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can create lists of issues in an iteration.
@@ -321,9 +340,12 @@ to and from a iteration list to manipulate the iteration of the dragged issues.
### Group issues in swimlanes
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With swimlanes you can visualize issues grouped by epic.
Your issue board keeps all the other features, but with a different visual organization of issues.
@@ -335,7 +357,7 @@ Prerequisites:
To group issues by epic in an issue board:
-1. Select **View options** (**{preferences}**).
+1. Select **View options** ({{< icon name="preferences" >}}).
1. Select **Epic swimlanes**.
@@ -352,9 +374,12 @@ them to change their position and epic assignment:
### Sum of issue weights
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The top of each list indicates the sum of issue weights for the issues that
belong to that list. This is useful when using boards for capacity allocation,
@@ -364,9 +389,12 @@ especially in combination with [assignee lists](#assignee-lists).
### Work in progress limits
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can set a work in progress (WIP) limit for each issue list on an issue board. When a limit is
set, the list's header shows the number of issues in the list and the soft limit of issues. A line in the list separates items within the limit from those in excess of the limit.
@@ -387,7 +415,7 @@ Prerequisites:
To set a WIP limit for a list, in an issue board:
-1. On the top of the list you want to edit, select **Edit list settings** (**{settings}**).
+1. On the top of the list you want to edit, select **Edit list settings** ({{< icon name="settings" >}}).
The list settings sidebar opens on the right.
1. Next to **Work in progress limit**, select **Edit**.
1. Enter the maximum number of issues.
@@ -395,14 +423,17 @@ To set a WIP limit for a list, in an issue board:
### Blocked issues
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If an issue is [blocked by another issue](issues/related_issues.md#blocking-issues), an icon appears next to its title to indicate its blocked
status.
-When you hover over the blocked icon (**{entity-blocked}**), a detailed information popover is displayed.
+When you hover over the blocked icon ({{< icon name="entity-blocked" >}}), a detailed information popover is displayed.
@@ -451,7 +482,11 @@ There, you can edit all the fields, including the description, comments, or rela
### Create a new list
-> - Creating a list between existing lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462515) in GitLab 17.5.
+{{< history >}}
+
+- Creating a list between existing lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462515) in GitLab 17.5.
+
+{{< /history >}}
You can create a new list between two existing lists or at the right of an issue board.
@@ -486,7 +521,7 @@ Prerequisites:
To remove a list from an issue board:
-1. On the top of the list you want to remove, select **Edit list settings** (**{settings}**).
+1. On the top of the list you want to remove, select **Edit list settings** ({{< icon name="settings" >}}).
The list settings sidebar opens on the right.
1. Select **Remove list**.
1. On the confirmation dialog, select **Remove list** again.
@@ -569,7 +604,11 @@ You can't move the **Open** and **Closed** lists, but you can hide them when edi
#### Move an issue to the start of the list
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4.
+
+{{< /history >}}
You can move issues to the top of the list with a menu shortcut.
@@ -582,11 +621,15 @@ Prerequisites:
To move an issue to the start of the list:
1. In an issue board, hover over the card of the issue you want to move.
-1. Select **Card options** (**{ellipsis_v}**), then **Move to start of list**.
+1. Select **Card options** ({{< icon name="ellipsis_v" >}}), then **Move to start of list**.
#### Move an issue to the end of the list
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4.
+
+{{< /history >}}
You can move issues to the bottom of the list with a menu shortcut.
@@ -599,7 +642,7 @@ Prerequisites:
To move an issue to the end of the list:
1. In an issue board, hover over the card of the issue you want to move.
-1. Select **Card options** (**{ellipsis_v}**), then **Move to end of list**.
+1. Select **Card options** ({{< icon name="ellipsis_v" >}}), then **Move to end of list**.
#### Dragging issues between lists
diff --git a/doc/user/project/issues/_index.md b/doc/user/project/issues/_index.md
index 438a55ee5bedf7b431904daf56d1fb7348589af4..60ede00fa966da983c35147c596f747c27a246ac 100644
--- a/doc/user/project/issues/_index.md
+++ b/doc/user/project/issues/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Issues
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Use issues to collaborate on ideas, solve problems, and plan work.
Share and discuss proposals with your team and with outside collaborators.
diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md
index d80e33b6ea8eb3ea49f1cdaea8c91cbc19ecc185..99b75d98e56c14516e8f00012a23b22d2c64a02e 100644
--- a/doc/user/project/issues/associate_zoom_meeting.md
+++ b/doc/user/project/issues/associate_zoom_meeting.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Associate a Zoom meeting with an issue
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To communicate synchronously for incidents management,
you can associate a Zoom meeting with an issue.
diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md
index d3fd64ce3ceb18cfeb65008277dc51fddd68d69e..fc50c000e0c89c339944575820d22439823d3cb7 100644
--- a/doc/user/project/issues/confidential_issues.md
+++ b/doc/user/project/issues/confidential_issues.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Confidential issues
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Confidential issues are [issues](_index.md) visible only to members of a project with
[sufficient permissions](#who-can-see-confidential-issues).
@@ -16,7 +19,11 @@ keep security vulnerabilities private or prevent surprises from leaking out.
## Make an issue confidential
-> - Minimum role to make an issue confidential [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to make an issue confidential [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can make an issue confidential when you create or edit an issue.
@@ -38,7 +45,7 @@ When you create a confidential issue in a project, the project becomes listed in
To create a confidential issue:
1. On the left sidebar, select **Search or go to** and find your project.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**).
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}).
1. From the dropdown list, select **New issue**.
1. Complete the [fields](create_issues.md#fields-in-the-new-issue-form).
- Select the **This issue is confidential** checkbox.
@@ -51,13 +58,17 @@ To change the confidentiality of an existing issue:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**.
1. Select the title of your issue to view it.
-1. In the upper-right corner, select **Issue actions** (**{ellipsis_v}**) and then **Turn on confidentiality** (or **Turn off confidentiality** to make the issue non-confidential).
+1. In the upper-right corner, select **Issue actions** ({{< icon name="ellipsis_v" >}}) and then **Turn on confidentiality** (or **Turn off confidentiality** to make the issue non-confidential).
Alternatively, you can use the `/confidential` [quick action](../quick_actions.md#issues-merge-requests-and-epics).
## Who can see confidential issues
-> - Minimum role to see confidential issues [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to see confidential issues [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
When an issue is made confidential, only users with at least the Planner role
for the project have access to the issue.
@@ -75,13 +86,13 @@ Confidential issues are hidden in search results for users without the necessary
## Confidential issue indicators
Confidential issues are visually different from regular issues in a few ways.
-In the **Issues** and **Issue boards** pages, you can see the confidential (**{eye-slash}**) icon
+In the **Issues** and **Issue boards** pages, you can see the confidential ({{< icon name="eye-slash" >}}) icon
next to issues marked as confidential.
If you don't have [enough permissions](#who-can-see-confidential-issues),
you cannot see confidential issues at all.
-Likewise, while inside the issue, you can see the confidential (**{eye-slash}**) icon right next to
+Likewise, while inside the issue, you can see the confidential ({{< icon name="eye-slash" >}}) icon right next to
the issue number. There is also an indicator in the comment area that the
issue you are commenting on is confidential.
@@ -90,8 +101,8 @@ There is also an indicator on the sidebar denoting confidentiality.
Every change from regular to confidential and vice versa, is indicated by a
system note in the issue's comments, for example:
-> - **{eye-slash}** Jo Garcia made the issue confidential 5 minutes ago
-> - **{eye}** Jo Garcia made the issue visible to everyone just now
+> - {{< icon name="eye-slash" >}} Jo Garcia made the issue confidential 5 minutes ago
+> - {{< icon name="eye" >}} Jo Garcia made the issue visible to everyone just now
## Merge requests for confidential issues
diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md
index 37ff1b974226b9c7e2799384cc146cdee14b3160..c986fd1733b2eb08dd19c59faea4a43fc85a5ea0 100644
--- a/doc/user/project/issues/create_issues.md
+++ b/doc/user/project/issues/create_issues.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Create an issue
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you create an issue, you are prompted to enter the fields of the issue.
If you know the values you want to assign to an issue, you can use
@@ -35,7 +38,7 @@ To create an issue:
1. Either:
- On the left sidebar, select **Plan > Issues**, and then, in the upper-right corner, select **New issue**.
- - On the left sidebar, at the top, select the plus sign (**{plus}**) and then, under **In this project**,
+ - On the left sidebar, at the top, select the plus sign ({{< icon name="plus" >}}) and then, under **In this project**,
select **New issue**.
1. Complete the [fields](#fields-in-the-new-issue-form).
@@ -78,7 +81,7 @@ Prerequisites:
To create an issue from another issue:
-1. In an existing issue, select **Issue actions** (**{ellipsis_v}**).
+1. In an existing issue, select **Issue actions** ({{< icon name="ellipsis_v" >}}).
1. Select **New related issue**.
1. Complete the [fields](#fields-in-the-new-issue-form).
The new issue form has a **Relate to issue #123** checkbox, where `123` is the ID of the
@@ -100,7 +103,7 @@ To create an issue from a project issue board:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issue boards**.
-1. At the top of a board list, select **Create new issue** (**{plus-square}**).
+1. At the top of a board list, select **Create new issue** ({{< icon name="plus-square" >}}).
1. Enter the issue's title.
1. Select **Create issue**.
@@ -108,7 +111,7 @@ To create an issue from a group issue board:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Plan > Issue boards**.
-1. At the top of a board list, select **Create new issue** (**{plus-square}**).
+1. At the top of a board list, select **Create new issue** ({{< icon name="plus-square" >}}).
1. Enter the issue's title.
1. Under **Projects**, select the project in the group that the issue should belong to.
1. Select **Create issue**.
@@ -133,7 +136,7 @@ To email an issue to a project:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**.
1. At the bottom of the page, select **Email a new issue to this project**.
-1. To copy the email address, select **Copy** (**{copy-to-clipboard}**).
+1. To copy the email address, select **Copy** ({{< icon name="copy-to-clipboard" >}}).
1. From your email client, send an email to this address.
The subject is used as the title of the new issue, and the email body becomes the description.
You can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md).
@@ -141,11 +144,14 @@ To email an issue to a project:
A new issue is created, with your user as the author.
You can save this address as a contact in your email client to use it again.
-WARNING:
+{{< alert type="warning" >}}
+
The email address you see is a private email address, generated just for you.
**Keep it to yourself**, because anyone who knows it can create issues or merge requests as if they
were you.
+{{< /alert >}}
+
To regenerate the email address:
1. On the **Issues** page, select **Email a new issue to this project**.
@@ -200,7 +206,11 @@ the appropriate project and followed up from there.
## Fields in the new issue form
-> - Iteration field [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233517) in GitLab 15.6.
+{{< history >}}
+
+- Iteration field [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233517) in GitLab 15.6.
+
+{{< /history >}}
When you're creating a new issue, you can complete the following fields:
diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md
index b764cd51f020672d07c598fe5e0bc3dd661425a0..493e0c28597ee46ca3d8033e4b63adb231717d5c 100644
--- a/doc/user/project/issues/crosslinking_issues.md
+++ b/doc/user/project/issues/crosslinking_issues.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Crosslinking issues
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
There are several ways to mention an issue or make [issues](_index.md) appear in each other's
[Linked issues](related_issues.md) section.
diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md
index c904fb22ee0864d9b184fad369428f60e61092c8..c6d233c6a534531c8ed43a152560bfa74a640368 100644
--- a/doc/user/project/issues/csv_export.md
+++ b/doc/user/project/issues/csv_export.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Export issues to CSV
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Minimum role to export issues [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Minimum role to export issues [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can export issues from GitLab to a plain-text CSV
([comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values))
@@ -46,7 +53,7 @@ Prerequisites:
1. In the dropdown list that appears, select the attributes to filter by.
For more information about filter options, see
[Filter the list of issues](managing_issues.md#filter-the-list-of-issues).
-1. In the upper right, select **Actions** (**{ellipsis_v}**) **> Export as CSV**.
+1. In the upper right, select **Actions** ({{< icon name="ellipsis_v" >}}) **> Export as CSV**.
1. In the dialog, verify that the email address is correct, then select **Export issues**.
All matching issues are exported, including those not shown on the first page.
diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md
index 9e6cb79162f9462adf4affb89100dba700c6b76e..9d507facbb378d6057898e3b8e437c202c4ba8de 100644
--- a/doc/user/project/issues/csv_import.md
+++ b/doc/user/project/issues/csv_import.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Importing issues from CSV
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
> - Additionally [allowed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) for Planner role in GitLab 17.7.
@@ -15,10 +18,10 @@ You can import issues to a project by uploading a CSV file with the following co
| Name | Required? | Description |
|:--------------|:-----------------------|:-------------------------------------------------|
-| `title` | **{check-circle}** Yes | Issue title. |
-| `description` | **{check-circle}** Yes | Issue description. |
-| `due_date` | **{dotted-circle}** No | Issue due date in `YYYY-MM-DD` format. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91317) in GitLab 15.2. |
-| `milestone` | **{dotted-circle}** No | Title of the issue milestone. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112204) in GitLab 16.7. |
+| `title` | {{< icon name="check-circle" >}} Yes | Issue title. |
+| `description` | {{< icon name="check-circle" >}} Yes | Issue description. |
+| `due_date` | {{< icon name="dotted-circle" >}} No | Issue due date in `YYYY-MM-DD` format. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91317) in GitLab 15.2. |
+| `milestone` | {{< icon name="dotted-circle" >}} No | Title of the issue milestone. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112204) in GitLab 16.7. |
Data in other columns is not imported.
@@ -43,7 +46,7 @@ To import issues:
1. Go to your project's **Issues** page.
1. Open the import feature, depending if the project has issues:
- - The project has existing issues: in the upper-right corner, next to **Bulk edit**, select **Actions** (**{ellipsis_v}**) **> Import CSV**.
+ - The project has existing issues: in the upper-right corner, next to **Bulk edit**, select **Actions** ({{< icon name="ellipsis_v" >}}) **> Import CSV**.
- The project has no issues: in the middle of the page, select **Import CSV**.
1. Select the file you want to import, and then select **Import issues**.
diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md
index 9b0c9aab724f934faf34e4c02e3a96bb3e7a6821..783982b2c2fb69cf74b7c679aff5daaaa9e75e5b 100644
--- a/doc/user/project/issues/design_management.md
+++ b/doc/user/project/issues/design_management.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Design management
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With Design Management you can upload design assets (including wireframes and mockups)
to GitLab issues and keep them stored in a single place. Product designers, product managers, and
@@ -75,17 +78,17 @@ The design you selected opens. You can then [zoom in](#zoom-in-on-a-design) on i
When viewing a design, you can move to other designs. To do so, either:
-- In the upper-right corner, select **Go to previous design** (**{chevron-lg-left}**) or **Go to next design** (**{chevron-lg-right}**).
+- In the upper-right corner, select **Go to previous design** ({{< icon name="chevron-lg-left" >}}) or **Go to next design** ({{< icon name="chevron-lg-right" >}}).
- Press <kbd>Left</kbd> or <kbd>Right</kbd> on your keyboard.
To return to the issue view, either:
-- In the upper-left corner, select the close icon (**{close}**).
+- In the upper-left corner, select the close icon ({{< icon name="close" >}}).
- Press <kbd>Esc</kbd> on your keyboard.
-When a design is added, a green icon (**{plus-square}**) is displayed on the image
+When a design is added, a green icon ({{< icon name="plus-square" >}}) is displayed on the image
thumbnail. When a design has been [changed](#add-a-new-version-of-a-design) in the current version,
-a blue icon (**{file-modified-solid}**) is displayed.
+a blue icon ({{< icon name="file-modified-solid" >}}) is displayed.
### Zoom in on a design
@@ -93,15 +96,19 @@ You can explore a design in more detail by zooming in and out of the image:
- To control the amount of zoom, select plus (`+`) and minus (`-`)
at the bottom of the image.
-- To reset the zoom level, select the redo icon (**{redo}**).
+- To reset the zoom level, select the redo icon ({{< icon name="redo" >}}).
To move around the image while zoomed in, drag the image.
## Add a design to an issue
-> - Ability to edit the description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1.
-> - Minimum role to add a design to an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147053) from Developer to Reporter in GitLab 16.11.
-> - Minimum role to add a design to an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Ability to edit the description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1.
+- Minimum role to add a design to an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147053) from Developer to Reporter in GitLab 16.11.
+- Minimum role to add a design to an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -136,8 +143,12 @@ To add a design to an issue:
## Add a new version of a design
-> - Minimum role to add a new version of a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147053) from Developer to Reporter in GitLab 16.11.
-> - Minimum role to add a new version of a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to add a new version of a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147053) from Developer to Reporter in GitLab 16.11.
+- Minimum role to add a new version of a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
As discussion on a design continues, you might want to upload a new version of a design.
@@ -158,8 +169,12 @@ When designs are skipped, a warning message is displayed.
## Archive a design
-> - Minimum role to archive a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147053) from Developer to Reporter in GitLab 16.11.
-> - Minimum role to archive a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to archive a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147053) from Developer to Reporter in GitLab 16.11.
+- Minimum role to archive a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can archive individual designs or select a few of them to archive at once.
@@ -178,7 +193,7 @@ Prerequisites:
To archive a single design:
1. Select the design to view it enlarged.
-1. In the upper-right corner, select **Archive design** (**{archive}**).
+1. In the upper-right corner, select **Archive design** ({{< icon name="archive" >}}).
1. Select **Archive designs**.
To archive multiple designs at once:
@@ -199,9 +214,13 @@ and in GitLab 16.1 and later it can be [verified by Geo as well](https://gitlab.
## Markdown and rich text editors for descriptions
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375172) in GitLab 16.2.
-> - Feature flag `content_editor_on_issues` removed in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375172) in GitLab 16.2.
+- Feature flag `content_editor_on_issues` removed in GitLab 16.5.
+
+{{< /history >}}
You can use the Markdown and rich text editor in design descriptions.
It's the same editor you use for comments across GitLab.
@@ -234,8 +253,12 @@ so that everyone involved can participate in the discussion.
## Delete a comment from a design
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385100) in GitLab 15.9.
-> - Minimum role to delete comment from a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385100) in GitLab 15.9.
+- Minimum role to delete comment from a design [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -243,7 +266,7 @@ Prerequisites:
To delete a comment from a design:
-1. On the comment you want to delete, select **More actions** **{ellipsis_v}** **> Delete comment**.
+1. On the comment you want to delete, select **More actions** {{< icon name="ellipsis_v" >}} **> Delete comment**.
1. On the confirmation dialog, select **Delete comment**.
## Resolve a discussion thread on a design
@@ -252,7 +275,7 @@ When you're done discussing part of a design, you can resolve the discussion thr
To mark a thread as resolved or unresolved, either:
-- In the upper-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** (**{check-circle}**).
+- In the upper-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** ({{< icon name="check-circle" >}}).
- Add a new comment to the thread and select or clear the **Resolve thread** checkbox.
Resolving a discussion thread also marks any pending [to-do items](../../todos.md) related to notes
diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md
index daf6bdc1c8bb00da6a68afd5806fbc580d17ff98..f0175b38bd6aba7fbf3d4643cc12e348a621c280 100644
--- a/doc/user/project/issues/due_dates.md
+++ b/doc/user/project/issues/due_dates.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Due dates
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Minimum role to set due dates [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Minimum role to set due dates [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Use due dates in work items to track deadlines, and make sure features are
shipped on time.
@@ -36,14 +43,14 @@ it is shown below the issue title:
-Issue dates in the past are shown with a red icon (**{calendar-overdue}**).
+Issue dates in the past are shown with a red icon ({{< icon name="calendar-overdue" >}}).
To view and sort issues containing due dates in your project:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**.
1. To sort by due date, select the current sort method, then select **Due date**.
-1. Optional. To reverse the sort order, select **Sort direction** (**{sort-lowest}**).
+1. Optional. To reverse the sort order, select **Sort direction** ({{< icon name="sort-lowest" >}}).
## Set a due date for an issue
@@ -91,6 +98,6 @@ feed can be added to calendar applications.
- [Issues in a specific project](managing_issues.md#issue-list)
- Issues for all projects [in a group](../../group/_index.md)
-1. On the right, from the **Actions** (**{ellipsis_v}**) dropdown list, select **Subscribe to calendar** to display the `.ics` file.
+1. On the right, from the **Actions** ({{< icon name="ellipsis_v" >}}) dropdown list, select **Subscribe to calendar** to display the `.ics` file.
1. Copy the full link to the page (including the full query string) and use it in your
preferred calendar application.
diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md
index e8d4adf560f0d2884472e3b069803f83b3162e41..112b767c4c96a3c86dbf02dddf43d86fbd9f596d 100644
--- a/doc/user/project/issues/issue_weight.md
+++ b/doc/user/project/issues/issue_weight.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Issue weight
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Moved to GitLab Premium in 13.9.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
When you have a lot of issues, it can be hard to get an overview.
With weighted issues, you can get a better idea of how much time,
@@ -21,13 +28,17 @@ to see which issues need to be prioritized.
You can view the issue weight on:
- The right sidebar of each issue.
-- The issues page, next to a weight icon (**{weight}**).
-- [Issue boards](../issue_board.md), next to a weight icon (**{weight}**).
+- The issues page, next to a weight icon ({{< icon name="weight" >}}).
+- [Issue boards](../issue_board.md), next to a weight icon ({{< icon name="weight" >}}).
- The [milestone](../milestones/_index.md) page, as a total sum of issue weights.
## Set the issue weight
-> - Minimum role to set issue weight [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to set issue weight [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -65,7 +76,11 @@ To set the issue weight when you [edit an issue from an issue board](../issue_bo
## Remove issue weight
-> - Minimum role to remove issue weight [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to remove issue weight [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
diff --git a/doc/user/project/issues/issue_work_items.md b/doc/user/project/issues/issue_work_items.md
index bba94f05722c8358c49776da7ddf21283d108684..ee36345fc45647a1a0b1919c47272eeb73ea69b3 100644
--- a/doc/user/project/issues/issue_work_items.md
+++ b/doc/user/project/issues/issue_work_items.md
@@ -5,18 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Test a new look for issues
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9584) in GitLab 17.5 [with a flag](../../../administration/feature_flags.md) named `work_items_view_preference`. Disabled by default. This feature is in [beta](../../../policy/development_stages_support.md#beta).
-> - Enabled on GitLab.com in GitLab 17.9 for a subset of users.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9584) in GitLab 17.5 [with a flag](../../../administration/feature_flags.md) named `work_items_view_preference`. Disabled by default. This feature is in [beta](../../../policy/development_stages_support.md#beta).
+- Enabled on GitLab.com in GitLab 17.9 for a subset of users.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
<!-- When issues as work items are generally available and `work_items_view_preference` flag is removed,
incorporate this content into issues/index.md or managing_issues.md and redirect this page there -->
diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md
index 1624026acc251fa903c21f0a542a08f3327c0965..8572e3225c3416d1d11f975417b0116bd37da677 100644
--- a/doc/user/project/issues/managing_issues.md
+++ b/doc/user/project/issues/managing_issues.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Manage issues
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
After you create an issue, you can start working with it.
## Edit an issue
-> - Minimum role to edit an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to edit an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can edit an issue's title and description.
@@ -25,20 +32,27 @@ To edit an issue:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select the title of your issue to view it.
-1. To the right of the title, select **Edit title and description** (**{pencil}**).
+1. To the right of the title, select **Edit title and description** ({{< icon name="pencil" >}}).
1. Edit the available fields.
1. Select **Save changes**.
### Populate an issue with Issue Description Generation
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com
-**Status:** Experiment
-**LLM:** Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/about-claude/models#claude-3-a-new-generation-of-ai)
+{{< details >}}
+
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com
+- Status: Experiment
+- LLM: Anthropic [Claude 3 Haiku](https://docs.anthropic.com/en/docs/about-claude/models#claude-3-a-new-generation-of-ai)
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10762) in GitLab 16.3 as an [experiment](../../../policy/development_stages_support.md#experiment).
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10762) in GitLab 16.3 as an [experiment](../../../policy/development_stages_support.md#experiment).
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+
+{{< /history >}}
Generate a detailed description for an issue based on a short summary you provide.
@@ -54,7 +68,7 @@ Prerequisites:
To generate an issue description:
1. Create a new issue.
-1. Above the **Description** field, select **GitLab Duo** (**{tanuki-ai}**) **> Generate issue description**.
+1. Above the **Description** field, select **GitLab Duo** ({{< icon name="tanuki-ai" >}}) **> Generate issue description**.
1. Write a short description and select **Submit**.
The issue description is replaced with AI-generated text.
@@ -66,7 +80,11 @@ the large language model.
## Bulk edit issues from a project
-> - Minimum role to bulk edit issues from a project [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to bulk edit issues from a project [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can edit multiple issues at a time when you're in a project.
@@ -97,11 +115,18 @@ When bulk editing issues in a project, you can edit the following attributes:
### Bulk edit issues from a group
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Minimum role to bulk edit issues from a group [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
-> - Minimum role to bulk edit issues from a group [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< /history >}}
You can edit multiple issues across multiple projects when you're in a group.
@@ -128,7 +153,11 @@ When bulk editing issues in a group, you can edit the following attributes:
## Move an issue
-> - Minimum role to move an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to move an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
When you move an issue, it's closed and copied to the target project.
The original issue is not deleted. A [system note](../system_notes.md), which indicates
@@ -152,9 +181,13 @@ You can also use the `/move` [quick action](../quick_actions.md) in a comment or
### Moving tasks when the parent issue is moved
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371252) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `move_issue_children`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/371252) in GitLab 16.11.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371252) in GitLab 17.3. Feature flag `move_issue_children` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371252) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `move_issue_children`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/371252) in GitLab 16.11.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371252) in GitLab 17.3. Feature flag `move_issue_children` removed.
+
+{{< /history >}}
When you move an issue to another project, all its child tasks are also moved to the target project
and remain as child tasks of the moved issue.
@@ -163,15 +196,26 @@ copied to the target project.
### Bulk move issues
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Minimum role to bulk move issues [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Minimum role to bulk move issues [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
#### From the Issues page
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15991) in GitLab 15.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15991) in GitLab 15.6.
+
+{{< /history >}}
You can move multiple issues at the same time when you're in a project.
You can't move tasks or test cases.
@@ -233,7 +277,11 @@ When you use ordered lists, unordered lists, or task lists in issue descriptions
### Delete a task list item
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9.
+
+{{< /history >}}
Prerequisites:
@@ -241,7 +289,7 @@ Prerequisites:
In an issue description with task list items:
-1. Hover over a task list item and select the options menu (**{ellipsis_v}**).
+1. Hover over a task list item and select the options menu ({{< icon name="ellipsis_v" >}}).
1. Select **Delete**.
The task list item is removed from the issue description.
@@ -249,8 +297,12 @@ Any nested task list items are moved up a nested level.
### Reorder list items in the issue description
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.0.
-> - Minimum role to reorder list items in the issue description [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.0.
+- Minimum role to reorder list items in the issue description [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
When you view an issue that has a list in the description, you can also reorder the list items.
@@ -263,14 +315,18 @@ Prerequisites:
To reorder list items, when viewing an issue:
-1. Hover over the list item row to make the grip icon (**{grip}**) visible.
+1. Hover over the list item row to make the grip icon ({{< icon name="grip" >}}) visible.
1. Select and hold the grip icon.
1. Drag the row to the new position in the list.
1. Release the grip icon.
## Close an issue
-> - Minimum role to close an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to close an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
When you decide that an issue is resolved or no longer needed, you can close it.
The issue is marked as closed but is not deleted.
@@ -285,19 +341,23 @@ To close an issue, you can either:
- From any other page in the GitLab UI:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
- 1. In the upper-right corner, select **Issue actions** (**{ellipsis_v}**) and then **Close issue**.
+ 1. In the upper-right corner, select **Issue actions** ({{< icon name="ellipsis_v" >}}) and then **Close issue**.
You can also use the `/close` [quick action](../quick_actions.md) in a comment or description.
### Reopen a closed issue
-> - Minimum role to reopen a closed issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to reopen a closed issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
- You must have at least the Planner role for the project, be the author of the issue, or be assigned to the issue.
-To reopen a closed issue, in the upper-right corner, select **Issue actions** (**{ellipsis_v}**) and then **Reopen issue**.
+To reopen a closed issue, in the upper-right corner, select **Issue actions** ({{< icon name="ellipsis_v" >}}) and then **Reopen issue**.
A reopened issue is no different from any other open issue.
You can also use the `/reopen` [quick action](../quick_actions.md) in a comment or description.
@@ -345,7 +405,11 @@ the list of issues that will be automatically closed.
#### Default closing pattern
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/465391) work item (task, objective, or key result) references in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/465391) work item (task, objective, or key result) references in GitLab 17.3.
+
+{{< /history >}}
To automatically close an issue, use the following keywords followed by the issue reference.
@@ -390,7 +454,11 @@ The default issue closing pattern regex:
#### Disable automatic issue closing
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/240922) in GitLab 15.4: The referenced issue's project setting is checked instead of the project of the commit or merge request.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/240922) in GitLab 15.4: The referenced issue's project setting is checked instead of the project of the commit or merge request.
+
+{{< /history >}}
You can disable the automatic issue closing feature on a per-project basis
in the [project's settings](#disable-automatic-issue-closing).
@@ -416,9 +484,12 @@ Merge requests and commits in this project can still close another project's iss
#### Customize the issue closing pattern
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
@@ -429,7 +500,11 @@ of your installation.
## Change the issue type
-> - Minimum role to change the issue type [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to change the issue type [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -439,7 +514,7 @@ To change issue type:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
-1. To the right of the title, select **Edit title and description** (**{pencil}**).
+1. To the right of the title, select **Edit title and description** ({{< icon name="pencil" >}}).
1. Edit the issue and select an issue type from the **Issue type** dropdown list:
- Issue
@@ -449,7 +524,11 @@ To change issue type:
## Delete an issue
-> - Required role to delete an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Owner to Owner or Planner in GitLab 17.7.
+{{< history >}}
+
+- Required role to delete an issue [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Owner to Owner or Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -459,23 +538,30 @@ To delete an issue:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
-1. In the upper-right corner, select **Issue actions** (**{ellipsis_v}**).
+1. In the upper-right corner, select **Issue actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Delete issue**.
Alternatively:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select the title of your issue to view it.
-1. Select **Edit title and description** (**{pencil}**).
+1. Select **Edit title and description** ({{< icon name="pencil" >}}).
1. Select **Delete issue**.
## Promote an issue to an epic
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - Minimum role to promote an issue to an epic [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to promote an issue to an epic [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can promote an issue to an [epic](../../group/epics/_index.md) in the immediate parent group.
@@ -509,22 +595,29 @@ To promote an issue to an epic:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
-1. In the upper-right corner, select **Issue actions** (**{ellipsis_v}**).
+1. In the upper-right corner, select **Issue actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Promote to epic**.
Alternatively, you can use the `/promote` [quick action](../quick_actions.md#issues-merge-requests-and-epics).
## Promote an issue to an incident
-> - Quick actions to set issue type as incident upon creation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/376760) in GitLab 15.8.
+{{< history >}}
+
+- Quick actions to set issue type as incident upon creation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/376760) in GitLab 15.8.
+
+{{< /history >}}
You can use the `/promote_to_incident` [quick action](../quick_actions.md) to promote the issue to an [incident](../../../operations/incident_management/incidents.md).
## Add an issue to an iteration
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To add an issue to an [iteration](../../group/iterations/_index.md):
@@ -550,7 +643,7 @@ To view all issues assigned to you:
Or:
- To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>i</kbd>.
-- On the left sidebar, at the top, select **Assigned issues** (**{issues}**).
+- On the left sidebar, at the top, select **Assigned issues** ({{< icon name="issues" >}}).
## Issue list
@@ -574,10 +667,14 @@ The following sections describe how to work with the issue list.
### Filter the list of issues
-> - Filtering by type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 13.10 [with a flag](../../../administration/feature_flags.md) named `vue_issues_list`. Disabled by default.
-> - Filtering by type was [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 14.10.
-> - Filtering by type is generally available in GitLab 15.1. [Feature flag `vue_issues_list`](https://gitlab.com/gitlab-org/gitlab/-/issues/359966) removed.
-> - Filtering by health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218711) in GitLab 15.5.
+{{< history >}}
+
+- Filtering by type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 13.10 [with a flag](../../../administration/feature_flags.md) named `vue_issues_list`. Disabled by default.
+- Filtering by type was [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 14.10.
+- Filtering by type is generally available in GitLab 15.1. [Feature flag `vue_issues_list`](https://gitlab.com/gitlab-org/gitlab/-/issues/359966) removed.
+- Filtering by health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218711) in GitLab 15.5.
+
+{{< /history >}}
To filter the list of issues:
@@ -602,7 +699,7 @@ To filter the list issues for text in a title or description:
1. Select **Plan > Issues**.
1. Above the list of issues, in the **Search or filter results** text box, enter the searched phrase.
1. In the dropdown list that appears, select **Search within**, and then either **Titles** or **Descriptions**.
-1. Press <kbd>Enter</kbd> or select the search icon (**{search}**).
+1. Press <kbd>Enter</kbd> or select the search icon ({{< icon name="search" >}}).
Filtering issues uses [PostgreSQL full text search](https://www.postgresql.org/docs/current/textsearch-intro.html)
to match meaningful and significant words to answer a query.
@@ -616,10 +713,14 @@ It's a limitation of PostgreSQL full text search.
#### Filter with the OR operator
-> - OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default.
-> - OR filtering for label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104292) in GitLab 15.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/296031) in GitLab 17.0. Feature flag `or_issuable_queries` removed.
+{{< history >}}
+
+- OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default.
+- OR filtering for label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104292) in GitLab 15.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/296031) in GitLab 17.0. Feature flag `or_issuable_queries` removed.
+
+{{< /history >}}
You can use the OR operator (**is one of: `||`**) when you [filter the list of issues](#filter-the-list-of-issues) by:
@@ -640,16 +741,26 @@ You can use the OR operator (**is one of: `||`**) when you [filter the list of i
### Open issues in a drawer
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464063) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `issues_list_drawer`. Disabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464063) in GitLab 17.4 [with a flag](../../../administration/feature_flags.md) named `issues_list_drawer`. Disabled by default.
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
When this feature is enabled, when you select an issue from the list or issue board, it opens in a drawer.
You can then edit the issue or create comments.
@@ -671,7 +782,7 @@ To copy the issue reference to your clipboard:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
-1. On the right sidebar, next to **Reference**, select **Copy Reference** (**{copy-to-clipboard}**).
+1. On the right sidebar, next to **Reference**, select **Copy Reference** ({{< icon name="copy-to-clipboard" >}}).
You can now paste the reference into another description or comment.
@@ -689,7 +800,7 @@ To copy the issue's email address:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
-1. On the right sidebar, next to **Issue email**, select **Copy Reference** (**{copy-to-clipboard}**).
+1. On the right sidebar, next to **Issue email**, select **Copy Reference** ({{< icon name="copy-to-clipboard" >}}).
## Assignees
@@ -704,7 +815,11 @@ themselves or another project member assigns them.
### Change assignee on an issue
-> - Minimum role to change assignee [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to change assignee [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -731,11 +846,18 @@ Up to five similar issues, sorted by most recently updated, are displayed below
## Health status
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218618) in GitLab 15.4: health status is visible on issue cards in issue boards.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218618) in GitLab 15.4: health status is visible on issue cards in issue boards.
+
+{{< /history >}}
To better track the risk in meeting your plans, you can assign a health status to each issue.
You can use health status to signal to others in your organization whether issues are progressing
@@ -745,7 +867,11 @@ Incorporate a review of issue health status into your daily stand-up, project st
### Change health status of an issue
-> - Minimum role to change health status [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to change health status [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -776,9 +902,12 @@ You can also set and clear health statuses using the `/health_status` and `/clea
## Publish an issue
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If a status page application is associated with the project, you can use the `/publish`
[quick action](../quick_actions.md) to publish the issue.
diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md
index 735c5164301da3ca5491341ddb31c81c901b5a42..e83b147e3d0df56a2c33c0d88897e9c7a6fd460e 100644
--- a/doc/user/project/issues/multiple_assignees_for_issues.md
+++ b/doc/user/project/issues/multiple_assignees_for_issues.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Multiple assignees for issues
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In large teams with shared ownership, it can be difficult
to track who is working on an issue, who's already done, or who hasn't started yet.
diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md
index a830d8fd8e92b8ebcacbe56fd3c26bc321f425c4..6a8e46288927e2201409e51ccd7d0eec713aec4a 100644
--- a/doc/user/project/issues/related_issues.md
+++ b/doc/user/project/issues/related_issues.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Linked issues
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/10267) minimum required role from Reporter (if true) to Guest in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/10267) minimum required role from Reporter (if true) to Guest in GitLab 17.0.
+
+{{< /history >}}
Linked issues are a bi-directional relationship between any two issues and appear in a block below
the issue description. You can link issues in different projects.
@@ -17,9 +24,12 @@ the issue description. You can link issues in different projects.
The relationship only shows up in the UI if the user can see both issues. When you try to close an
issue that has open blockers, a warning is displayed.
-NOTE:
+{{< alert type="note" >}}
+
To manage linked issues through our API, see [Issue links API](../../../api/issue_links.md).
+{{< /alert >}}
+
## Add a linked issue
Prerequisites:
@@ -29,7 +39,7 @@ Prerequisites:
To link one issue to another:
1. In the **Linked items** section of an issue,
- select the add linked issue button (**{plus}**).
+ select the add linked issue button ({{< icon name="plus" >}}).
1. Select the relationship between the two issues. Either:
- **relates to**
- **[blocks](#blocking-issues)**
@@ -60,7 +70,7 @@ For more information, see [Crosslinking issues](crosslinking_issues.md).
## Remove a linked issue
-In the **Linked items** section of an issue, select the remove button (**{close}**) on the
+In the **Linked items** section of an issue, select the remove button ({{< icon name="close" >}}) on the
right-side of each issue token to remove.
Due to the bi-directional relationship, the relationship no longer appears in either issue.
@@ -71,14 +81,17 @@ Access our [permissions](../../permissions.md) page for more information.
## Blocking issues
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you [add a linked issue](#add-a-linked-issue), you can show that it **blocks** or
**is blocked by** another issue.
-Issues blocked by other issues have an icon (**{entity-blocked}**) next to their title, shown in the
+Issues blocked by other issues have an icon ({{< icon name="entity-blocked" >}}) next to their title, shown in the
issue lists and [boards](../issue_board.md).
The icon disappears when the blocking issue is closed or their relationship is changed or
[removed](#remove-a-linked-issue).
diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md
index b9a35e0f9cb5bf2f946259d838903b2f849e9fca..4690fa394d00e93569fca5728c2a3e235b818573 100644
--- a/doc/user/project/issues/sorting_issue_lists.md
+++ b/doc/user/project/issues/sorting_issue_lists.md
@@ -5,18 +5,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sorting and ordering issue lists
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can sort a list of issues several ways.
The available sorting options can change based on the context of the list.
## Sorting by blocking issues
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you sort by **Blocking**, the issue list changes to sort descending by the
number of issues each issue is [blocking](related_issues.md#blocking-issues).
@@ -108,11 +114,18 @@ title in this order:
## Sorting by health status
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377841) in GitLab 15.7.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377841) in GitLab 15.7.
+{{< /history >}}
When you sort by **Health**, the issue list changes to sort by the
[health status](managing_issues.md#health-status) of the issues
diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md
index 1e27436c906591706bb2bd6041334ceccb89cbf4..6f1765b13658fc54e1b75df9ec052ac62b88916f 100644
--- a/doc/user/project/labels.md
+++ b/doc/user/project/labels.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Labels
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Labels are a way to categorize and filter issues, merge requests, and epics in GitLab.
@@ -35,10 +38,14 @@ You can use two types of labels in GitLab:
## Assign and unassign labels
-> - Real-time updates in the sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241538) in GitLab 14.10 with a [feature flag](../../administration/feature_flags.md) named `realtime_labels`, disabled by default.
-> - Real-time updates in the sidebar [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/357370#note_991987201) in GitLab 15.1.
-> - Real-time updates in the sidebar [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/357370) in GitLab 15.5.
-> - Real-time updates in the sidebar [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103199) in GitLab 15.6. Feature flag `realtime_labels` removed.
+{{< history >}}
+
+- Real-time updates in the sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241538) in GitLab 14.10 with a [feature flag](../../administration/feature_flags.md) named `realtime_labels`, disabled by default.
+- Real-time updates in the sidebar [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/357370#note_991987201) in GitLab 15.1.
+- Real-time updates in the sidebar [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/357370) in GitLab 15.5.
+- Real-time updates in the sidebar [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103199) in GitLab 15.6. Feature flag `realtime_labels` removed.
+
+{{< /history >}}
You can assign labels to any issue, merge request, or epic.
@@ -104,7 +111,11 @@ the group's projects.
## Create a label
-> - Minimum role to create a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to create a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -127,7 +138,11 @@ To create a project label:
### Create a project label from an issue or merge request
-> - Minimum role to create a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to create a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can also create a new project label from an issue or merge request.
Labels you create this way belong to the same project as the issue or merge request.
@@ -163,11 +178,18 @@ To create a group label:
### Create a group label from an epic
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - Minimum role to create a group label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+- Minimum role to create a group label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can also create a new group label from an epic.
Labels you create this way belong to the same group as the epic.
@@ -188,7 +210,11 @@ To do so:
## Edit a label
-> - Minimum role to edit a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to edit a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -200,7 +226,7 @@ To edit a **project** label:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Manage > Labels**.
-1. Next to the label you want to edit, select the vertical ellipsis (**{ellipsis_v}**), and then select **Edit**.
+1. Next to the label you want to edit, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), and then select **Edit**.
1. Select **Save changes**.
### Edit a group label
@@ -209,17 +235,24 @@ To edit a **group** label:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Manage > Labels**.
-1. Next to the label you want to edit, select the vertical ellipsis (**{ellipsis_v}**), and then select **Edit**.
+1. Next to the label you want to edit, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), and then select **Edit**.
1. Select **Save changes**.
## Delete a label
-> - Minimum role to delete a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to delete a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
If you delete a label, it is permanently deleted. All references to the label are removed from the
system and you cannot undo the deletion.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Planner role for the project.
@@ -230,7 +263,7 @@ To delete a **project** label:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Manage > Labels**.
-1. Next to the **Subscribe** button, select (**{ellipsis_v}**), and then select **Delete**.
+1. Next to the **Subscribe** button, select ({{< icon name="ellipsis_v" >}}), and then select **Delete**.
### Delete a group label
@@ -240,14 +273,18 @@ To delete a **group** label:
1. Select **Manage > Labels**.
1. Either:
- - Next to the **Subscribe** button, select (**{ellipsis_v}**).
- - Next to the label you want to edit, select **Edit** (**{pencil}**).
+ - Next to the **Subscribe** button, select ({{< icon name="ellipsis_v" >}}).
+ - Next to the label you want to edit, select **Edit** ({{< icon name="pencil" >}}).
1. Select **Delete**.
## Promote a project label to a group label
-> - Minimum role to promote a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to promote a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You might want to make a project label available for other
projects in the same group. Then, you can promote the label to a group label.
@@ -256,9 +293,12 @@ If other projects in the same group have a label with the same title, they are a
merged with the new group label. If a group label with the same title exists, it is
also merged.
-WARNING:
+{{< alert type="warning" >}}
+
Promoting a label is a permanent action and cannot be reversed.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Planner role for the project.
@@ -268,7 +308,7 @@ To promote a project label to a group label:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Manage > Labels**.
-1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and
+1. Next to the **Subscribe** button, select the three dots ({{< icon name="ellipsis_v" >}}) and
select **Promote to group label**.
All issues, merge requests, issue board lists, issue board filters, and label subscriptions
@@ -278,7 +318,11 @@ The new group label has the same ID as the previous project label.
## Promote a subgroup label to the parent group
-> - Minimum role to promote a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to promote a label [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
It's not possible to directly promote a group label to the parent group.
To achieve this, use the following workaround.
@@ -309,7 +353,11 @@ to the same issues, MRs, and epics.
## Generate default project labels
-> - Minimum role to generate default labels [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to generate default labels [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
If a project or its parent group has no labels, you can generate a default set of project
labels from the label list page.
@@ -338,9 +386,12 @@ The following labels are created:
## Scoped labels
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Teams can use scoped labels to annotate issues, merge requests, and epics with mutually exclusive
labels. By preventing certain labels from being used together, you can create more complex workflows.
@@ -368,9 +419,12 @@ To filter issue, merge request, or epic lists by a given scope, enter
For example, filtering by the `platform::*` label returns issues that have `platform::iOS`,
`platform::Android`, or `platform::Linux` labels.
-NOTE:
+{{< alert type="note" >}}
+
Filtering by scoped labels not available on the issues or merge requests dashboard pages.
+{{< /alert >}}
+
### Scoped labels examples
**Example 1.** Updating issue priority:
@@ -450,7 +504,11 @@ To subscribe to a label:
## Set label priority
-> - Minimum role to set label priority [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Minimum role to set label priority [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Labels can have relative priorities, which are used when you sort issue and merge request lists
by [label priority](issues/sorting_issue_lists.md#sorting-by-label-priority) and [priority](issues/sorting_issue_lists.md#sorting-by-priority).
@@ -458,10 +516,13 @@ by [label priority](issues/sorting_issue_lists.md#sorting-by-label-priority) and
When prioritizing labels, you must do it from a project.
It's not possible to do it from the group label list.
-NOTE:
+{{< alert type="note" >}}
+
Priority sorting is based on the highest priority label only.
[This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Planner role for the project.
@@ -470,7 +531,7 @@ To prioritize a label:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Manage > Labels**.
-1. Next to a label you want to prioritize, select the star (**{star-o}**).
+1. Next to a label you want to prioritize, select the star ({{< icon name="star-o" >}}).
@@ -484,19 +545,29 @@ To learn what happens when you sort by priority or label priority, see
## Lock labels when a merge request is merged
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408676) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `enforce_locked_labels_on_merge`. This feature is [beta](../../policy/development_stages_support.md). Disabled by default.
-> - Minimum role to lock labels [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408676) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `enforce_locked_labels_on_merge`. This feature is [beta](../../policy/development_stages_support.md). Disabled by default.
+- Minimum role to lock labels [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
To comply with certain auditing requirements, you can set a label to be locked.
When a merge request with locked labels gets merged, nobody can remove them from the MR.
@@ -506,14 +577,17 @@ Prerequisites:
- You must have at least the Planner role for the project or group.
-WARNING:
+{{< alert type="warning" >}}
+
After you set a label as locked, nobody can undo it or delete the label.
+{{< /alert >}}
+
To set a label to get locked on merge:
1. On the left sidebar, select **Search or go to** and find your group or project.
1. Select **Manage > Labels**.
-1. Next to the label you want to edit, select the vertical ellipsis (**{ellipsis_v}**), and then select **Edit**.
+1. Next to the label you want to edit, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), and then select **Edit**.
1. Select the **Lock label after a merge request is merged** checkbox.
1. Select **Save changes**.
diff --git a/doc/user/project/members/_index.md b/doc/user/project/members/_index.md
index 09e04aaee4c6d829933fd2a312983beed420f1e0..e0e5fa8f64e2b04c171f647375659441293486c2 100644
--- a/doc/user/project/members/_index.md
+++ b/doc/user/project/members/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Members of a project
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Members are the users and groups who have access to your project.
@@ -15,9 +18,13 @@ Each member gets a role, which determines what they can do in the project.
## Membership types
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to display invited group members on the Members tab of the Members page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
-> - Feature flag `webui_members_inherited_users` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
-> - Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to display invited group members on the Members tab of the Members page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
+- Feature flag `webui_members_inherited_users` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
+- Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+
+{{< /history >}}
Users can become members of a group or project directly or indirectly.
Indirect membership can be inherited, shared, or inherited shared.
@@ -70,8 +77,12 @@ In the above example:
## Add users to a project
-> - Expiring access email notification [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.2.
-> - Access expiration date for direct members of subgroups and projects [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471051) in GitLab 17.4.
+{{< history >}}
+
+- Expiring access email notification [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.2.
+- Access expiration date for direct members of subgroups and projects [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471051) in GitLab 17.4.
+
+{{< /history >}}
Add users to a project so they become direct members and have permission
to perform actions.
@@ -100,10 +111,13 @@ To add a user to a project:
If you selected an access expiration date, the project member gets an email notification
seven days before their access expires.
- WARNING:
+ {{< alert type="warning" >}}
+
Maintainers have full permissions until their role expires, including the ability to
extend their own access expiration date.
+ {{< /alert >}}
+
1. Select **Invite**.
If you invited the user using their:
@@ -150,9 +164,12 @@ Instead of adding users one by one, you can [share a project with an entire grou
You can import another project's direct members to your own project.
Imported project members retain the same permissions as the project you import them from.
-NOTE:
+{{< alert type="note" >}}
+
Only direct members of a project are imported. Inherited or shared members of a project are not imported.
+{{< /alert >}}
+
Prerequisites:
- You must have the Maintainer or Owner role.
@@ -266,7 +283,7 @@ To sort members:
GitLab users can request to become a member of a project.
1. On the left sidebar, select **Search or go to** and find the project you want to be a member of.
-1. In the top right, select the vertical ellipsis (**{ellipsis_v}**) and select **Request Access**.
+1. In the top right, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and select **Request Access**.
An email is sent to the most recently active project Maintainers or Owners.
Up to ten project Maintainers or Owners are notified.
@@ -307,13 +324,13 @@ The following table lists the membership and visibility rights of project member
| Action | Direct project member | Inherited project member | Direct shared project member | Inherited shared project member |
| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- |
-| Generate boards | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| View issues of parent groups <sup>1</sup> | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| View labels of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| View milestones of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Be shared into other groups | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| Be imported into other projects | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| Share the project with other members | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
+| Generate boards | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| View issues of parent groups <sup>1</sup> | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| View labels of parent groups | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| View milestones of parent groups | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Be shared into other groups | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Be imported into other projects | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Share the project with other members | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
**Footnotes:**
@@ -323,10 +340,10 @@ The following table lists the membership and visibility rights of group members.
| Action | Direct group member | Inherited group member | Direct shared group member | Inherited shared group member |
| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- |
-| Generate boards | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| View issues of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| View labels of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| View milestones of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
+| Generate boards | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| View issues of parent groups | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| View labels of parent groups | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| View milestones of parent groups | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
In the following example, `User` is a:
diff --git a/doc/user/project/members/sharing_projects_groups.md b/doc/user/project/members/sharing_projects_groups.md
index f50c2c581b8bf9738959b9831579a0c93b32b033..8ee8ea5cc4ec63ff0ed44c0a7ea23cdc112890d4 100644
--- a/doc/user/project/members/sharing_projects_groups.md
+++ b/doc/user/project/members/sharing_projects_groups.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Sharing projects and groups
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to display invited group members on the Members tab of the Members page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
-> - Feature flag `webui_members_inherited_users` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
-> - Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to display invited group members on the Members tab of the Members page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
+- Feature flag `webui_members_inherited_users` was [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
+- Feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163627) in GitLab 17.4. Members of invited groups displayed by default.
+
+{{< /history >}}
You can share by invitation:
@@ -32,10 +39,10 @@ The following table provides an overview of the group members that get access to
| Group member source | Access to shared project |
|---------------------------------------------------------------------|--------------------------|
-| Direct member of the group that is shared | **{check-circle}** Yes |
-| Inherited member of the group that is shared | **{check-circle}** Yes |
-| Direct member of a subgroup, but not of the group that is shared | **{dotted-circle}** No |
-| Inherited member of a subgroup, but not of the group that is shared | **{dotted-circle}** No |
+| Direct member of the group that is shared | {{< icon name="check-circle" >}} Yes |
+| Inherited member of the group that is shared | {{< icon name="check-circle" >}} Yes |
+| Direct member of a subgroup, but not of the group that is shared | {{< icon name="dotted-circle" >}} No |
+| Inherited member of a subgroup, but not of the group that is shared | {{< icon name="dotted-circle" >}} No |
The [visibility level](../../public_access.md) of the group you're inviting must be at least as restrictive as that of the project.
For example, you can invite:
@@ -83,11 +90,14 @@ unless one of the following applies:
- The current user is a member of the invited group.
- The current user is an Owner of the current group or the Maintainer/Owner of the current project.
-NOTE:
+{{< alert type="note" >}}
+
The invited group's name and membership source are masked from members who do not have access to the invited group.
However, even if project Maintainers and Owners cannot access the private invited group, they can see the source of private invited group members.
This behavior is intended to help project Maintainers and Owners to better manage the memberships of the projects they own.
+{{< /alert >}}
+
### Examples
A project in the namespace `group/subgroup01/project`:
@@ -103,9 +113,13 @@ For a project that was created by `Group 1`:
### Invite a group to a project
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to display invited group members on the Members tab of the Members page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
-> - Feature flag `webui_members_inherited_users` [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
-> - Access expiration date for direct members of subgroups and projects [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471051), and feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/364078) in GitLab 17.4.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) to display invited group members on the Members tab of the Members page in GitLab 16.10 [with a flag](../../../administration/feature_flags.md) named `webui_members_inherited_users`. Disabled by default.
+- Feature flag `webui_members_inherited_users` [enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/219230) in GitLab 17.0.
+- Access expiration date for direct members of subgroups and projects [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471051), and feature flag `webui_members_inherited_users` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/364078) in GitLab 17.4.
+
+{{< /history >}}
Prerequisites:
@@ -199,9 +213,12 @@ When this setting is enabled:
- It applies to all subgroups, unless overridden by a group Owner.
- Groups already added to a project lose access to it.
-NOTE:
+{{< alert type="note" >}}
+
After you [specify a user cap for the group](../../group/manage.md#specify-a-user-cap-for-a-group), you cannot disable this setting.
+{{< /alert >}}
+
## Sharing groups
When you want a group to have access to your group,
@@ -226,11 +243,14 @@ unless one of the following applies:
- The current user is a member of the invited group.
- The current user is an Owner of the current group or the Maintainer/Owner of the current project.
-NOTE:
+{{< alert type="note" >}}
+
The invited group's name and membership source are masked from members who do not have access to the invited group.
However, even if group Owners cannot access the private invited group, they can see the source of private invited group members.
This behavior is intended to help group Owners to better manage the memberships of the groups they own.
+{{< /alert >}}
+
### Examples
`User A` is a direct member of `Group 1` and has the Maintainer role for the group.
@@ -241,7 +261,11 @@ This behavior is intended to help group Owners to better manage the memberships
### Invite a group to a group
-> - Access expiration date for direct members of subgroups and projects [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471051) in GitLab 17.4.
+{{< history >}}
+
+- Access expiration date for direct members of subgroups and projects [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/471051) in GitLab 17.4.
+
+{{< /history >}}
Similar to how you invite a group to a project, you can invite a group to another group.
@@ -267,7 +291,7 @@ To remove an invited group:
1. On the left sidebar, select **Search or go to** and find your group.
1. Select **Manage > Members**.
1. Select the **Groups** tab.
-1. To the right of the group you want to remove, select **Remove group** (**{remove}**).
+1. To the right of the group you want to remove, select **Remove group** ({{< icon name="remove" >}}).
When you remove the invited group from your group:
diff --git a/doc/user/project/merge_requests/_index.md b/doc/user/project/merge_requests/_index.md
index aefaf12b3299d605c2365787091a8a158fe18872..a7c39472aa4d22b73b7e981214193bf42040ce28 100644
--- a/doc/user/project/merge_requests/_index.md
+++ b/doc/user/project/merge_requests/_index.md
@@ -2,16 +2,23 @@
stage: Create
group: Code Review
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
-description: "Propose, review, and collaborate on changes to a project."
+description: Propose, review, and collaborate on changes to a project.
title: Merge requests
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Sidebar actions menu [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/373757) to also move actions on issues, incidents, and epics in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127001) in GitLab 16.9. Feature flag `moved_mr_sidebar` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Sidebar actions menu [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/373757) to also move actions on issues, incidents, and epics in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127001) in GitLab 16.9. Feature flag `moved_mr_sidebar` removed.
+
+{{< /history >}}
A merge request (MR) is a proposal to incorporate changes from a source branch to a target branch.
@@ -41,16 +48,19 @@ found to your merge request:
| Commit message with an [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) like `Closes #1234` | 1 | 2 | 3 | 4 | 5 \* |
| Branch name [prefixed with an issue ID](../repository/branches/_index.md#prefix-branch-names-with-issue-numbers), like `1234-example` | 1 \* | 2 \* | 3 \* | 4 \* | 5 \* |
-NOTE:
+{{< alert type="note" >}}
+
Items marked with an asterisk (\*) also append an [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically).
+{{< /alert >}}
+
## View merge requests
You can view merge requests for your project, group, or yourself.
-::Tabs
+{{< tabs >}}
-:::TabTitle You're participating in
+{{< tab title="You're participating in" >}}
To view all merge requests on the homepage, use the <kbd>Shift</kbd> + <kbd>m</kbd>
[keyboard shortcut](../../shortcuts.md), or:
@@ -62,7 +72,9 @@ or:
1. On the left sidebar, select **Search or go to**.
1. From the dropdown list, select **Merge requests**.
-:::TabTitle For a project
+{{< /tab >}}
+
+{{< tab title="For a project" >}}
To view all merge requests for a project:
@@ -71,7 +83,9 @@ To view all merge requests for a project:
Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>.
-:::TabTitle For all projects in a group
+{{< /tab >}}
+
+{{< tab title="For all projects in a group" >}}
To view merge requests for all projects in a group:
@@ -80,13 +94,19 @@ To view merge requests for all projects in a group:
If your group contains subgroups, this view also displays merge requests from the subgroup projects.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Filter the list of merge requests
-> - Filtering by `source-branch` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134555) in GitLab 16.6.
-> - Filtering by `merged-by` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140002) in GitLab 16.9. Available only when the feature flag `mr_merge_user_filter` is enabled.
-> - Filtering by `merged-by` [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142666) in GitLab 17.0. Feature flag `mr_merge_user_filter` removed.
+{{< history >}}
+
+- Filtering by `source-branch` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134555) in GitLab 16.6.
+- Filtering by `merged-by` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140002) in GitLab 16.9. Available only when the feature flag `mr_merge_user_filter` is enabled.
+- Filtering by `merged-by` [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142666) in GitLab 17.0. Feature flag `mr_merge_user_filter` removed.
+
+{{< /history >}}
To filter the list of merge requests:
@@ -110,8 +130,8 @@ To filter the list of merge requests:
You can filter some attributes by **None** or **Any**.
1. Repeat this process to filter by more attributes, joined by a logical
`AND`.
-1. Select a **Sort direction**, either **{sort-lowest}** for descending order,
- or **{sort-highest}** for ascending order.
+1. Select a **Sort direction**, either {{< icon name="sort-lowest" >}} for descending order,
+ or {{< icon name="sort-highest" >}} for ascending order.
### By environment or deployment date
@@ -122,10 +142,13 @@ you can type (or select from the dropdown list) the following:
- Deployed-before
- Deployed-after
-NOTE:
+{{< alert type="note" >}}
+
Projects using a [fast-forward merge method](methods/_index.md#fast-forward-merge)
do not return results, as this method does not create a merge commit.
+{{< /alert >}}
+
When filtering by an environment, a dropdown list presents all environments that
you can choose from.
@@ -223,9 +246,12 @@ If the user lacks the correct role, such as in a forked project, the source bran
### Update merge requests when target branch merges
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Merge requests are often chained together, with one merge request depending on
the code added or changed in another merge request. To support keeping individual
@@ -282,11 +308,15 @@ For a web developer writing a webpage for your company's website:
## Filter activity in a merge request
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115383) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `mr_activity_filters`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/387070) in GitLab 16.0.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126998) in GitLab 16.3 by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132355) in GitLab 16.5. Feature flag `mr_activity_filters` removed.
-> - Filtering bot comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128473) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115383) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `mr_activity_filters`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/387070) in GitLab 16.0.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126998) in GitLab 16.3 by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132355) in GitLab 16.5. Feature flag `mr_activity_filters` removed.
+- Filtering bot comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128473) in GitLab 16.9.
+
+{{< /history >}}
To understand the history of a merge request, filter its activity feed to show you
only the items that are relevant to you.
@@ -312,7 +342,7 @@ only the items that are relevant to you.
- Merge request status
- Tracking
-1. Optional. Select **Sort** (**{sort-lowest}**) to reverse the sort order.
+1. Optional. Select **Sort** ({{< icon name="sort-lowest" >}}) to reverse the sort order.
Your selection persists across all merge requests. You can also change the
sort order by clicking the sort button on the right.
@@ -333,7 +363,7 @@ create an issue to resolve them separately:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests** and find your merge request.
1. In the merge request, in the top right, find the **Unresolved threads**
- dropdown list, and select **Thread options** (**{ellipsis_v}**).
+ dropdown list, and select **Thread options** ({{< icon name="ellipsis_v" >}}).
1. Select **Resolve all with new issue**.
1. Fill out the fields in the new issue, and select **Create issue**.
@@ -349,7 +379,7 @@ create an issue to resolve it separately:
1. Select **Code > Merge requests** and find your merge request.
1. In the merge request, find the thread you want to move.
1. Below the last reply to the thread, next to **Resolve thread**, select
- **Create issue to resolve thread** (**{issue-new}**).
+ **Create issue to resolve thread** ({{< icon name="issue-new" >}}).
1. Fill out the fields in the new issue, and select **Create issue**.
GitLab marks the thread as resolved, and adds a link from the merge request to
@@ -382,17 +412,27 @@ Threads on lines that don't change and top-level resolvable threads are not reso
## Move notifications and to-dos
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132678) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `notifications_todos_buttons`. Disabled by default.
-> - [Issues, incidents](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133474), and [epics](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133881) also updated.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132678) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `notifications_todos_buttons`. Disabled by default.
+- [Issues, incidents](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133474), and [epics](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133881) also updated.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `notifications_todos_buttons`.
On GitLab.com and GitLab Dedicated, this feature is not available.
+{{< /alert >}}
+
Enabling this feature flag moves the notifications and to-do item buttons to the upper right corner of the page.
- On merge requests, these buttons are shown to the far right of the tabs.
diff --git a/doc/user/project/merge_requests/ai_in_merge_requests.md b/doc/user/project/merge_requests/ai_in_merge_requests.md
index 218a82cf235c8fdfdfa89be88cca90f92efbd5a7..a97c19b9032c9f04e1713112dcde5e13e2a20e0e 100644
--- a/doc/user/project/merge_requests/ai_in_merge_requests.md
+++ b/doc/user/project/merge_requests/ai_in_merge_requests.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'duo_in_merge_requests.md'
-remove_date: '2025-06-11'
+redirect_to: duo_in_merge_requests.md
+remove_date: "2025-06-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md
index 95a99270579f0e1403de07fe7a708de5c444d69f..974030061c0048bfad3d634bc702e7cf51c70f23 100644
--- a/doc/user/project/merge_requests/allow_collaboration.md
+++ b/doc/user/project/merge_requests/allow_collaboration.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "When you fork a merge request, you can set whether or not members of the upstream repository can contribute to your fork."
+description: When you fork a merge request, you can set whether or not members of the upstream repository can contribute to your fork.
title: Collaborate on merge requests across forks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you open a merge request from your [fork](../repository/forking_workflow.md), you can allow upstream
members to collaborate with you on your branch.
diff --git a/doc/user/project/merge_requests/approvals/_index.md b/doc/user/project/merge_requests/approvals/_index.md
index efa7b1c6d09fc2142a8c85e82b1daf218cb97770..6afa26512a61ff2120b6be0e44d7eade40495a17 100644
--- a/doc/user/project/merge_requests/approvals/_index.md
+++ b/doc/user/project/merge_requests/approvals/_index.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "To ensure all changes are reviewed, configure optional or required approvals for merge requests in your project."
+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
+description: To ensure all changes are reviewed, configure optional or required approvals for merge requests in your project.
title: Merge request approvals
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To set up a review process for changes in your project, configure merge request approvals.
They help to ensure that changes are reviewed before they're merged into your project.
@@ -27,10 +30,13 @@ You can configure approvals to be optional or required, depending on your projec
[for the entire instance](../../../../administration/merge_requests_approvals.md).
- Configure [group merge request approval settings](../../../group/manage.md#group-merge-request-approval-settings).
- NOTE:
+ {{< alert type="note" >}}
+
Support for group merge request approval settings is tracked in
[epic 4367](https://gitlab.com/groups/gitlab-org/-/epics/4367).
+ {{< /alert >}}
+
## Configure approval rules
Prerequisites:
@@ -54,9 +60,12 @@ For more information on configuring rules, see [Approval rules](rules.md).
### Required approvals
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Required approvals enforce code reviews by specified users. Without these approvals, merging is not possible.
@@ -71,7 +80,11 @@ Use cases include:
## View approval status
-> - More granular approver display [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178005) in GitLab 17.9 [with a flag](../../../../administration/feature_flags.md) named `mr_approvers_filter_hidden_users`. Enabled by default.
+{{< history >}}
+
+- More granular approver display [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178005) in GitLab 17.9 [with a flag](../../../../administration/feature_flags.md) named `mr_approvers_filter_hidden_users`. Enabled by default.
+
+{{< /history >}}
You can see the approval status of a merge request in two places. On the [merge request itself](#for-a-single-merge-request)
and in the [list of merge requests](#in-the-list-of-merge-requests) for your project or group.
@@ -95,7 +108,7 @@ The widget displays one of these statuses:
- **Approve additionally**: The merge request has the required approvals.
- **Revoke approval**: You have already approved the merge request.
-To check if your approval satisfies Code Owner requirements, select **Expand eligible approvers** (**{chevron-lg-down}**).
+To check if your approval satisfies Code Owner requirements, select **Expand eligible approvers** ({{< icon name="chevron-lg-down" >}}).
If you have enabled the `mr_approvers_filter_hidden_users` feature flag, introduced in GitLab 17.9,
approver visibility depends on your project membership, and group privacy:
@@ -112,9 +125,9 @@ shows the approval status for each merge request:
| Example | Description |
| :-----: | :---------- |
-|  | Required approvals are missing. (**{approval}**) |
-|  | Approvals are satisfied. (**{check}**) |
-|  | Approvals are satisfied, and you are one of the approvers. (**{approval-solid}**) |
+|  | Required approvals are missing. ({{< icon name="approval" >}}) |
+|  | Approvals are satisfied. ({{< icon name="check" >}}) |
+|  | Approvals are satisfied, and you are one of the approvers. ({{< icon name="approval-solid" >}}) |
### Individual reviewer status
@@ -125,15 +138,15 @@ To see the review and approval status for each reviewer:
Each reviewer's status is shown next to the their name.
-- **{dash-circle}** Awaiting review
-- **{status_running}** Review in progress
-- **{check-circle}** Approved
-- **{comment-lines}** Reviewer commented
-- **{status_warning}** Reviewer requested changes
+- {{< icon name="dash-circle" >}} Awaiting review
+- {{< icon name="status_running" >}} Review in progress
+- {{< icon name="check-circle" >}} Approved
+- {{< icon name="comment-lines" >}} Reviewer commented
+- {{< icon name="status_warning" >}} Reviewer requested changes
-To [re-request a review](../reviews/_index.md#re-request-a-review), select the **Re-request a review** icon (**{redo}**) next to the user.
+To [re-request a review](../reviews/_index.md#re-request-a-review), select the **Re-request a review** icon ({{< icon name="redo" >}}) next to the user.
## Approve a merge request
@@ -142,7 +155,7 @@ Eligible approvers can approve merge requests in two ways:
1. Select **Approve** in the merge request widget.
1. Use the `/approve` [quick action](../../quick_actions.md) in a comment.
-Approved merge requests display a green check mark (**{check-circle-filled}**) next to the user's name in the reviewer list.
+Approved merge requests display a green check mark ({{< icon name="check-circle-filled" >}}) next to the user's name in the reviewer list.
After a merge request receives the required approvals, it is ready to merge, unless it's blocked due to:
- [Merge conflicts](../conflicts.md)
@@ -160,9 +173,13 @@ don't affect existing merge requests, except for [target branch](rules.md#approv
## Invalid rules
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/389905) in GitLab 15.11 [with a flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/405023) in GitLab 16.2. Feature flag `invalid_scan_result_policy_prevents_merge` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/389905) in GitLab 15.11 [with a flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/405023) in GitLab 16.2. Feature flag `invalid_scan_result_policy_prevents_merge` removed.
+
+{{< /history >}}
GitLab marks approval rules as **Auto approved** when they're impossible to satisfy, such as when:
diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md
index 64d05b618f02c2439d60b382b3e60faf1831ee39..3c5998ffcaede7919de1c7c5e24e17307869b681 100644
--- a/doc/user/project/merge_requests/approvals/rules.md
+++ b/doc/user/project/merge_requests/approvals/rules.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Use approval rules to define the users or groups who should approve merge requests. Approvers can be optional or required."
+description: Use approval rules to define the users or groups who should approve merge requests. Approvers can be optional or required.
title: Merge request approval rules
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Approval rules define how many [approvals](_index.md) a merge request must receive before it can
be merged, and which users should do the approving. They can be used in conjunction
@@ -36,7 +39,11 @@ Merge request approvals can be configured globally to apply across all (or a sub
## Add an approval rule
-> - Approval rules for all protected branches introduced in GitLab 15.3.
+{{< history >}}
+
+- Approval rules for all protected branches introduced in GitLab 15.3.
+
+{{< /history >}}
Prerequisites:
@@ -90,7 +97,7 @@ To edit a merge request approval rule:
creates a required rule.
Maximum number of required approvals is `100`.
- To remove users or groups, identify the group or user to remove, and select **Remove**
- (**{remove}**).
+ ({{< icon name="remove" >}}).
1. Select **Save changes**.
## Delete an approval rule
@@ -103,7 +110,7 @@ To delete a merge request approval rule:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > Merge requests**.
-1. In the **Merge request approvals** section, next to the rule you want to delete, select the trash can (**{remove}**).
+1. In the **Merge request approvals** section, next to the rule you want to delete, select the trash can ({{< icon name="remove" >}}).
1. Select **Remove approvers**.
## Multiple approval rules
@@ -267,7 +274,11 @@ To make an approval rule optional, you can also [use the API](../../../../api/me
## Approvals for protected branches
-> - **All protected branches** target branch option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360930) in GitLab 15.3.
+{{< history >}}
+
+- **All protected branches** target branch option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360930) in GitLab 15.3.
+
+{{< /history >}}
Approval rules are often relevant only to specific branches, like your
[default branch](../../repository/branches/default.md). To configure an
@@ -284,13 +295,20 @@ approval rule for certain branches:
## Security Approvals
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Security approvals moved to merge request approvals settings [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0.
+- Bot comment for approvals [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/411656) in GitLab 16.2 [with a flag](../../../../administration/feature_flags.md) named `security_policy_approval_notification`. Enabled by default.
+- Bot comment for approvals [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130827) in GitLab 16.3. Feature flag `security_policy_approval_notification` removed.
-> - Security approvals moved to merge request approvals settings [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0.
-> - Bot comment for approvals [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/411656) in GitLab 16.2 [with a flag](../../../../administration/feature_flags.md) named `security_policy_approval_notification`. Enabled by default.
-> - Bot comment for approvals [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130827) in GitLab 16.3. Feature flag `security_policy_approval_notification` removed.
+{{< /history >}}
You can use [merge request approval policies](../../../application_security/policies/merge_request_approval_policies.md#merge-request-approval-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch.
Details for each security policy is shown in the Security Approvals section of your Merge Request configuration.
diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md
index 38a544f6e9a05681b414b660e01d71aa55231e33..ef09662c59183dd971f260a25401683e7c61f35f 100644
--- a/doc/user/project/merge_requests/approvals/settings.md
+++ b/doc/user/project/merge_requests/approvals/settings.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Define approval rules and limits in GitLab with merge request approval settings. Options include preventing author approval, requiring re-authentication, and removing approvals on new commits."
+description: Define approval rules and limits in GitLab with merge request approval settings. Options include preventing author approval, requiring re-authentication, and removing approvals on new commits.
title: Merge request approval settings
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can configure the settings for [merge request approvals](_index.md) to
ensure the approval rules meet your use case. You can also configure
@@ -77,8 +80,12 @@ this setting, unless you configure one of these options:
## Prevent approvals by users who add commits
-> - [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127744) added in GitLab 16.3 to also include merge commits in this check.
-> - [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131778) removed in GitLab 16.5. This check now includes merge commits.
+{{< history >}}
+
+- [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127744) added in GitLab 16.3 to also include merge commits in this check.
+- [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131778) removed in GitLab 16.5. This check now includes merge commits.
+
+{{< /history >}}
By default, users who commit to a merge request can still approve it. You can prevent committers
in your project or on your instance from approving merge requests that are partially
@@ -122,14 +129,21 @@ When you change this field, it can affect all open merge requests depending on t
## Require user re-authentication to approve
-> - Requiring re-authentication by using SAML authentication for GitLab.com groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default.
-> - Requiring re-authentication by using SAML authentication for GitLab Self-Managed instances [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431415) in GitLab 16.7 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default.
-> - [Enabled `ff_require_saml_auth_to_approve` by default](https://gitlab.com/gitlab-org/gitlab/-/issues/431714) in GitLab 16.8 for GitLab.com and GitLab Self-Managed instances.
+{{< history >}}
+
+- Requiring re-authentication by using SAML authentication for GitLab.com groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default.
+- Requiring re-authentication by using SAML authentication for GitLab Self-Managed instances [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431415) in GitLab 16.7 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default.
+- [Enabled `ff_require_saml_auth_to_approve` by default](https://gitlab.com/gitlab-org/gitlab/-/issues/431714) in GitLab 16.8 for GitLab.com and GitLab Self-Managed instances.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default requiring re-authentication by using SAML authentication is available. To hide the feature, an administrator can
[disable the feature flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. On GitLab.com and GitLab Dedicated, this feature is available.
+{{< /alert >}}
+
You can force potential approvers to first authenticate with SAML or a password.
This permission enables an electronic signature for approvals, such as the one defined by
[Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3).
@@ -153,9 +167,12 @@ Prerequisites:
## Remove all approvals when commits are added to the source branch
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
By default, an approval on a merge request is removed when you add more changes
after the approval. In GitLab Premium and Ultimate tiers, to keep existing approvals
@@ -176,7 +193,11 @@ you perform commands like `git rebase` or `git merge <target>` on a feature bran
## Remove approvals by Code Owners if their files changed
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90578) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90578) in GitLab 15.3.
+
+{{< /history >}}
To remove approvals only from Code Owners whose files change in a new commit:
diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md
index 1d04a5b52d976ad7730be7cd5085f909468c98c5..0f1d7c50835d8635a605fcfec110f7dc6f8c3b6c 100644
--- a/doc/user/project/merge_requests/authorization_for_merge_requests.md
+++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "The most common merge request flows in GitLab use forks, protected branches, or both."
+description: The most common merge request flows in GitLab use forks, protected branches, or both.
title: Merge request workflows
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab merge requests commonly follow one of these flows:
diff --git a/doc/user/project/merge_requests/auto_merge.md b/doc/user/project/merge_requests/auto_merge.md
index 535980110d44f60d92d2508d7b6373a019c966ec..00ce56b50d1296ff21b447482dfc23cf49766c6f 100644
--- a/doc/user/project/merge_requests/auto_merge.md
+++ b/doc/user/project/merge_requests/auto_merge.md
@@ -2,24 +2,31 @@
stage: Create
group: Code Review
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
-description: "Set auto-merge on a merge request when you have reviewed its content, so it can merge without intervention when all merge checks pass."
+description: Set auto-merge on a merge request when you have reviewed its content, so it can merge without intervention when all merge checks pass.
title: Auto-merge
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-
-> - **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409530) to **Auto-merge** in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `auto_merge_labels_mr_widget`. Enabled by default.
-> - Renamed auto-merge feature [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120922) in GitLab 16.0. Feature flag `auto_merge_labels_mr_widget` removed.
-> - Enhanced auto-merge features [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10874) in GitLab 16.5 [with two flags](../../../administration/feature_flags.md) named `merge_when_checks_pass` and `additional_merge_when_checks_ready`. Disabled by default.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/412995) the flags `merge_when_checks_pass` and `additional_merge_when_checks_ready` on GitLab.com in GitLab 17.0.
-> - [Merged](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/154366) the flag `additional_merge_when_checks_ready` with the flag `merge_when_checks_pass` in GitLab 17.1.
-> - Auto-merge for merge trains [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10874) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `merge_when_checks_pass_merge_train`. Disabled by default.
-> - Auto-merge for merge trains [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/470667) on GitLab.com in GitLab 17.2.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/412995) the flag `merge_when_checks_pass` on GitLab Self-Managed by default in GitLab 17.4.
-> - Auto-merge for merge trains [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174357) in GitLab 17.7. Feature flag `merge_when_checks_pass_merge_train` removed.
-> - Auto-merge [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/412995) in GitLab 17.7. Feature flag `merge_when_checks_pass` removed.
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409530) to **Auto-merge** in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `auto_merge_labels_mr_widget`. Enabled by default.
+- Renamed auto-merge feature [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120922) in GitLab 16.0. Feature flag `auto_merge_labels_mr_widget` removed.
+- Enhanced auto-merge features [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10874) in GitLab 16.5 [with two flags](../../../administration/feature_flags.md) named `merge_when_checks_pass` and `additional_merge_when_checks_ready`. Disabled by default.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/412995) the flags `merge_when_checks_pass` and `additional_merge_when_checks_ready` on GitLab.com in GitLab 17.0.
+- [Merged](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/154366) the flag `additional_merge_when_checks_ready` with the flag `merge_when_checks_pass` in GitLab 17.1.
+- Auto-merge for merge trains [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10874) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `merge_when_checks_pass_merge_train`. Disabled by default.
+- Auto-merge for merge trains [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/470667) on GitLab.com in GitLab 17.2.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/412995) the flag `merge_when_checks_pass` on GitLab Self-Managed by default in GitLab 17.4.
+- Auto-merge for merge trains [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/174357) in GitLab 17.7. Feature flag `merge_when_checks_pass_merge_train` removed.
+- Auto-merge [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/412995) in GitLab 17.7. Feature flag `merge_when_checks_pass` removed.
+
+{{< /history >}}
If the content of a merge request is ready to merge,
you can select **Set to auto-merge**. The merge request auto-merges when all required checks complete
@@ -171,7 +178,11 @@ To change this behavior:
## Prevent merge before a specific date
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14380) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14380) in GitLab 17.6.
+
+{{< /history >}}
If your merge request should not merge before a specific date and time, set a **Merge after** date.
This value sets when the merge (or merge train) can start. The exact time of merge can vary,
diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md
index 135fe6865f052ffebeacd7fddf448601b946c18a..78625ccd6583788e60a4e92ec8abe3e93e567f1b 100644
--- a/doc/user/project/merge_requests/changes.md
+++ b/doc/user/project/merge_requests/changes.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Understand how to read the changes proposed in a merge request."
+description: Understand how to read the changes proposed in a merge request.
title: Changes in merge requests
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A [merge request](_index.md) proposes a set of changes to files in a branch in your repository. GitLab
shows these changes as a _diff_ (difference) between the current state and the proposed
@@ -24,20 +27,20 @@ This example shows changes to a text file. In the default syntax highlighting th
The header for each file in the diff contains:
-- **Hide file contents** (**{chevron-down}**) to hide all changes to this file.
+- **Hide file contents** ({{< icon name="chevron-down" >}}) to hide all changes to this file.
- **Path**: The full path to this file. To copy this path, select
- **Copy file path** (**{copy-to-clipboard}**).
+ **Copy file path** ({{< icon name="copy-to-clipboard" >}}).
- **Lines changed**: The number of lines added and deleted in this file, in the format `+2 -2`.
- **Viewed**: Select this checkbox to [mark the file as viewed](#mark-files-as-viewed)
until it changes again.
-- **Comment on this file** (**{comment}**) to leave a general comment on the file, without
+- **Comment on this file** ({{< icon name="comment" >}}) to leave a general comment on the file, without
pinning the comment to a specific line.
-- **Options**: Select (**{ellipsis_v}**) to display more file viewing options.
+- **Options**: Select ({{< icon name="ellipsis_v" >}}) to display more file viewing options.
The diff also includes navigation and comment aids to the left of the file, in the gutter:
-- **Show more context**: Select **Previous 20 lines** (**{expand-up}**) to display
- the previous 20 unchanged lines, or **Next 20 lines** (**{expand-down}**) to
+- **Show more context**: Select **Previous 20 lines** ({{< icon name="expand-up" >}}) to display
+ the previous 20 unchanged lines, or **Next 20 lines** ({{< icon name="expand-down" >}}) to
show the next 20 unchanged lines.
- **Line numbers** are shown in two columns. Previous line numbers are shown on
the left, and proposed line numbers on the right. To interact with a line:
@@ -53,10 +56,10 @@ Use the **file browser** to view a list of files changed in a merge request:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests** and find your merge request.
1. Below the merge request title, select **Changes**.
-1. Select **Show file browser** (**{file-tree}**) or press <kbd>F</kbd> to show
+1. Select **Show file browser** ({{< icon name="file-tree" >}}) or press <kbd>F</kbd> to show
the file tree.
- - For a tree view that shows nesting, select **Tree view** (**{file-tree}**).
- - For a file list without nesting, select **List view** (**{list-bulleted}**).
+ - For a tree view that shows nesting, select **Tree view** ({{< icon name="file-tree" >}}).
+ - For a file list without nesting, select **List view** ({{< icon name="list-bulleted" >}}).
## Show all changes in a merge request
@@ -66,7 +69,7 @@ To view the diff of changes included in a merge request:
1. Select **Code > Merge requests** and find your merge request.
1. Below the merge request title, select **Changes**.
1. If the merge request changes many files, you can jump directly to a specific file:
- 1. Select **Show file browser** (**{file-tree}**) or press <kbd>F</kbd> to show the file tree.
+ 1. Select **Show file browser** ({{< icon name="file-tree" >}}) or press <kbd>F</kbd> to show the file tree.
1. Select the file you want to view.
1. To hide the file browser, select **Show file browser** or press <kbd>F</kbd> again.
@@ -75,12 +78,19 @@ GitLab collapses files with many changes to improve performance, and displays th
### Show a linked file first
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387246) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `pinned_file`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162503) in GitLab 17.4. Feature flag `pinned_file` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387246) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `pinned_file`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162503) in GitLab 17.4. Feature flag `pinned_file` removed.
+
+{{< /history >}}
When you share a merge request link with a team member, you might want to show a specific file
first in the list of changed files. To copy a merge request link that shows your desired file first:
@@ -90,19 +100,26 @@ first in the list of changed files. To copy a merge request link that shows your
1. Below the merge request title, select **Changes**.
1. Find the file you want to show first. Right-click the name of the file to copy the link to it.
1. When you visit that link, your chosen file is shown at the top of the list. The file browser
- shows a link icon (**{link}**) next to the file name:
+ shows a link icon ({{< icon name="link" >}}) next to the file name:
## Collapse generated files
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140180) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `collapse_generated_diff_files`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145100) in GitLab 16.10.
-> - `generated_file` [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148478) in GitLab 16.11. Feature flag `collapse_generated_diff_files` removed.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/140180) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `collapse_generated_diff_files`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145100) in GitLab 16.10.
+- `generated_file` [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148478) in GitLab 16.11. Feature flag `collapse_generated_diff_files` removed.
+
+{{< /history >}}
To help reviewers focus on the files needed to perform a code review, GitLab collapses
several common types of generated files. GitLab collapses these files by default, because
@@ -159,31 +176,37 @@ For larger merge requests, you can review one file at a time. You can change thi
setting in your user preferences, or when you review a merge request. If you change this
setting in a merge request, it updates your user settings as well.
-::Tabs
+{{< tabs >}}
-:::TabTitle In a merge request
+{{< tab title="In a merge request" >}}
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests** and find your merge request.
1. Below the merge request title, select **Changes**.
-1. Select **Preferences** (**{preferences}**).
+
+1. Select **Preferences** ({{< icon name="preferences" >}}).
+
1. Select or clear **Show one file at a time**.
-:::TabTitle In your user preferences
+{{< /tab >}}
+
+{{< tab title="In your user preferences" >}}
1. On the left sidebar, select your avatar.
1. Select **Preferences**.
1. Scroll to the **Behavior** section and select the **Show one file at a time on merge request's Changes tab** checkbox.
1. Select **Save changes**.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To select another file to view when this setting is enabled, either:
- Scroll to the end of the file and select either **Prev** or **Next**.
- If [keyboard shortcuts are enabled](../../shortcuts.md#enable-keyboard-shortcuts),
press <kbd>[</kbd>, <kbd>]</kbd>, <kbd>k</kbd>, or <kbd>j</kbd>.
-- Select **Show file browser** (**{file-tree}**) and select another file to view.
+- Select **Show file browser** ({{< icon name="file-tree" >}}) and select another file to view.
## Compare changes
@@ -200,31 +223,42 @@ To change how a merge request shows changed lines:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests** and find your merge request.
1. Below the title, select **Changes**.
-1. Select **Preferences** (**{preferences}**). Select either **Side-by-side** or **Inline**.
+1. Select **Preferences** ({{< icon name="preferences" >}}). Select either **Side-by-side** or **Inline**.
This example shows how GitLab renders the same change in both inline and side-by-side mode:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle Inline changes
+ {{< tab title="Inline changes" >}}
- :::TabTitle Side-by-side changes
+ {{< /tab >}}
+
+ {{< tab title="Side-by-side changes" >}}
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
## Explain code in a merge request
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced in GitLab 15.11 as an [experiment](../../../policy/development_stages_support.md#experiment) on GitLab.com.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) in GitLab 16.8.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - Introduced in GitLab 15.11 as an [experiment](../../../policy/development_stages_support.md#experiment) on GitLab.com.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) in GitLab 16.8.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+{{< /history >}}
If you spend a lot of time trying to understand code that others have created, or
you struggle to understand code written in a language you are not familiar with,
@@ -241,12 +275,12 @@ To explain the code in a merge request:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests**, then select your merge request.
1. Select **Changes**.
-1. On the file you would like explained, select the three dots (**{ellipsis_v}**) and select **View File @ $SHA**.
+1. On the file you would like explained, select the three dots ({{< icon name="ellipsis_v" >}}) and select **View File @ $SHA**.
A separate browser tab opens and shows the full file with the latest changes.
1. On the new tab, select the lines you want to have explained.
-1. On the left side, select the question mark (**{question}**). You might have to scroll to the first line of your selection to view it.
+1. On the left side, select the question mark ({{< icon name="question" >}}). You might have to scroll to the first line of your selection to view it.
@@ -269,7 +303,7 @@ When reviewing code changes, you can hide inline comments:
1. Select **Code > Merge requests** and find your merge request.
1. Below the title, select **Changes**.
1. Scroll to the file that contains the comments you want to hide.
-1. Scroll to the line the comment is attached to, and select **Collapse** (**{collapse}**):
+1. Scroll to the line the comment is attached to, and select **Collapse** ({{< icon name="collapse" >}}):
To expand inline comments and show them again:
@@ -289,7 +323,7 @@ a merge request. You can choose to hide or show whitespace changes:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests** and find your merge request.
1. Below the title, select **Changes**.
-1. Before the list of changed files, select **Preferences** (**{preferences}**).
+1. Before the list of changed files, select **Preferences** ({{< icon name="preferences" >}}).
1. Select or clear **Show whitespace changes**:
@@ -311,8 +345,12 @@ Files marked as viewed are not shown to you again unless either:
## Show merge request conflicts in diff
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276918) in GitLab 15.7.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/276918) in GitLab 15.8. Feature flag `display_merge_conflicts_in_diff` removed.
+{{< history >}}
+
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276918) in GitLab 15.7.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/276918) in GitLab 15.8. Feature flag `display_merge_conflicts_in_diff` removed.
+
+{{< /history >}}
To avoid displaying changes already on target branch, we compare the merge request's
source branch with the `HEAD` of the target branch.
@@ -324,9 +362,12 @@ per conflicted file on the merge request diff:
## Show scanner findings in diff
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can show scanner findings in the diff. For details, see:
@@ -335,8 +376,12 @@ You can show scanner findings in the diff. For details, see:
## Add a comment to a merge request file
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123515) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `comment_on_files`. Enabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125130) in GitLab 16.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123515) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `comment_on_files`. Enabled by default.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125130) in GitLab 16.2.
+
+{{< /history >}}
You can add comments to a merge request diff file. These comments persist across
rebases and file changes.
@@ -346,7 +391,7 @@ To add a comment to a merge request file:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests** and find your merge request.
1. Select **Changes**.
-1. In the header for the file you want to comment on, select **Comment** (**{comment}**).
+1. In the header for the file you want to comment on, select **Comment** ({{< icon name="comment" >}}).
## Add a comment to an image
diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md
index 30584fa84f6f0424540bf255163dda7d32a8419c..607c66fe5f13eea1c7d9fae395323a53725f0cf5 100644
--- a/doc/user/project/merge_requests/cherry_pick_changes.md
+++ b/doc/user/project/merge_requests/cherry_pick_changes.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Cherry-pick a Git commit when you want to add a single commit from one branch to another."
+description: Cherry-pick a Git commit when you want to add a single commit from one branch to another.
title: Cherry-pick changes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In Git, *cherry-picking* is taking a single commit from one branch and adding it
as the latest commit on another branch. The rest of the commits in the source branch
@@ -107,7 +110,7 @@ when you view that file in your project's Git repository:
## View system notes for cherry-picked commits
When you cherry-pick a merge commit in the GitLab UI or API, GitLab adds a [system note](../system_notes.md)
-to the related merge request thread. The format is **{cherry-pick-commit}**
+to the related merge request thread. The format is {{< icon name="cherry-pick-commit" >}}
`[USER]` **picked the changes into the branch** `[BRANCHNAME]` with commit** `[SHA]` `[DATE]`:
diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md
index fff6fc0a3bc4b84b7fff69b59d5603fd4181cec4..6b3b3ba310a7b7bb18e0479b70bccfbb6c52e5ae 100644
--- a/doc/user/project/merge_requests/commit_templates.md
+++ b/doc/user/project/merge_requests/commit_templates.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Use commit message templates to ensure commits to your GitLab project contain all necessary information and are formatted correctly."
+description: Use commit message templates to ensure commits to your GitLab project contain all necessary information and are formatted correctly.
title: Commit message templates
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab uses commit templates to create default messages for specific types of
commits. These templates encourage commit messages to follow a particular format,
@@ -68,10 +71,14 @@ GitLab creates a squash commit message with this template:
## Supported variables in commit templates
-> - `reviewed_by` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) in GitLab 15.7.
-> - `local_reference` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199823) in GitLab 16.1.
-> - `source_project_id` variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128553) in GitLab 16.3.
-> - `merge_request_author` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152510) in GitLab 17.1.
+{{< history >}}
+
+- `reviewed_by` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) in GitLab 15.7.
+- `local_reference` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199823) in GitLab 16.1.
+- `source_project_id` variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128553) in GitLab 16.3.
+- `merge_request_author` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/152510) in GitLab 17.1.
+
+{{< /history >}}
Commit message templates support these variables:
diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md
index 6052427b7899753e5b1626cbcf3be06b11f5596d..37d03a5c1ee552dc8a20efcfffb5ed889a4bc68e 100644
--- a/doc/user/project/merge_requests/commits.md
+++ b/doc/user/project/merge_requests/commits.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Understand how to read the display of commits in a merge request."
+description: Understand how to read the display of commits in a merge request.
title: Commits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A commit records and sends the source code changes to the [repository](../repository/_index.md).
For more information, see [Recording Changes to the Repository](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository).
@@ -72,7 +75,7 @@ To see the commits included in a merge request:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests**, then select your merge request.
1. To show a list of the commits in the merge request, newest first, select **Commits** .
- To read more about the commit, select **Toggle commit description** (**{ellipsis_h}**)
+ To read more about the commit, select **Toggle commit description** ({{< icon name="ellipsis_h" >}})
on any commit.
1. To view the changes in the commit, select the title of the commit link.
1. To view other commits in the merge request, either:
@@ -108,10 +111,13 @@ the [API](../../../api/merge_request_context_commits.md).
### Add a comment to a commit
-WARNING:
+{{< alert type="warning" >}}
+
Threads created this way are lost if the commit ID changes after a
force push.
+{{< /alert >}}
+
To add discussion to a specific commit:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -119,7 +125,7 @@ To add discussion to a specific commit:
1. Below the commits, in the **Comment** field, enter a comment.
1. Save your comment as either a standalone comment, or a thread:
- To add a comment, select **Comment**.
- - To start a thread, select the down arrow (**{chevron-down}**), then select **Start thread**.
+ - To start a thread, select the down arrow ({{< icon name="chevron-down" >}}), then select **Start thread**.
### View diffs between commits
@@ -128,7 +134,7 @@ To view the changes between previously merged commits:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests**, then select your merge request.
1. Select **Changes**.
-1. By **Compare** (**{file-tree}**), select the commits to compare:
+1. By **Compare** ({{< icon name="file-tree" >}}), select the commits to compare:
diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md
index ad4a9643cbc0b5362836e58b19685e22bb722a54..110964e474d1020ac7b7404ebb1f9d9e4f1e7caf 100644
--- a/doc/user/project/merge_requests/confidential.md
+++ b/doc/user/project/merge_requests/confidential.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "How to create a merge request for a confidential issue without leaking information publicly."
+description: How to create a merge request for a confidential issue without leaking information publicly.
title: Merge requests for confidential issues
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Merge requests in a public repository are also public, even when you create a
merge request for a [confidential issue](../issues/confidential_issues.md).
@@ -34,10 +37,13 @@ Users with the Developer role for the upstream public repository inherit those u
permissions in your downstream private fork without action by you. These users can
immediately push code to branches in your private fork to help fix the confidential issue.
-WARNING:
+{{< alert type="warning" >}}
+
Your private fork might expose confidential information if you create it in a different
namespace than the upstream repository. The two namespaces might not contain the same users.
+{{< /alert >}}
+
Prerequisites:
- You have the Owner or Maintainer role for the public repository, as you need one
diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md
index 0f80c5fc2ff3a83e0e00bd5b52273075b0803fdf..5da14110793d09ca7a66019621a95b7b1ded4d54 100644
--- a/doc/user/project/merge_requests/conflicts.md
+++ b/doc/user/project/merge_requests/conflicts.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Understand merge conflicts, and learn how to fix them in Git projects."
+description: Understand merge conflicts, and learn how to fix them in Git projects.
title: Merge conflicts
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Merge conflicts occur when two branches in a merge request, the source and target,
have different changes to the same lines of code. In most cases, GitLab can merge changes together,
diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md
index 3bf70ee33bd154187c419e508ff1452635223053..b9ab454de110a57e5d9ebb41f7664313374f6b6a 100644
--- a/doc/user/project/merge_requests/creating_merge_requests.md
+++ b/doc/user/project/merge_requests/creating_merge_requests.md
@@ -2,22 +2,28 @@
stage: Create
group: Code Review
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
-description: "How to create merge requests in GitLab."
+description: How to create merge requests in GitLab.
title: Creating merge requests
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides many different ways to create a merge request, including by [using Git commands](../../../topics/git/merge.md).
-NOTE:
+{{< alert type="note" >}}
+
GitLab enforces [branch naming rules](../repository/branches/_index.md#name-your-branch)
to prevent problems, and provides
[branch naming patterns](../repository/branches/_index.md#prefix-branch-names-with-issue-numbers)
to streamline merge request creation.
+{{< /alert >}}
+
## From the merge request list
You can create a merge request from the list of merge requests.
@@ -39,9 +45,9 @@ The new branch, and later its merge request, are marked as related to this issue
After merging the merge request, the issue is closed automatically, unless
[automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing):
-::Tabs
+{{< tabs >}}
-:::TabTitle Merge request and branch
+{{< tab title="Merge request and branch" >}}
To create a branch and a merge request at the same time:
@@ -55,7 +61,9 @@ To create a branch and a merge request at the same time:
1. Select a source branch or tag.
1. Select **Create merge request**.
-:::TabTitle Branch only
+{{< /tab >}}
+
+{{< tab title="Branch only" >}}
To create only a branch directly from an issue:
@@ -69,7 +77,9 @@ To create only a branch directly from an issue:
1. Select a source branch or tag.
1. Select **Create branch**.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
If your Git repository is empty, GitLab:
@@ -91,7 +101,11 @@ when the merge request merges.
## From a task
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/477785) in GitLab 17.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/477785) in GitLab 17.8.
+
+{{< /history >}}
If your team breaks issues into [tasks](../../tasks.md), you can create a branch directly from the task to speed the process up.
The new branch, and later its merge request, are marked as related to this task.
@@ -102,9 +116,9 @@ Prerequisites:
- You must have at least a Developer role for the project containing the task.
-::Tabs
+{{< tabs >}}
-:::TabTitle Merge request and branch
+{{< tab title="Merge request and branch" >}}
To create a branch and a merge request at the same time:
@@ -119,7 +133,9 @@ To create a branch and a merge request at the same time:
1. Select a source branch or tag.
1. Select **Create merge request**.
-:::TabTitle Branch only
+{{< /tab >}}
+
+{{< tab title="Branch only" >}}
To create only a branch directly from a task:
@@ -134,7 +150,9 @@ To create only a branch directly from a task:
1. Select a source branch or tag.
1. Select **Create branch**.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
If your Git repository is empty, GitLab:
@@ -191,10 +209,13 @@ You can create a merge request from your fork to contribute back to the main pro
- NOTE:
- If your fork's visibility is more restricted than the parent repository, the target branch defaults
+ {{< alert type="note" >}}
+
+If your fork's visibility is more restricted than the parent repository, the target branch defaults
to your fork's default branch. This prevents potential exposure of private information in your fork.
+ {{< /alert >}}
+
1. Select **Compare branches and continue**.
1. Select **Create merge request**. The merge request is created in the target repository,
not your fork.
diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md
index c672bbd4c6fef07c3e0f3fca1362917ef21905fe..f71e1c59a00f37c94a615aa839f523aeb815fdab 100644
--- a/doc/user/project/merge_requests/csv_export.md
+++ b/doc/user/project/merge_requests/csv_export.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Export merge requests to CSV
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Export all the data collected from a project's merge requests into a comma-separated values (CSV) file.
@@ -17,7 +20,7 @@ To export merge requests to a CSV file:
1. Select **Code > Merge requests**.
1. Add any searches or filters. This can help you keep the size of the CSV file under the 15 MB limit. The limit ensures
the file can be emailed to a variety of email providers.
-1. Select **Actions** (**{ellipsis_v}**) **> Export as CSV**.
+1. Select **Actions** ({{< icon name="ellipsis_v" >}}) **> Export as CSV**.
1. Confirm the correct number of merge requests are to be exported.
1. Select **Export merge requests**.
diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md
index fcc8c4650b1101acc5cdc5aa41dc93d371623851..7aa4417f2a76534937af45262d2e06b065f7bb62 100644
--- a/doc/user/project/merge_requests/dependencies.md
+++ b/doc/user/project/merge_requests/dependencies.md
@@ -2,16 +2,23 @@
stage: Create
group: Code Review
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
-description: "Set a merge request dependency to control the merge order of merge requests with related or dependent content."
+description: Set a merge request dependency to control the merge order of merge requests with related or dependent content.
title: Merge request dependencies
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Support for complex merge dependencies [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `remove_mr_blocking_constraints`. Disabled by default.
-> - Support for complex merge dependencies [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136775) in GitLab 16.7. Feature flag `remove_mr_blocking_constraints` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Support for complex merge dependencies [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `remove_mr_blocking_constraints`. Disabled by default.
+- Support for complex merge dependencies [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136775) in GitLab 16.7. Feature flag `remove_mr_blocking_constraints` removed.
+
+{{< /history >}}
A single feature can span several merge requests, spread out across multiple projects,
and the order in which the work merges can be significant. Use merge request dependencies
@@ -78,9 +85,12 @@ graph LR;
Nested dependencies do not display in the GitLab UI, but UI support is
proposed in [epic 5308](https://gitlab.com/groups/gitlab-org/-/epics/5308).
-NOTE:
+{{< alert type="note" >}}
+
A merge request cannot depend on itself (self-referential), but it's possible to create circular dependencies.
+{{< /alert >}}
+
## View dependencies for a merge request
If a merge request is dependent on another, the merge request reports section shows
@@ -156,9 +166,13 @@ Prerequisites:
1. Scroll to **Merge request dependencies** and select **Remove** next to the reference
for each dependency you want to remove.
- NOTE:
+ {{< alert type="note" >}}
+
Merge request dependencies you do not have permission to view are shown as
**1 inaccessible merge request**. You can still remove the dependency.
+
+ {{< /alert >}}
+
1. Select **Save changes**.
## Troubleshooting
diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md
index 263b9b11f35268c8abd6eaa126afc17da1cd8f40..df77757b293e7b24bcf5f2b9bff949b56b7f16eb 100644
--- a/doc/user/project/merge_requests/drafts.md
+++ b/doc/user/project/merge_requests/drafts.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Prevent an incomplete merge request from merging until it's ready by setting it as a draft."
+description: Prevent an incomplete merge request from merging until it's ready by setting it as a draft.
title: Draft merge requests
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If a merge request isn't ready to merge, you can block it from merging until you
[mark it as ready](#mark-merge-requests-as-ready). Merge requests marked as **Draft**
@@ -18,13 +21,17 @@ cannot merge until you remove the **Draft** flag, even if they meet all other me
## Mark merge requests as drafts
-> - `/draft` quick action as a toggle [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108073) the draft status to use a checkbox in GitLab 15.8.
+{{< history >}}
+
+- `/draft` quick action as a toggle [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108073) the draft status to use a checkbox in GitLab 15.8.
+
+{{< /history >}}
You can flag a merge request as a draft in several ways:
- **Viewing a merge request**: In the upper-right corner of the merge request,
- select **Merge request actions** (**{ellipsis_v}**), then **Mark as draft**.
+ select **Merge request actions** ({{< icon name="ellipsis_v" >}}), then **Mark as draft**.
- **Creating or editing a merge request**: Add `[Draft]`, `Draft:` or `(Draft)` to
the beginning of the merge request's title, or select **Mark as draft**
below the **Title** field.
diff --git a/doc/user/project/merge_requests/duo_in_merge_requests.md b/doc/user/project/merge_requests/duo_in_merge_requests.md
index cabc5b344aac6d00ecb1ef88e8420bf57a657fa0..b6b438446aa787d67952a53dd3c6fdf853abda95 100644
--- a/doc/user/project/merge_requests/duo_in_merge_requests.md
+++ b/doc/user/project/merge_requests/duo_in_merge_requests.md
@@ -2,39 +2,44 @@
stage: Create
group: Code Review
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
-description: "Use AI-assisted features for relevant information about a merge request."
+description: Use AI-assisted features for relevant information about a merge request.
title: GitLab Duo in merge requests
---
-DETAILS:
-**Tier:** Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com
+{{< details >}}
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the
-sole discretion of GitLab Inc.
+- Tier: Ultimate with GitLab Duo Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< alert type="disclaimer" />}}
GitLab Duo is designed to provide contextually relevant information during the lifecycle of a merge request.
## Generate a description by summarizing code changes
-DETAILS:
-**Status:** Beta
-**LLM:** Vertex AI Codey [`text-bison`](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/text-bison)
+{{< details >}}
+
+- Status: Beta
+- LLM: Vertex AI Codey [`text-bison`](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/text-bison)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10401) in GitLab 16.2 as an [experiment](../../../policy/development_stages_support.md#experiment).
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/429882) to beta in GitLab 16.10.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10401) in GitLab 16.2 as an [experiment](../../../policy/development_stages_support.md#experiment).
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/429882) to beta in GitLab 16.10.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+{{< /history >}}
When you create or edit a merge request, use GitLab Duo Merge Request Summary
to create a merge request description.
1. [Create a new merge request](creating_merge_requests.md).
1. In the **Description** field, put your cursor where you want to insert the description.
-1. On the toolbar above the text area, select **Summarize code changes** (**{tanuki-ai}**).
+1. On the toolbar above the text area, select **Summarize code changes** ({{< icon name="tanuki-ai" >}}).
@@ -46,29 +51,45 @@ Provide feedback on this feature in [issue 443236](https://gitlab.com/gitlab-org
## Have GitLab Duo review your code
-DETAILS:
-**Status:** Experiment
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14825) in GitLab 17.5 as an [experiment](../../../policy/development_stages_support.md#experiment) behind two feature flags named [`ai_review_merge_request`](https://gitlab.com/gitlab-org/gitlab/-/issues/456106) and [`duo_code_review_chat`](https://gitlab.com/gitlab-org/gitlab/-/issues/508632), both disabled by default.
-> - Feature flags [`ai_review_merge_request`](https://gitlab.com/gitlab-org/gitlab/-/issues/456106) and [`duo_code_review_chat`](https://gitlab.com/gitlab-org/gitlab/-/issues/508632) enabled for GitLab.com in 17.10.
+- Status: Experiment
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14825) in GitLab 17.5 as an [experiment](../../../policy/development_stages_support.md#experiment) behind two feature flags named [`ai_review_merge_request`](https://gitlab.com/gitlab-org/gitlab/-/issues/456106) and [`duo_code_review_chat`](https://gitlab.com/gitlab-org/gitlab/-/issues/508632), both disabled by default.
+- Feature flags [`ai_review_merge_request`](https://gitlab.com/gitlab-org/gitlab/-/issues/456106) and [`duo_code_review_chat`](https://gitlab.com/gitlab-org/gitlab/-/issues/508632) enabled for GitLab.com in 17.10.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by two feature flags.
For more information, see the history.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
This feature is considered [experimental](../../../policy/development_stages_support.md) and breaking changes may still be made to this feature.
+{{< /alert >}}
+
When your merge request is ready to be reviewed, use GitLab Duo Code Review to perform an initial review:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests** and find your merge request.
1. In a comment box, enter the quick action `/assign_reviewer @GitLabDuo`, or assign GitLab Duo as reviewer.
-NOTE:
+{{< alert type="note" >}}
+
Provide feedback on this feature in issue [517386](https://gitlab.com/gitlab-org/gitlab/-/issues/517386).
+{{< /alert >}}
+
**Data usage**: When you use this feature, the following data is sent to the large language model:
- Contents of the file
@@ -82,11 +103,18 @@ Interactions with GitLab Duo can help to improve the suggestions and feedback as
## Summarize a code review
-DETAILS:
-**Status:** Experiment
-**LLM:** Vertex AI Codey [`text-bison`](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/text-bison)
+{{< details >}}
+
+- Status: Experiment
+- LLM: Vertex AI Codey [`text-bison`](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/text-bison)
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10466) in GitLab 16.0 as an [experiment](../../../policy/development_stages_support.md#experiment).
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10466) in GitLab 16.0 as an [experiment](../../../policy/development_stages_support.md#experiment).
+
+{{< /history >}}
When you've completed your review of a merge request and are ready to [submit your review](reviews/_index.md#submit-a-review), use GitLab Duo Code Review Summary to generate a summary of your comments.
@@ -105,13 +133,20 @@ Provide feedback on this experimental feature in [issue 408991](https://gitlab.c
## Generate a merge commit message
-DETAILS:
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
+
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10453) in GitLab 16.2 as an [experiment](../../../policy/development_stages_support.md#experiment) [with a flag](../../../administration/feature_flags.md) named `generate_commit_message_flag`. Disabled by default.
+- Feature flag `generate_commit_message_flag` [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158339) in GitLab 17.2.
+- Feature flag `generate_commit_message_flag` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173262) in GitLab 17.7.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10453) in GitLab 16.2 as an [experiment](../../../policy/development_stages_support.md#experiment) [with a flag](../../../administration/feature_flags.md) named `generate_commit_message_flag`. Disabled by default.
-> - Feature flag `generate_commit_message_flag` [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158339) in GitLab 17.2.
-> - Feature flag `generate_commit_message_flag` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173262) in GitLab 17.7.
+{{< /history >}}
When preparing to merge your merge request, edit the proposed merge commit message
by using GitLab Duo Merge Commit Message Generation.
diff --git a/doc/user/project/merge_requests/manage.md b/doc/user/project/merge_requests/manage.md
index 6cdc2d23f43d72ae383009f350963201cfbf10a1..f9aa5e30dae35aa49016ac2c60a3b0b308a5ec2f 100644
--- a/doc/user/project/merge_requests/manage.md
+++ b/doc/user/project/merge_requests/manage.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Review
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
-description: "Use merge request reviews to discuss and improve code before it is merged into your project."
+description: Use merge request reviews to discuss and improve code before it is merged into your project.
title: Manage merge requests
---
@@ -24,11 +24,14 @@ To delete a merge request:
1. Select **Edit**.
1. Scroll to the bottom of the page, and select **Delete merge request**.
-NOTE:
+{{< alert type="note" >}}
+
Deleting a merge request does not completely erase all data.
Some information persists to maintain project history and to support recovery processes.
For more information, see [Handle sensitive information](../../../topics/git/undo.md#handle-sensitive-information).
+{{< /alert >}}
+
## Bulk edit merge requests in a project
These attributes are editable when bulk editing merge requests:
@@ -54,9 +57,12 @@ To do this:
## Bulk edit merge requests in a group
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
These attributes are editable when you bulk edit merge requests for a group:
diff --git a/doc/user/project/merge_requests/merge_request_troubleshooting.md b/doc/user/project/merge_requests/merge_request_troubleshooting.md
index 617325a5904ef05d14f8b474327c856f07a0b697..02357b039a19d5634d8881edb530c5f54c2801f8 100644
--- a/doc/user/project/merge_requests/merge_request_troubleshooting.md
+++ b/doc/user/project/merge_requests/merge_request_troubleshooting.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Troubleshooting help for merge requests."
+description: Troubleshooting help for merge requests.
title: Merge request troubleshooting
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When working with merge requests, you might encounter the following issues.
@@ -35,19 +38,25 @@ merge request again.
## Rebase a merge request from the Rails console
-DETAILS:
-**Tier:** Free, Premium, Ultimate
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+
+{{< /details >}}
In addition to the `/rebase` [quick action](../quick_actions.md#issues-merge-requests-and-epics),
users with access to the [Rails console](../../../administration/operations/rails_console.md)
can rebase a merge request from the Rails console. Replace `<username>`,
`<namespace/project>`, and `<iid>` with appropriate values:
-WARNING:
+{{< alert type="warning" >}}
+
Any command that changes data directly could be damaging if not run correctly,
or under the right conditions. We highly recommend running them in a test environment
with a backup of the instance ready to be restored, just in case.
+{{< /alert >}}
+
```ruby
u = User.find_by_username('<username>')
p = Project.find_by_full_path('<namespace/project>')
@@ -57,20 +66,26 @@ MergeRequests::RebaseService.new(project: m.target_project, current_user: u).exe
## Fix incorrect merge request status
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If a merge request remains **Open** after its changes are merged,
users with access to the [Rails console](../../../administration/operations/rails_console.md)
can correct the merge request's status. Replace `<username>`, `<namespace/project>`,
and `<iid>` with appropriate values:
-WARNING:
+{{< alert type="warning" >}}
+
Any command that changes data directly could be damaging if not run correctly,
or under the right conditions. We highly recommend running them in a test environment
with a backup of the instance ready to be restored, just in case.
+{{< /alert >}}
+
```ruby
u = User.find_by_username('<username>')
p = Project.find_by_full_path('<namespace/project>')
@@ -83,16 +98,22 @@ merge request to display an incorrect message: `merged into <branch-name>`.
## Close a merge request from the Rails console
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If closing a merge request doesn't work through the UI or API, try closing it in a
[Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session):
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
u = User.find_by_username('<username>')
p = Project.find_by_full_path('<namespace/project>')
@@ -102,18 +123,24 @@ MergeRequests::CloseService.new(project: p, current_user: u).execute(m)
## Delete a merge request from the Rails console
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If deleting a merge request doesn't work through the UI or API, try deleting it in a
[Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session):
-WARNING:
+{{< alert type="warning" >}}
+
Any command that changes data directly could be damaging if not run correctly,
or under the right conditions. We highly recommend running them in a test environment
with a backup of the instance ready to be restored, just in case.
+{{< /alert >}}
+
```ruby
u = User.find_by_username('<username>')
p = Project.find_by_full_path('<namespace/project>')
@@ -157,8 +184,12 @@ greater than 1000. The cached value is rounded to thousands (or millions) and up
## Check out merge requests locally through the `head` ref
-> - Deleting `head` refs 14 days after a merge request closes or merges [enabled on GitLab Self-Managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130098) in GitLab 16.4.
-> - Deleting `head` refs 14 days after a merge request closes or merges [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/336070) in GitLab 16.6. Feature flag `merge_request_refs_cleanup` removed.
+{{< history >}}
+
+- Deleting `head` refs 14 days after a merge request closes or merges [enabled on GitLab Self-Managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130098) in GitLab 16.4.
+- Deleting `head` refs 14 days after a merge request closes or merges [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/336070) in GitLab 16.6. Feature flag `merge_request_refs_cleanup` removed.
+
+{{< /history >}}
A merge request contains all the history from a repository, plus the additional
commits added to the branch associated with the merge request. Here's a few
diff --git a/doc/user/project/merge_requests/methods/_index.md b/doc/user/project/merge_requests/methods/_index.md
index 7f671baeecc0dfefd9d7a3082fc616daa810962b..ed644ee10b48a67669934060e9feb650de5e8297 100644
--- a/doc/user/project/merge_requests/methods/_index.md
+++ b/doc/user/project/merge_requests/methods/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Your project's merge method determines whether to squash commits before merging, and if merge commits are created when work merges."
+description: Your project's merge method determines whether to squash commits before merging, and if merge commits are created when work merges.
title: Merge methods
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The merge method you select for your project determines how the changes in your
merge requests are merged into an existing branch.
@@ -216,7 +219,11 @@ considered equivalent to rebasing.
### Rebase without CI/CD pipeline
-> - Changed to [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350262) in GitLab 15.3. Feature flag `rebase_without_ci_ui` removed.
+{{< history >}}
+
+- Changed to [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350262) in GitLab 15.3. Feature flag `rebase_without_ci_ui` removed.
+
+{{< /history >}}
To rebase a merge request's branch without triggering a CI/CD pipeline, select
**Rebase without pipeline** from the merge request reports section.
diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md
index e4c1c1297603c4547512c8a0b046756ad4640abe..47ed59c39a307b46a8ecd3c14af91b270c242e7d 100644
--- a/doc/user/project/merge_requests/revert_changes.md
+++ b/doc/user/project/merge_requests/revert_changes.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "How to revert commits or merge requests in a GitLab project."
+description: How to revert commits or merge requests in a GitLab project.
title: Revert changes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can revert individual commits or an entire merge request in GitLab.
@@ -102,20 +105,27 @@ the command line, see [Revert and undo changes with Git](../../../topics/git/und
## Redact text from repository
-> - Introduced in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `rewrite_history_ui`. Disabled by default. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/450701`
-> - Enabled on GitLab.com in confidential issue `https://gitlab.com/gitlab-org/gitlab/-/issues/462999` in GitLab 17.2.
-> - Enabled on GitLab Self-Managed and GitLab Dedicated in confidential issue `https://gitlab.com/gitlab-org/gitlab/-/issues/462999` in GitLab 17.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472018) in GitLab 17.9. Feature flag `rewrite_history_ui` removed.
+{{< history >}}
+
+- Introduced in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `rewrite_history_ui`. Disabled by default. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/450701`
+- Enabled on GitLab.com in confidential issue `https://gitlab.com/gitlab-org/gitlab/-/issues/462999` in GitLab 17.2.
+- Enabled on GitLab Self-Managed and GitLab Dedicated in confidential issue `https://gitlab.com/gitlab-org/gitlab/-/issues/462999` in GitLab 17.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472018) in GitLab 17.9. Feature flag `rewrite_history_ui` removed.
+
+{{< /history >}}
Permanently delete sensitive or confidential information that was accidentally committed, ensuring
it's no longer accessible in your repository's history.
Replaces a list of strings with `***REMOVED***`.
-WARNING:
+{{< alert type="warning" >}}
+
**This action is irreversible.**
After rewriting history and running housekeeping, the changes are permanent.
Be aware of the following impacts when redacting text from your repository:
+{{< /alert >}}
+
- Open merge requests might fail to merge and require manual rebasing.
- Existing local clones are incompatible with the updated repository and must be re-cloned.
- Pipelines referencing old commit SHAs might break and require reconfiguration.
diff --git a/doc/user/project/merge_requests/reviews/_index.md b/doc/user/project/merge_requests/reviews/_index.md
index 02c44851439e0b4d28e1ec8901e7aa00f9dd9d7e..3a8e6d60e06e54aed227a3f5f906dd3218511dc5 100644
--- a/doc/user/project/merge_requests/reviews/_index.md
+++ b/doc/user/project/merge_requests/reviews/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Use merge request reviews to discuss and improve code before it is merged into your project."
+description: Use merge request reviews to discuss and improve code before it is merged into your project.
title: Merge request reviews
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Merge requests are the primary method of making changes to files in a
GitLab project. [Create and submit](../creating_merge_requests.md) a merge request
@@ -55,17 +58,21 @@ To do this:
To see the individual review status for each reviewer, check the right sidebar
of a merge request. Each **Reviewer** shows the status to the right of the user's name:
-- **{dash-circle}** Awaiting review from this user.
-- **{status_running}** The user's review is in progress.
-- **{check-circle}** Approved by this user.
-- **{comment-lines}** User has requested changes, and [blocked this merge request](#prevent-merge-when-you-request-changes).
+- {{< icon name="dash-circle" >}} Awaiting review from this user.
+- {{< icon name="status_running" >}} The user's review is in progress.
+- {{< icon name="check-circle" >}} Approved by this user.
+- {{< icon name="comment-lines" >}} User has requested changes, and [blocked this merge request](#prevent-merge-when-you-request-changes).
(If needed, you can [bypass this block](#prevent-merge-when-you-request-changes).)
## Request a review
-> - Enhanced reviewer drawer [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12878) in GitLab 17.5 [with a flag](../../../../administration/feature_flags.md) named `reviewer_assign_drawer`.
-> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/467205) on GitLab.com and GitLab Self-Managed in GitLab 17.5.
-> - [Feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/467205) `reviewer_assign_drawer` removed in GitLab 17.8.
+{{< history >}}
+
+- Enhanced reviewer drawer [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12878) in GitLab 17.5 [with a flag](../../../../administration/feature_flags.md) named `reviewer_assign_drawer`.
+- [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/467205) on GitLab.com and GitLab Self-Managed in GitLab 17.5.
+- [Feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/467205) `reviewer_assign_drawer` removed in GitLab 17.8.
+
+{{< /history >}}
When you've finished preparing your changes, it's time to request a review. To assign a reviewer to your merge request,
either use the `/assign_reviewer @user`
@@ -84,9 +91,12 @@ GitLab adds the merge request to the user's review requests.
### Find reviewers who fulfill approval rules
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab Premium and Ultimate help you more quickly find the best reviewers for your merge request.
Use the **Assign reviewers** drawer to filter lists of reviewers. See the Code Owners for the files
@@ -96,13 +106,13 @@ In this example, the merge request requires 3 Code Owner approvals, but has none
-1. To see optional approval rules or Code Owners, select **Optional approval rules** (**{chevron-lg-up}**) to show them.
+1. To see optional approval rules or Code Owners, select **Optional approval rules** ({{< icon name="chevron-lg-up" >}}) to show them.
1. Next to the reviewer type you need, select **Edit**:
- **Code Owners** shows only the Code Owners for that file type.
- **Approval rules** shows only users who fulfill that approval rule.
1. Select your desired reviewers. (GitLab Premium and Ultimate enable you to select multiple reviewers.)
1. Repeat for each required **Code Owner** and **Approval rule** item.
-1. When you've selected your reviewers, on the top right, select **Close** (**{close}**) to hide the drawer.
+1. When you've selected your reviewers, on the top right, select **Close** ({{< icon name="close" >}}) to hide the drawer.
### Re-request a review
@@ -114,8 +124,8 @@ To do this, either use the `/request_review @user` quick action in any text fiel
1. Select **Code > Merge requests** and find your merge request.
1. Select the title of the merge request to view it.
1. If you have collapsed the right sidebar in the merge request, select the
- **{chevron-double-lg-left}** **Expand Sidebar** to expand it.
-1. In the **Reviewers** section, select the **Re-request a review** icon (**{redo}**)
+ {{< icon name="chevron-double-lg-left" >}} **Expand Sidebar** to expand it.
+1. In the **Reviewers** section, select the **Re-request a review** icon ({{< icon name="redo" >}})
next to the reviewer's name.
GitLab creates a new [to-do item](../../../todos.md) for the reviewer, and sends
@@ -127,7 +137,7 @@ If a user has asked you to review a merge request:
1. Either:
- Press <kbd>Shift</kbd> + <kbd>r</kbd> to go to your **Review requests** page.
- - On the left sidebar, select **Merge requests** (**{merge-request}**) **> Review requests**.
+ - On the left sidebar, select **Merge requests** ({{< icon name="merge-request" >}}) **> Review requests**.
1. Find your merge request, and select the title of the merge request to view it.
1. Read the merge request description and comments to learn about the merge request.
@@ -157,8 +167,8 @@ To resolve or unresolve a thread when replying to a comment:
Pending comments display information about delayed actions. GitLab does not perform these actions until you publish the comment:
-- **{check-circle-filled}** Thread is resolved.
-- **{check-circle}** Thread stays unresolved.
+- {{< icon name="check-circle-filled" >}} Thread is resolved.
+- {{< icon name="check-circle" >}} Thread stays unresolved.
## Submit a review
@@ -185,13 +195,20 @@ When you submit your review, GitLab:
### Prevent merge when you request changes
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/430728) in GitLab 16.11 [with a flag](../../../../administration/feature_flags.md) named `mr_reviewer_requests_changes`. Disabled by default.
-> - Enabled by default [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/451211) and [GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158226) in GitLab 17.2.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/451211) in GitLab 17.3.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/430728) in GitLab 16.11 [with a flag](../../../../administration/feature_flags.md) named `mr_reviewer_requests_changes`. Disabled by default.
+- Enabled by default [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/451211) and [GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158226) in GitLab 17.2.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/451211) in GitLab 17.3.
+
+{{< /history >}}
A reviewer [requesting changes](#submit-a-review) blocks a merge request from merging.
When this happens, the merge request reports area shows the message
@@ -200,7 +217,11 @@ the reviewer who requested changes should [re-review and approve](#re-request-a-
### Remove a change request
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/480412) in GitLab 17.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/480412) in GitLab 17.8.
+
+{{< /history >}}
If you previously requested changes, you can remove your change request. You might need to do this
if both of the following are true:
@@ -232,8 +253,8 @@ another user with permission to merge the merge request can override this check:
1. The merge reports area shows `Merge with caution: Override added`. To see which check a user
- bypassed, select **Expand merge checks** (**{chevron-lg-down}**) and find the
- check that contains a warning (**{status_warning}**) icon. In this example, the
+ bypassed, select **Expand merge checks** ({{< icon name="chevron-lg-down" >}}) and find the
+ check that contains a warning ({{< icon name="status_warning" >}}) icon. In this example, the
author bypassed **The change requests must be completed or resolved**:
diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md
index acc6670d7c73f4d5406c0c77b1723ebdc0b718b8..c97b07c6b936330d06e8037ae2098e68d13c0ae5 100644
--- a/doc/user/project/merge_requests/reviews/data_usage.md
+++ b/doc/user/project/merge_requests/reviews/data_usage.md
@@ -1,6 +1,6 @@
---
-redirect_to: '_index.md'
-remove_date: '2025-02-03'
+redirect_to: _index.md
+remove_date: "2025-02-03"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md
index 106e725cfbe45464edab9e3e210394cc9b5fa493..1a0d54ea566b6d0ba8d7b9ff089ed77642fce332 100644
--- a/doc/user/project/merge_requests/reviews/suggestions.md
+++ b/doc/user/project/merge_requests/reviews/suggestions.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Suggest improvements to the code in a merge request, and commit those improvements to the merge request directly from your browser."
+description: Suggest improvements to the code in a merge request, and commit those improvements to the merge request directly from your browser.
title: Suggest changes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Reviewers can suggest code changes with a Markdown syntax in merge request diff threads.
The merge request author (or other users with the appropriate role) can apply any or
@@ -22,13 +25,13 @@ merge request, authored by the user who suggested the changes.
1. On the secondary menu, select **Changes**.
1. Find the lines of code you want to change.
- To select a single line, hover over the line number and
- select **Add a comment to this line** (**{comment}**).
+ select **Add a comment to this line** ({{< icon name="comment" >}}).
- To select more lines:
- 1. Hover over the line number, and select **Add a comment to this line** (**{comment}**):
+ 1. Hover over the line number, and select **Add a comment to this line** ({{< icon name="comment" >}}):
1. Select and drag your selection to include all desired lines. To
learn more, see [Multi-line suggestions](#multi-line-suggestions).
-1. In the comment toolbar, select **Insert suggestion** (**{doc-code}**). GitLab
+1. In the comment toolbar, select **Insert suggestion** ({{< icon name="doc-code" >}}). GitLab
inserts a pre-populated code block into your comment, like this:
````markdown
@@ -48,7 +51,11 @@ merge request, authored by the user who suggested the changes.
### Multi-line suggestions
-> - Multi-line suggestions [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172981/) in GitLab 17.7 to support rendering when the suggestion contains a code block.
+{{< history >}}
+
+- Multi-line suggestions [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/172981/) in GitLab 17.7 to support rendering when the suggestion contains a code block.
+
+{{< /history >}}
When you review a merge request diff, you can propose changes to multiple lines (up to 200)
in a single suggestion, by either:
@@ -84,9 +91,13 @@ Multi-line comments display the comment's line numbers above the body of the com
#### Using the rich text editor
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375172) in GitLab 16.2.
-> - Feature flag `content_editor_on_issues` removed in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375172) in GitLab 16.2.
+- Feature flag `content_editor_on_issues` removed in GitLab 16.5.
+
+{{< /history >}}
When you insert suggestions, use the WYSIWYG [rich text editor](../../../rich_text_editor.md) to move
up and down the source file's line numbers in the UI.
@@ -182,12 +193,15 @@ suggestions in a single commit.
1. Optional. To remove a suggestion, select **Remove from batch**.
1. After you add your desired suggestions, select **Apply suggestions**.
- WARNING:
+ {{< alert type="warning" >}}
+
If you apply a batch of suggestions containing changes from multiple authors,
the resulting commit credits you as the author. If you configure your project
to [prevent approvals from users who add commits](../approvals/settings.md#prevent-approvals-by-users-who-add-commits), you are no longer an eligible
approver for this merge request.
+ {{< /alert >}}
+
1. Optional. Provide a custom commit message for [batch suggestions](#batch-suggestions)
to describe your change. If you don't specify one, it uses
the default commit message.
diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md
index 3cba417fee74e466d2a3303f563125989bf4f024..9ee28bdb03b15a09aa96a99c0e6bd668cf0c0db6 100644
--- a/doc/user/project/merge_requests/squash_and_merge.md
+++ b/doc/user/project/merge_requests/squash_and_merge.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Understand and configure the commit squashing options available in GitLab."
+description: Understand and configure the commit squashing options available in GitLab.
title: Squash and merge
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
As you work on a feature branch, you often create small, self-contained commits. These small commits
help describe the process of building a feature, but can clutter your Git history after the feature
diff --git a/doc/user/project/merge_requests/stacked_diffs.md b/doc/user/project/merge_requests/stacked_diffs.md
index b4a398182811c399a820518edb07c04002d93549..4fb984e03e7f973b4ad7ceba704a8bd049a48daa 100644
--- a/doc/user/project/merge_requests/stacked_diffs.md
+++ b/doc/user/project/merge_requests/stacked_diffs.md
@@ -2,14 +2,17 @@
stage: Create
group: Code Review
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
-description: "Use stacked diffs to create small merge changes that build upon each other to ultimately deliver a feature."
+description: Use stacked diffs to create small merge changes that build upon each other to ultimately deliver a feature.
title: Stacked diffs
---
-DETAILS:
-**Tier:** Core, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**Status:** Experiment
+{{< details >}}
+
+- Tier: Core, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Experiment
+
+{{< /details >}}
> - Released in [v1.42.0 of the GitLab CLI](https://gitlab.com/gitlab-org/cli/-/releases/v1.42.0) as an [experiment](../../../policy/development_stages_support.md#experiment).
diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md
index 4910f45e18f2a2d8e2d14eb73452f374221473cb..b20b48ebc01431d1957bebd57df7cb1019b492ac 100644
--- a/doc/user/project/merge_requests/status_checks.md
+++ b/doc/user/project/merge_requests/status_checks.md
@@ -1,16 +1,23 @@
---
stage: Security Risk Management
group: Security Policies
-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"
+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
title: External status checks
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - `pending` status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413723) in GitLab 16.5
-> - Timeout interval of two minutes for `pending` status checks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388725) in GitLab 16.6.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- `pending` status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413723) in GitLab 16.5
+- Timeout interval of two minutes for `pending` status checks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388725) in GitLab 16.6.
+
+{{< /history >}}
Status checks are API calls to external systems that request the status of an external requirement.
@@ -33,9 +40,13 @@ see [epic 3869](https://gitlab.com/groups/gitlab-org/-/epics/3869).
## Block merges of merge requests unless all status checks have passed
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/372340) in GitLab 15.8.
-> - Enabled on GitLab Self-Managed and feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111492) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/372340) in GitLab 15.8.
+- Enabled on GitLab Self-Managed and feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111492) in GitLab 15.9.
+
+{{< /history >}}
By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail:
@@ -97,15 +108,18 @@ Filling in the form and selecting the **Add status check** button creates a new
### Update a status check service
-Within the **Status checks** sub-section, select **Edit** (**{pencil}**)
+Within the **Status checks** sub-section, select **Edit** ({{< icon name="pencil" >}})
next to the status check you want to edit.
The **Update status check** form is then shown.
-NOTE:
+{{< alert type="note" >}}
+
You cannot see or modify the value of the HMAC shared secret. To change the shared secret, delete and recreate the external status check with a new value for the shared secret.
+{{< /alert >}}
+
Changing the values in the form and selecting the **Update status check** button updates the status check.
### Form values
@@ -148,7 +162,7 @@ and ensures they come from a legitimate source.
## Delete a status check service
-Within the **Status checks** sub-section, select **Remove** (**{remove}**)
+Within the **Status checks** sub-section, select **Remove** ({{< icon name="remove" >}})
next to the status check you want to delete.
The **Remove status check?** modal is then shown.
@@ -160,14 +174,18 @@ the status check and it **is not** recoverable.
## Status checks widget
-> - UI [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91504) in GitLab 15.2.
-> - Ability to retry failed external status checks [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383200) in GitLab 15.8.
-> - Widget [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111763) to poll for updates when there are pending status checks in GitLab 15.11.
+{{< history >}}
+
+- UI [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91504) in GitLab 15.2.
+- Ability to retry failed external status checks [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383200) in GitLab 15.8.
+- Widget [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111763) to poll for updates when there are pending status checks in GitLab 15.11.
+
+{{< /history >}}
The status checks widget displays in merge requests and displays the following statuses:
-- **pending** (**{status-neutral}**), while GitLab waits for a response from an external status check.
-- **success** (**{status-success}**) or **failed** (**{status-failed}**), when GitLab receives a response from an external status check.
+- **pending** ({{< icon name="status-neutral" >}}), while GitLab waits for a response from an external status check.
+- **success** ({{< icon name="status-success" >}}) or **failed** ({{< icon name="status-failed" >}}), when GitLab receives a response from an external status check.
When there are pending status checks, the widget polls for updates every few seconds until it receives a **success** or **failed** response.
@@ -176,16 +194,19 @@ To retry a failed status check:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Merge requests** and find your merge request.
1. Scroll to the merge request reports section, and expand the dropdown list to show the list of external status checks.
-1. Select **Retry** (**{retry}**) on the failed external status check row. The status check is put back into a pending state.
+1. Select **Retry** ({{< icon name="retry" >}}) on the failed external status check row. The status check is put back into a pending state.
An organization might have a policy that does not allow merging merge requests if
external status checks do not pass. However, the details in the widget are for informational
purposes only.
-NOTE:
+{{< alert type="note" >}}
+
GitLab cannot guarantee that the external status checks are properly processed by
the related external service.
+{{< /alert >}}
+
## Troubleshooting
### Duplicate value errors
diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md
index 650d04aab72881abaf71105909b51af2dcc6d201..bf6780a417d591339659f4ce99c5f4a6977c6d11 100644
--- a/doc/user/project/merge_requests/versions.md
+++ b/doc/user/project/merge_requests/versions.md
@@ -2,23 +2,29 @@
stage: Create
group: Code Review
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
-description: "Use diff versions to compare pushes contained in a single merge request."
+description: Use diff versions to compare pushes contained in a single merge request.
title: Merge request diff versions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you create a merge request, you select two branches to compare. The differences
between the two branches are shown as a **diff** in the merge request. Each time
you push commits to a branch connected to a merge request, GitLab updates the
merge request diff to a new **diff version**.
-NOTE:
+{{< alert type="note" >}}
+
Diff versions are updated on each push, not each commit. If a push contains multiple
commits, only one new diff version is created.
+{{< /alert >}}
+
By default, GitLab compares the latest push in your source branch (`feature`)
against the most recent commit in the target branch, often `main`.
@@ -39,7 +45,7 @@ To compare diff versions:
1. Select **Code > Merge requests**.
1. Select a merge request.
1. To view the current diff version for this merge request, select **Changes**.
-1. Next to **Compare** (**{file-tree}**), select the pushes to compare. This example
+1. Next to **Compare** ({{< icon name="file-tree" >}}), select the pushes to compare. This example
compares `main` to the most recent push (latest diff version) of the branch:
diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md
index 13fa6c5fd5d7d81697a8c57027f825ac75c88270..69c71e9ea758c6a89c5f3ae7a1d0ace1f4426272 100644
--- a/doc/user/project/merge_requests/widgets.md
+++ b/doc/user/project/merge_requests/widgets.md
@@ -2,13 +2,16 @@
stage: Create
group: Code Review
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
-description: "Merge requests show the results of CI/CD pipelines and mergeability tests in a reports area."
+description: Merge requests show the results of CI/CD pipelines and mergeability tests in a reports area.
title: Merge request widgets
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The **Overview** page of a merge request displays status updates from services
that perform actions on your merge request. All subscription levels display a
@@ -28,10 +31,13 @@ If an application is successfully deployed to an
[environment](../../../ci/environments/_index.md), the deployed environment and the link to the
[review app](../../../ci/review_apps/_index.md) are both shown.
-NOTE:
+{{< alert type="note" >}}
+
When the pipeline fails in a merge request but it can still merge,
GitLab shows **Merge** in red.
+{{< /alert >}}
+
## Post-merge pipeline status
When you merge a merge request, you can see the post-merge pipeline status of
@@ -68,9 +74,12 @@ faster to preview proposed modifications.
## License compliance
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To view a list of licenses that detected for your project's dependencies,
configure [License Compliance](../../compliance/license_scanning_of_cyclonedx_files/_index.md)
@@ -80,9 +89,12 @@ for your project.
## External status checks
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you have configured [external status checks](status_checks.md) you can
see the status of these checks in merge requests
diff --git a/doc/user/project/milestones/_index.md b/doc/user/project/milestones/_index.md
index 833ea409084926224f7aafb5995f9d0abd21dfd3..18440e696e9fe6bdb355614fdcf88a4827caa137 100644
--- a/doc/user/project/milestones/_index.md
+++ b/doc/user/project/milestones/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Milestones
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal
in a certain period of time, such as a program increment or upcoming release.
@@ -121,8 +124,12 @@ The sidebar on the milestone view shows the following:
## Create a milestone
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can create a milestone either in a project or a group.
@@ -143,8 +150,12 @@ To create a milestone:
## Edit a milestone
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -155,14 +166,18 @@ To edit a milestone:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Milestones**.
1. Select a milestone's title.
-1. In the upper-right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Edit**.
+1. In the upper-right corner, select **Milestone actions** ({{< icon name="ellipsis_v" >}}) and then select **Edit**.
1. Edit the title, start date, due date, or description.
1. Select **Save changes**.
## Close a milestone
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -173,13 +188,17 @@ To close a milestone:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Milestones**.
1. Either:
- - Next to the milestone you want to close, select **Milestone actions** (**{ellipsis_v}**) > **Close**.
+ - Next to the milestone you want to close, select **Milestone actions** ({{< icon name="ellipsis_v" >}}) > **Close**.
- Select the milestone title, and then select **Close**.
## Delete a milestone
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -190,13 +209,17 @@ To delete a milestone:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Milestones**.
1. Either:
- - Next to the milestone you want to delete, select **Milestone actions** (**{ellipsis_v}**) > **Delete**.
- - Select the milestone title, and then select **Milestone actions** (**{ellipsis_v}**) > **Delete**.
+ - Next to the milestone you want to delete, select **Milestone actions** ({{< icon name="ellipsis_v" >}}) > **Delete**.
+ - Select the milestone title, and then select **Milestone actions** ({{< icon name="ellipsis_v" >}}) > **Delete**.
1. Select **Delete milestone**.
## Promote a project milestone to a group milestone
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
If you are expanding the number of projects in a group, you might want to share the same milestones
among this group's projects.
@@ -208,9 +231,12 @@ name into a single group milestone.
All issues and merge requests that were previously assigned to one of these project
milestones become assigned to the new group milestone.
-WARNING:
+{{< alert type="warning" >}}
+
This action cannot be reversed and the changes are permanent.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Planner role for the group.
@@ -220,8 +246,8 @@ To promote a project milestone:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Milestones**.
1. Either:
- - Next to the milestone you want to promote, select **Milestone actions** (**{ellipsis_v}**) > **Promote**.
- - Select the milestone title, and then select **Milestone actions** (**{ellipsis_v}**) > **Promote**.
+ - Next to the milestone you want to promote, select **Milestone actions** ({{< icon name="ellipsis_v" >}}) > **Promote**.
+ - Select the milestone title, and then select **Milestone actions** ({{< icon name="ellipsis_v" >}}) > **Promote**.
1. Select **Promote Milestone**.
## Assign a milestone to an issue or merge request
@@ -277,10 +303,13 @@ of the below topic into "Special milestone filters" -->
#### "Upcoming" and "Started" filters (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/501294) in GitLab 17.7
and is [planned for change](https://gitlab.com/gitlab-org/gitlab/-/issues/429728) in 18.0.
+{{< /alert >}}
+
The behavior of "Upcoming" and "Started" special filters is planned to change in upcoming GitLab major release 18.0.
The new behavior of both the filters is outlined in
[issue 429728](https://gitlab.com/gitlab-org/gitlab/-/issues/429728#proposed-issue-filter-logic-for-upcoming-and-started-milestones).
diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md
index 9bbd48769a60a2237668c3e9247f2fda4054b5f1..72c8fcb31b4daf35d7ec1085999bd871739d6297 100644
--- a/doc/user/project/milestones/burndown_and_burnup_charts.md
+++ b/doc/user/project/milestones/burndown_and_burnup_charts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Burndown and burnup charts
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone.
@@ -65,9 +68,12 @@ and you follow this workflow:
A burndown chart is available for every project or group milestone that has been attributed a **start
date** and a **due date**.
-NOTE:
+{{< alert type="note" >}}
+
You're able to [promote project](_index.md#promote-a-project-milestone-to-a-group-milestone) to group milestones and still see the **burndown chart** for them, respecting license limitations.
+{{< /alert >}}
+
The chart indicates the project's progress throughout that milestone (for issues assigned to it).
In particular, it shows how many issues were or are still open for a given day in the
@@ -137,15 +143,25 @@ have weight assigned, because issues with no weight don't show on the chart.
## Roll up weights
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381879) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `rollup_timebox_chart`. Disabled by default.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381879) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `rollup_timebox_chart`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
With [tasks](../../tasks.md), a more granular planning is possible.
If this feature is enabled, the weight of issues that have tasks is derived from the tasks in the
same milestone.
diff --git a/doc/user/project/ml/_index.md b/doc/user/project/ml/_index.md
index dd65ba94dbde7e854c9af9da15bdd501e2d8f4f5..3a9e8972e75d6e2b791ed845b237d2b8ee2fea82 100644
--- a/doc/user/project/ml/_index.md
+++ b/doc/user/project/ml/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: MLOps
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Model registry
diff --git a/doc/user/project/ml/experiment_tracking/_index.md b/doc/user/project/ml/experiment_tracking/_index.md
index 2f35b4def89f19366eab544e8088fb30abc4bb46..9f506d5f19f819a748f8aee066aec1bf10478412 100644
--- a/doc/user/project/ml/experiment_tracking/_index.md
+++ b/doc/user/project/ml/experiment_tracking/_index.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Machine learning model experiments
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9341) in GitLab 15.11.
-> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/9341) in GitLab 17.8.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9341) in GitLab 15.11.
+- [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/9341) in GitLab 17.8.
+
+{{< /history >}}
When creating machine learning models, data scientists often experiment with different parameters, configurations, and feature
engineering to improve the performance of the model. Keeping track of all this metadata and the associated
diff --git a/doc/user/project/ml/experiment_tracking/mlflow_client.md b/doc/user/project/ml/experiment_tracking/mlflow_client.md
index c46a084d0833885fbf9e4ee17e6c03f7a3c6604f..04847ed0ae39047252a2e73ab8d1bbd7ccbb8c95 100644
--- a/doc/user/project/ml/experiment_tracking/mlflow_client.md
+++ b/doc/user/project/ml/experiment_tracking/mlflow_client.md
@@ -5,12 +5,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: MLflow client compatibility
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11.
-> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/9341) in GitLab 17.8.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11.
+- [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/9341) in GitLab 17.8.
+
+{{< /history >}}
[MLflow](https://mlflow.org/) is a popular open source tool for Machine Learning experiment tracking.
GitLab [Model experiment tracking](_index.md) and GitLab
@@ -40,7 +47,7 @@ To use MLflow client compatibility from a local environment:
1. If the training code contains the call to `mlflow.set_tracking_uri()`, remove it.
In the model registry, you can copy the tracking URI from the overflow menu in the top right
-by selecting the vertical ellipsis (**{ellipsis_v}**).
+by selecting the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
## Model experiments
@@ -135,7 +142,11 @@ with mlflow.start_run():
### Loading a run
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/509595) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/509595) in GitLab 17.9.
+
+{{< /history >}}
You can load a run from the GitLab model registry to, for example, make predictions.
@@ -154,8 +165,12 @@ model.predict(data=sample_input)
### Associating a run to a CI/CD job
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119454) in GitLab 16.1.
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/9423) to beta in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119454) in GitLab 16.1.
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/9423) to beta in GitLab 17.1.
+
+{{< /history >}}
If your training code is being run from a CI/CD job, GitLab can use that information to enhance
run metadata. To associate a run to a CI/CD job:
diff --git a/doc/user/project/ml/model_registry/_index.md b/doc/user/project/ml/model_registry/_index.md
index ec26a010c9de01ff843890be967d76abbff3637d..126896ad79e7872e2f142c3c803e8dfa0fb058d3 100644
--- a/doc/user/project/ml/model_registry/_index.md
+++ b/doc/user/project/ml/model_registry/_index.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Model registry
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9423) in GitLab 16.8 as an [experiment](../../../../policy/development_stages_support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `model_registry`. Disabled by default. To enable the feature, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `model_registry`.
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/9423) to beta in GitLab 17.1.
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/14998) to general availability in GitLab 17.6.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9423) in GitLab 16.8 as an [experiment](../../../../policy/development_stages_support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `model_registry`. Disabled by default. To enable the feature, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `model_registry`.
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/9423) to beta in GitLab 17.1.
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/14998) to general availability in GitLab 17.6.
+
+{{< /history >}}
Model registry allows data scientists and developers to manage their machine learning
models, along with all metadata associated with their creation: parameters, performance
@@ -66,14 +73,14 @@ To delete a model and all its associated versions:
1. On the left sidebar, select **Deploy > Model registry**.
1. Find the model you want to delete.
-1. In the most right column, select the vertical ellipsis (**{ellipsis_v}**) and **Delete model**.
+1. In the most right column, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and **Delete model**.
Alternatively you can delete models from the model details page:
1. On the left sidebar, select **Deploy > Model registry**.
1. Find the model you want to delete.
1. Select the model name to view its details.
-1. Select the vertical ellipsis (**{ellipsis_v}**) and **Delete model**.
+1. Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and **Delete model**.
1. Confirm the deletion.
### Delete a model version
@@ -85,7 +92,7 @@ To delete a model version:
1. Select the model name to view its details.
1. Select the **Versions** tab.
1. Find the model version you want to delete
-1. In the most right column, select the vertical ellipsis (**{ellipsis_v}**) and **Delete model version**.
+1. In the most right column, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and **Delete model version**.
Alternatively you can delete models from the model version details page:
@@ -94,7 +101,7 @@ Alternatively you can delete models from the model version details page:
1. Select the model name to view its details.
1. Select the **Versions** tab.
1. Select the version name to view its details.
-1. Select the vertical ellipsis (**{ellipsis_v}**) and **Delete model version**.
+1. Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}) and **Delete model version**.
1. Confirm the deletion.
### Add artifacts to a model version
diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md
index 1decfc83ca9f543df26eed9ac538792b5e53309c..0beb9879f66a054de180ff85b73b047380619d97 100644
--- a/doc/user/project/organize_work_with_projects.md
+++ b/doc/user/project/organize_work_with_projects.md
@@ -1,8 +1,8 @@
---
stage: Tenant Scale
group: Organizations
-description: Project visibility, search, badges, layout.
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
+description: Project visibility, search, badges, layout.
title: Organize work with projects
---
diff --git a/doc/user/project/pages/_index.md b/doc/user/project/pages/_index.md
index 012778f7d92ffdd846903d12a1d02aeda9f5bf95..c0a1b67a35161c5c48c017cf3c4bd8ae3ff11f16 100644
--- a/doc/user/project/pages/_index.md
+++ b/doc/user/project/pages/_index.md
@@ -1,14 +1,17 @@
---
-description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.'
stage: Plan
group: Knowledge
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
+description: Learn how to use GitLab Pages to deploy a static website at no additional cost.
title: GitLab Pages
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With GitLab Pages, you can publish static websites directly from a repository
in GitLab.
@@ -160,10 +163,14 @@ To ensure each project uses different cookies, enable the Pages [unique domains]
## Unique domains
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9347) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `pages_unique_domain`. Disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/388151) in GitLab 15.11.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122229) in GitLab 16.3.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163523) unique domain URLs to be shorter in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9347) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `pages_unique_domain`. Disabled by default.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/388151) in GitLab 15.11.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122229) in GitLab 16.3.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163523) unique domain URLs to be shorter in GitLab 17.4.
+
+{{< /history >}}
By default, every new project uses pages unique domain. This is to avoid projects on the same group
to share cookies.
@@ -179,7 +186,11 @@ For example URLs, see [GitLab Pages default domain names](getting_started_part_o
## Primary domain
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/481334) in GitLab 17.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/481334) in GitLab 17.8.
+
+{{< /history >}}
When you use GitLab Pages with custom domains, you can redirect all requests to GitLab Pages to a primary domain.
When the primary domain is selected, users receive `308 Permanent Redirect` status that redirects the browser to the
@@ -197,11 +208,18 @@ Prerequisites:
## Expiring deployments
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162826) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162826) in GitLab 17.4.
+
+{{< /history >}}
You can configure your Pages deployments to be automatically deleted after
a period of time has passed by specifying a duration at [`pages.expire_in`](../../../ci/yaml/_index.md#pagespagesexpire_in):
@@ -250,16 +268,23 @@ To recover a stopped deployment that has not yet been deleted:
## Parallel deployments
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129534) in GitLab 16.7 as an [experiment](../../../policy/development_stages_support.md) [with a flag](../../feature_flags.md) named `pages_multiple_versions_setting`. Disabled by default.
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/480195) from "multiple deployments" to "parallel deployments" in GitLab 17.4.
-> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/422145) in GitLab 17.4.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/502219) to remove the project setting in GitLab 17.7.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/507423) to allow periods in `path_prefix` in GitLab 17.8.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/500000) to allow variables when passed to `publish` property in GitLab 17.9.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/487161) in GitLab 17.9. Feature flag `pages_multiple_versions_setting` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129534) in GitLab 16.7 as an [experiment](../../../policy/development_stages_support.md) [with a flag](../../feature_flags.md) named `pages_multiple_versions_setting`. Disabled by default.
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/480195) from "multiple deployments" to "parallel deployments" in GitLab 17.4.
+- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/422145) in GitLab 17.4.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/502219) to remove the project setting in GitLab 17.7.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/507423) to allow periods in `path_prefix` in GitLab 17.8.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/500000) to allow variables when passed to `publish` property in GitLab 17.9.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/487161) in GitLab 17.9. Feature flag `pages_multiple_versions_setting` removed.
+
+{{< /history >}}
Use the [`pages.path_prefix`](../../../ci/yaml/_index.md#pagespagespath_prefix) CI/CD option to configure a prefix for the GitLab Pages URL.
A prefix allows you to differentiate between multiple GitLab Pages deployments:
@@ -427,8 +452,12 @@ merge request is closed or merged.
## User-defined job names
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232505) in GitLab 17.5 with a flag `customizable_pages_job_name`, disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169095) in GitLab 17.6. Feature flag `customizable_pages_job_name` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232505) in GitLab 17.5 with a flag `customizable_pages_job_name`, disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169095) in GitLab 17.6. Feature flag `customizable_pages_job_name` removed.
+
+{{< /history >}}
To trigger a Pages deployment from any job, include the `pages` property in the
job definition. It can either be a Boolean set to `true` or a hash.
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/_index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/_index.md
index d35218ea0849f2e8db606e8e88db05b304197f8d..622b539bf8c813237dbd7901cb1a0f298158e485 100644
--- a/doc/user/project/pages/custom_domains_ssl_tls_certification/_index.md
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/_index.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Pages custom domains
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4, you can use verified domains to [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/_index.md#bypass-user-email-confirmation-with-verified-domains).
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4, you can use verified domains to [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/_index.md#bypass-user-email-confirmation-with-verified-domains).
+
+{{< /history >}}
You can use custom domains:
@@ -22,9 +29,12 @@ To use one or more custom domain names:
- Add a [custom **root domain** or a **subdomain**](#set-up-a-custom-domain).
- Add [SSL/TLS certification](#adding-an-ssltls-certificate-to-pages).
-WARNING:
+{{< alert type="warning" >}}
+
You cannot verify the [most popular public email domains](../../../group/access_and_permissions.md#restrict-group-access-by-domain).
+{{< /alert >}}
+
## Set up a custom domain
To set up Pages with a custom domain name, read the requirements and steps below.
@@ -96,7 +106,8 @@ server running on your instance).
-WARNING:
+{{< alert type="warning" >}}
+
If you use your root domain for your GitLab Pages website
**only**, and if your domain registrar supports this feature, you can
add a DNS apex `CNAME` record instead of an `A` record. The main
@@ -105,6 +116,8 @@ changes for whatever reason, you don't need to update your `A` record.
There may be a few exceptions, but **this method is not recommended**
as it most likely doesn't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain.
+{{< /alert >}}
+
##### For subdomains
Subdomains (`subdomain.example.com`) require:
@@ -161,18 +174,21 @@ After you have added all the DNS records:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Pages**.
-1. Next to the domain name, select **Edit** (**{pencil}**).
-1. In **Verification status**, select **Retry verification** (**{retry}**).
+1. Next to the domain name, select **Edit** ({{< icon name="pencil" >}}).
+1. In **Verification status**, select **Retry verification** ({{< icon name="retry" >}}).
As soon as your domain becomes active, your website is available through your domain name.
-WARNING:
+{{< alert type="warning" >}}
+
Considering GitLab instances with domain verification enabled,
if the domain can't be verified for 7 days, it's removed
from the GitLab project.
+{{< /alert >}}
+
Additionally:
- Domain verification is **required for GitLab.com users**.
@@ -262,7 +278,7 @@ meet these requirements.
1. On the left sidebar, select **Search or go to** and find your project.
1. On the left sidebar, select **Deploy > Pages**.
- 1. Next to the domain name, select **Edit** (**{pencil}**).
+ 1. Next to the domain name, select **Edit** ({{< icon name="pencil" >}}).
1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages).
1. Select **Save changes**.
@@ -310,7 +326,7 @@ To edit a custom domain:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Pages**.
-1. Next to the domain name, select **Edit** (**{pencil}**).
+1. Next to the domain name, select **Edit** ({{< icon name="pencil" >}}).
## Delete a custom domain
@@ -320,7 +336,7 @@ To delete and remove a custom domain:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Pages**.
-1. Next to the domain name, select **Remove domain** (**{remove}**)
+1. Next to the domain name, select **Remove domain** ({{< icon name="remove" >}})
1. When prompted, select **Remove domain**.
## Troubleshooting
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md
index a013e1ea9e0674e54222247f4c0f9ba0533e1dab..5e0e45e3a88a2064ab3b0051965abd2f8b665163 100644
--- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Pages DNS records
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A Domain Name System (DNS) web service routes visitors to websites
by translating domain names (such as `www.example.com`) into the
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md
index ece6e41becf1e336f51761fce00eeae354d7cd0f..f3efef78a91f9e5fd99710e605c8d020aed467c1 100644
--- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md
@@ -1,14 +1,17 @@
---
-description: "Automatic Let's Encrypt SSL certificates for GitLab Pages."
stage: Plan
group: Knowledge
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
+description: Automatic Let's Encrypt SSL certificates for GitLab Pages.
title: GitLab Pages Let's Encrypt certificates
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
The GitLab Pages integration with Let's Encrypt (LE) allows you
to use LE certificates for your Pages website with custom domains
@@ -18,11 +21,14 @@ GitLab does it for you, out-of-the-box.
[Let's Encrypt](https://letsencrypt.org) is a free, automated, and
open source Certificate Authority.
-WARNING:
+{{< alert type="warning" >}}
+
This feature covers only certificates for **custom domains**, not the wildcard certificate required to run
[Pages daemon](../../../../administration/pages/_index.md) (Self-managed, Free, Premium, and Ultimate only). Wildcard
certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342).
+{{< /alert >}}
+
## Prerequisites
Before you can enable automatic provisioning of an SSL certificate for your domain, make sure you have:
@@ -46,7 +52,7 @@ Once you've met the requirements, enable Let's Encrypt integration:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Pages**.
-1. Next to the domain name, select **Edit** (**{pencil}**).
+1. Next to the domain name, select **Edit** ({{< icon name="pencil" >}}).
1. Turn on the **Automatic certificate management using Let's Encrypt** toggle.
@@ -71,8 +77,8 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Pages**.
-1. Next to the domain name, select **Edit** (**{pencil}**).
-1. In **Verification status**, select **Retry verification** (**{retry}**).
+1. Next to the domain name, select **Edit** ({{< icon name="pencil" >}}).
+1. In **Verification status**, select **Retry verification** ({{< icon name="retry" >}}).
1. If you're still getting the same error:
1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain.
1. Make sure your domain **doesn't have** an `AAAA` DNS record.
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md
index 48bc5c1c11a68adeec2194476bff29c55be4c49d..fe3869cbf17e60dea233db5c3b1fb31703cb23ca 100644
--- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Pages SSL/TLS certificates
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
Every GitLab Pages project on GitLab.com is available under
HTTPS for the default Pages domain (`*.gitlab.io`). Once you set
@@ -15,11 +18,14 @@ up your Pages project with your custom (sub)domain, if you want
it secured by HTTPS, you must issue a certificate for that
(sub)domain and install it on your project.
-NOTE:
+{{< alert type="note" >}}
+
Certificates are **not** required to add to your custom
(sub)domain on your GitLab Pages project, though they are
highly recommendable.
+{{< /alert >}}
+
Let's start with an introduction to the importance of HTTPS.
## Why should you care about HTTPS?
diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md
index 95237cf4367681780c3a8b30aaffbf5e4bcf5011..0e87b6ead32b2f099767658517c73ae3c8f85ab4 100644
--- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md
+++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Create a GitLab Pages website from a CI/CD template
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs).
You can create your own `.gitlab-ci.yml` file from one of these templates, and run
@@ -19,7 +22,7 @@ Your GitLab repository should contain files specific to an SSG, or plain HTML. A
these steps, you may have to do additional configuration for the Pages site to generate properly.
1. On the left sidebar, select **Search or go to** and find your project.
-1. From the **Add** (**{plus}**) dropdown list, select **New file**.
+1. From the **Add** ({{< icon name="plus" >}}) dropdown list, select **New file**.
1. From the **Select a template type** dropdown list, select `.gitlab-ci.yml`.
1. From the **Apply a template** dropdown list, in the **Pages** section, select the name of your SSG.
1. In the **Commit message** box, type the commit message.
diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md
index 188171da64a9ccb71a2b7d68331f944aedc81d39..0d28e5abb7dec9c1454f60312194ee0d2d4e84e3 100644
--- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md
+++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Create a GitLab Pages website from a forked sample project
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages).
You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website.
diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md
index 453133269c6c6631dde67c44dd8542a00a786ea2..12cf7fe2962f74f453b59e4fd97f0debd7f16aec 100644
--- a/doc/user/project/pages/getting_started/pages_from_scratch.md
+++ b/doc/user/project/pages/getting_started/pages_from_scratch.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: 'Tutorial: Create a GitLab Pages website from scratch'
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This tutorial shows you how to create a Pages site from scratch using
the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG). You start with
diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md
index 2f608fd47495b623057558d6a8bff037f44b169e..c69165864e6194710a9cb3a7570af293ef4ac0cc 100644
--- a/doc/user/project/pages/getting_started/pages_new_project_template.md
+++ b/doc/user/project/pages/getting_started/pages_new_project_template.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Create a GitLab Pages website from a project template
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides templates for the most popular Static Site Generators (SSGs).
You can create a new project from a template and run the CI/CD pipeline to generate a Pages website.
@@ -15,7 +18,7 @@ You can create a new project from a template and run the CI/CD pipeline to gener
Use a template when you want to test GitLab Pages or start a new project that's already
configured to generate a Pages site.
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Create from Template**.
1. Next to one of the templates starting with **Pages**, select **Use template**.
diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md
index 1ac3d6cc7fa59391bee11bd91b5ff2ec3bebd686..02067ba6d010246f1559793fda657dee9370e895 100644
--- a/doc/user/project/pages/getting_started/pages_ui.md
+++ b/doc/user/project/pages/getting_started/pages_ui.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Create a GitLab Pages deployment for a static site
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you already have a GitLab project that contains your static site or framework,
you can generate a GitLab Pages website from it.
@@ -21,9 +24,12 @@ a pipeline deploys your Pages website.
- Your app must [output files to the `public` folder](../public_folder.md). If you create
this folder during the build pipeline, you do not need to commit it to Git.
- WARNING:
+ {{< alert type="warning" >}}
+
This step is important. Ensure your files are in a root-level `public` folder.
+ {{< /alert >}}
+
- You must have a project that either:
- Generates static sites or a client-rendered single-page application (SPA),
like [Eleventy](https://www.11ty.dev), [Astro](https://astro.build), or [Jekyll](https://jekyllrb.com).
diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md
index 227e8c960be6edccb4ae2afb0ddfdf4d0e7b0f84..bf3fd348e1b6f9408bb14192ba2c7c1e59674083 100644
--- a/doc/user/project/pages/getting_started_part_one.md
+++ b/doc/user/project/pages/getting_started_part_one.md
@@ -5,16 +5,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Pages default domain names and URLs
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
On this document, learn how to name your project for GitLab Pages
according to your intended website's URL.
## GitLab Pages default domain names
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163523) unique domain URLs to be shorter in GitLab 17.4.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163523) unique domain URLs to be shorter in GitLab 17.4.
+
+{{< /history >}}
If you use your own GitLab instance to deploy your site with GitLab Pages, verify your Pages
wildcard domain with your sysadmin. This guide is valid for any GitLab instance, provided that you
@@ -54,16 +61,22 @@ redirecting the browser to these unique domain URLs. Browsers might cache this r
For example, if the unique ID is `f85695`, the last example is
`http(s)://product-manual-f85695.example.io/`.
-WARNING:
+{{< alert type="warning" >}}
+
There are some known [limitations](introduction.md#subdomains-of-subdomains)
regarding namespaces served under the general domain name and HTTPS.
Make sure to read that section.
+{{< /alert >}}
+
To understand Pages domains clearly, read the examples below.
-NOTE:
+{{< alert type="note" >}}
+
The following examples imply you disabled the **Use unique domain** setting. If you did not, refer to the previous table, replacing `example.io` by `gitlab.io`.
+{{< /alert >}}
+
### Project website examples
- You created a project called `blog` under your username `john`,
@@ -104,9 +117,12 @@ The following examples imply you disabled the **Use unique domain** setting. If
## URLs and base URLs
-NOTE:
+{{< alert type="note" >}}
+
The `baseurl` option might be named differently in some static site generators.
+{{< /alert >}}
+
Every Static Site Generator (SSG) default configuration expects
to find your website under a (sub)domain (`example.com`), not
in a subdirectory of that domain (`example.com/subdir`). Therefore,
diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md
index 8a45f23a7d7aa794db70da33bbc482d546e363a6..21340db13dddbd7e5f3fef100b46a0fae6d3e4ab 100644
--- a/doc/user/project/pages/introduction.md
+++ b/doc/user/project/pages/introduction.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Pages settings
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This document is a user guide to explore the options and settings
GitLab Pages offers.
@@ -267,11 +270,15 @@ for both the `/data` and `/data/` URL paths.
## Customize the default folder
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/859) in GitLab 16.1 with a Pages flag named `FF_CONFIGURABLE_ROOT_DIR`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1073) in GitLab 16.1.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/890) in GitLab 16.2.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/500000) to allow variables when passed to `publish` property in GitLab 17.9.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/428018) the `publish` property under the `pages` keyword in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/859) in GitLab 16.1 with a Pages flag named `FF_CONFIGURABLE_ROOT_DIR`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1073) in GitLab 16.1.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/890) in GitLab 16.2.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/500000) to allow variables when passed to `publish` property in GitLab 17.9.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/428018) the `publish` property under the `pages` keyword in GitLab 17.9.
+
+{{< /history >}}
By default, the [artifact](../../../ci/jobs/job_artifacts.md) folder
that contains the static files of your site needs to have the name `public`.
@@ -304,7 +311,11 @@ To use variables in the `pages.publish` field, see [`pages:pages.publish`](../..
## Regenerate unique domain for GitLab Pages
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/481746) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/481746) in GitLab 17.7.
+
+{{< /history >}}
You can regenerate the unique domain for your GitLab Pages site.
diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md
index e458f79ae3cead96e7db2325aeb9c39bb0e44311..a686ad1365916db468bc8319c4e13c32dd312925 100644
--- a/doc/user/project/pages/pages_access_control.md
+++ b/doc/user/project/pages/pages_access_control.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Pages access control
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can enable Pages access control on your project
if your administrator has [enabled the access control feature](../../../administration/pages/_index.md#access-control)
@@ -48,7 +51,11 @@ can access the website.
## Restrict Pages access to project members for the group and its subgroups
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254962) in GitLab 17.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254962) in GitLab 17.9.
+
+{{< /history >}}
You can configure a setting for the group to restrict Pages access to only project members.
When enabled, all projects in the group and its subgroups become visible only to members.
diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md
index f296fac191ae799f07890e90ff30c50c58ae125f..9a6152967b5b2fedfc2519af7692466a0e68606d 100644
--- a/doc/user/project/pages/public_folder.md
+++ b/doc/user/project/pages/public_folder.md
@@ -1,17 +1,23 @@
---
-description: 'Learn how to configure the build output folder for the most
-common static site generators'
stage: Plan
group: Knowledge
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
+description: Learn how to configure the build output folder for the most common static site generators
title: GitLab Pages public folder
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - With GitLab 16.1 we introduced the ability to configure the published folder in `.gitlab-ci.yml`, so you longer need to change your framework config. For more information, see how to [set a custom folder to be deployed with Pages](introduction.md#customize-the-default-folder).
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- With GitLab 16.1 we introduced the ability to configure the published folder in `.gitlab-ci.yml`, so you longer need to change your framework config. For more information, see how to [set a custom folder to be deployed with Pages](introduction.md#customize-the-default-folder).
+
+{{< /history >}}
Follow these instructions to configure the `public` folder
for the following frameworks.
@@ -69,10 +75,13 @@ rename that folder to a collision-free alternative first:
## SvelteKit
-NOTE:
+{{< alert type="note" >}}
+
GitLab Pages supports only static sites. For SvelteKit,
you can use [`adapter-static`](https://kit.svelte.dev/docs/adapters#supported-environments-static-sites).
+{{< /alert >}}
+
When using `adapter-static`, add the following to your `svelte.config.js`:
```javascript
@@ -90,10 +99,13 @@ export default {
## Next.js
-NOTE:
+{{< alert type="note" >}}
+
GitLab Pages supports only static sites. For Next.js, you can use
Next's [Static HTML export functionality](https://nextjs.org/docs/pages/building-your-application/deploying/static-exports).
+{{< /alert >}}
+
With the release of [Next.js 13](https://nextjs.org/blog/next-13) a lot has changed on how Next.js works.
It is recommended to use the following `next.config.js` so all static assets can be exported properly:
@@ -129,9 +141,12 @@ The previous YAML example uses [user-defined job names](_index.md#user-defined-j
## Nuxt.js
-NOTE:
+{{< alert type="note" >}}
+
GitLab Pages supports only static sites.
+{{< /alert >}}
+
By default, Nuxt uses the `public` folder to store static assets. For GitLab
Pages, rename the `public` folder to a collision-free alternative first:
diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md
index 33af2054a8bfc2c9994cf85e75cbbba82db1f50b..6e7ab1daa4c764be575f4092b35935175d174853 100644
--- a/doc/user/project/pages/redirects.md
+++ b/doc/user/project/pages/redirects.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Pages redirects
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In GitLab Pages, you can configure rules to forward one URL to another using
[Netlify style](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file)
@@ -19,23 +22,26 @@ are supported.
| Feature | Supported | Example |
|---------------------------------------------------|------------------------|---------|
-| [Redirects (`301`, `302`)](#redirects) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` |
-| [Rewrites (`200`)](#rewrites) | **{check-circle}** Yes | `/* / 200` |
-| [Splats](#splats) | **{check-circle}** Yes | `/news/* /blog/:splat` |
-| [Placeholders](#placeholders) | **{check-circle}** Yes | `/news/:year/:month/:date /blog-:year-:month-:date.html` |
-| Rewrites (other than `200`) | **{dotted-circle}** No | `/en/* /en/404.html 404` |
-| Query parameters | **{dotted-circle}** No | `/store id=:id /blog/:id 301` |
-| Force ([shadowing](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing)) | **{dotted-circle}** No | `/app/ /app/index.html 200!` |
-| [Domain-level redirects](#domain-level-redirects) | **{check-circle}** Yes | `http://blog.example.com/* https://www.example.com/blog/:splat 301` |
-| Redirect by country or language | **{dotted-circle}** No | `/ /anz 302 Country=au,nz` |
-| Redirect by role | **{dotted-circle}** No | `/admin/* 200! Role=admin` |
-
-NOTE:
+| [Redirects (`301`, `302`)](#redirects) | {{< icon name="check-circle" >}} Yes | `/wardrobe.html /narnia.html 302` |
+| [Rewrites (`200`)](#rewrites) | {{< icon name="check-circle" >}} Yes | `/* / 200` |
+| [Splats](#splats) | {{< icon name="check-circle" >}} Yes | `/news/* /blog/:splat` |
+| [Placeholders](#placeholders) | {{< icon name="check-circle" >}} Yes | `/news/:year/:month/:date /blog-:year-:month-:date.html` |
+| Rewrites (other than `200`) | {{< icon name="dotted-circle" >}} No | `/en/* /en/404.html 404` |
+| Query parameters | {{< icon name="dotted-circle" >}} No | `/store id=:id /blog/:id 301` |
+| Force ([shadowing](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing)) | {{< icon name="dotted-circle" >}} No | `/app/ /app/index.html 200!` |
+| [Domain-level redirects](#domain-level-redirects) | {{< icon name="check-circle" >}} Yes | `http://blog.example.com/* https://www.example.com/blog/:splat 301` |
+| Redirect by country or language | {{< icon name="dotted-circle" >}} No | `/ /anz 302 Country=au,nz` |
+| Redirect by role | {{< icon name="dotted-circle" >}} No | `/admin/* 200! Role=admin` |
+
+{{< alert type="note" >}}
+
The [matching behavior test cases](https://gitlab.com/gitlab-org/gitlab-pages/-/blob/master/internal/redirects/matching_test.go)
are a good resource for understanding how GitLab implements rule matching in
detail. Community contributions are welcome for any edge cases that aren't included in
this test suite!
+{{< /alert >}}
+
## Create redirects
To create redirects, create a configuration file named `_redirects` in the
@@ -102,7 +108,11 @@ and an [HTTP status code](#http-status-codes):
## Rewrites
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/619) in GitLab 15.2.
+{{< history >}}
+
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/619) in GitLab 15.2.
+
+{{< /history >}}
Provide a status code of `200` to serve the content of the `to` path when the
request matches the `from`:
@@ -116,10 +126,14 @@ rewrite the URL.
## Domain-level redirects
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/936) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `FF_ENABLE_DOMAIN_REDIRECT`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/k8s-workloads/gitlab-com/-/merge_requests/3395) in GitLab 16.9.
-> - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1087) in GitLab 16.10.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1097) in GitLab 17.4. Feature flag `FF_ENABLE_DOMAIN_REDIRECT` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/936) in GitLab 16.8 [with a flag](../../../administration/feature_flags.md) named `FF_ENABLE_DOMAIN_REDIRECT`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/k8s-workloads/gitlab-com/-/merge_requests/3395) in GitLab 16.9.
+- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1087) in GitLab 16.10.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1097) in GitLab 17.4. Feature flag `FF_ENABLE_DOMAIN_REDIRECT` removed.
+
+{{< /history >}}
To create a domain-level redirect, add a domain-level path (beginning with `http://`
or `https://`) to either:
@@ -182,12 +196,15 @@ Splats also match empty strings, so the previous rule redirects
### Rewrite all requests to a root `index.html`
-NOTE:
+{{< alert type="note" >}}
+
If you are using [GitLab Pages integration with Let's Encrypt](custom_domains_ssl_tls_certification/lets_encrypt_integration.md),
you must enable it before adding this rule. Otherwise, the redirection breaks the Let's Encrypt
integration. For more details, see
[GitLab Pages issue 649](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/649).
+{{< /alert >}}
+
Single page applications (SPAs) often perform their own routing using
client-side routes. For these applications, it's important that _all_ requests
are rewritten to the root `index.html` so that the routing logic can be handled
diff --git a/doc/user/project/project_topics.md b/doc/user/project/project_topics.md
index 38fb78013e0c9a2fc48ceb066174ff3d054e1598..81428eddf39edb4463781367d91a4f7960843a55 100644
--- a/doc/user/project/project_topics.md
+++ b/doc/user/project/project_topics.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project topics
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Topics are labels that you can assign to projects to help you organize and find them.
A topic is typically a short name that describes the content or purpose of a project.
@@ -17,11 +20,14 @@ For example, you can create and assign the topics `python` and `hackathon` to al
Topics assigned to a project are displayed in the **Project overview** and [**Projects**](working_with_projects.md#view-all-projects-for-the-instance) lists, below the project information description.
-NOTE:
+{{< alert type="note" >}}
+
Only users with access to the project can see the topics assigned to that project,
but everyone (including unauthenticated users) can see the topics available on the GitLab instance.
Do not include sensitive information in the name of a topic.
+{{< /alert >}}
+
## Explore topics
To explore project topics:
@@ -62,17 +68,17 @@ To subscribe to a topic:
- From the **Explore topics** page:
- 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
+ 1. On the left sidebar, expand the top-most chevron ({{< icon name="chevron-down" >}}).
1. Select **Explore**.
1. Select **Topics**.
1. Select the topic you want to subscribe to.
- 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**).
+ 1. In the upper-right corner, select **Subscribe to the new projects feed** ({{< icon name="rss" >}}).
- From a project:
1. On the left sidebar, select **Search or go to** and find your project.
1. In the **Project overview** page, from the **Topics** list select the topic you want to subscribe to.
- 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**).
+ 1. In the upper-right corner, select **Subscribe to the new projects feed** ({{< icon name="rss" >}}).
The results are displayed as an RSS feed in Atom format.
The URL of the result contains a feed token and the list of projects that have the topic. You can add this URL to your feed reader.
diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md
index 49115eb69c85740ea5a80a9821bf7a2007bcf1ad..a22c0acfd88f75b0361db93219bad6331655cf1b 100644
--- a/doc/user/project/protected_tags.md
+++ b/doc/user/project/protected_tags.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Use protected tags in Git to control who can create tags, and prevent accidental tag updates or deletion."
+description: Use protected tags in Git to control who can create tags, and prevent accidental tag updates or deletion.
title: Protected tags
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Protected [tags](repository/tags/_index.md):
@@ -22,9 +25,12 @@ Each rule allows you to match either:
This feature evolved out of [protected branches](repository/branches/protected.md).
-NOTE:
+{{< alert type="note" >}}
+
To create or delete a protected tag, you must be in the **Allowed to create or delete** list for that protected tag.
+{{< /alert >}}
+
## Configuring protected tags
Prerequisites:
@@ -42,10 +48,13 @@ Prerequisites:
1. Select **Create wildcard**.
1. In **Allowed to create** , select roles that may create protected tags.
- NOTE:
- In GitLab Premium and Ultimate, you can also add groups or individual users
+ {{< alert type="note" >}}
+
+In GitLab Premium and Ultimate, you can also add groups or individual users
to **Allowed to create**.
+ {{< /alert >}}
+
1. Select **Protect**.
The protected tag (or wildcard) displays in the **Protected tags** list.
@@ -108,10 +117,13 @@ graph LR
To grant access to **Subgroup Y** members for **Project A**, you must share the project with the subgroup.
Adding the subgroup directly to the protected tag settings is not effective and isn't applicable to subgroup members.
-NOTE:
+{{< alert type="note" >}}
+
For a group to have protected tag permissions, the project must be directly shared with the group.
Inherited project membership from parent groups is not sufficient for protected tag permissions.
+{{< /alert >}}
+
## Wildcard protected tags
You can specify a wildcard protected tag, which protects all tags
@@ -158,7 +170,11 @@ Users can still create branches, but not tags, with the protected names.
## Allow deploy keys to create protected tags
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325415) in GitLab 15.11.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325415) in GitLab 15.11.
+
+{{< /history >}}
You can permit a [deploy key](deploy_keys/_index.md) to create protected tags.
@@ -205,7 +221,7 @@ To do this:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Tags**.
-1. Next to the tag you want to delete, select **Delete** (**{remove}**).
+1. Next to the tag you want to delete, select **Delete** ({{< icon name="remove" >}}).
1. On the confirmation dialog, enter the tag name and select **Yes, delete protected tag**.
Protected tags can only be deleted by using GitLab either from the UI or API.
diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md
index 7cf4d00cc9342dcf2eb7e48aaf8b80a0047e0076..a86a9be6f079b4421de744678e6cb3ac26709162 100644
--- a/doc/user/project/quick_actions.md
+++ b/doc/user/project/quick_actions.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab quick actions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Quick actions are text-based shortcuts for common actions that are usually done
by selecting buttons or dropdowns in the GitLab user interface. You can enter
@@ -51,95 +54,99 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do
| Command | Issue | Merge request | Epic | Action |
|:------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------|
-| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more active [CRM contacts](../crm/_index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). |
-| `/add_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six [email participants](service_desk/external_participants.md). This action is behind the feature flag `issue_email_participants`. Not supported in [issue templates](description_templates.md). |
-| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. |
-| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. |
-| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. |
-| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. |
-| `/assign_reviewer me` or `/reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. |
-| `/blocked_by <item1> <item2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the item as blocked by other items. The `<item>` value should be in the format of `#item`, `group/project#item`, or the full URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). |
-| `/blocks <item1> <item2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the item as blocking other items. The `<item>` value should be in the format of `#item`, `group/project#item`, or the full URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). |
-| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. This command performs no action. You can instead type `CC @user` or only `@user`. |
-| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. |
-| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). For epics, your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md). |
-| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. |
-| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given. Copies as much data as possible as long as the target project contains equivalent objects like labels, milestones, or epics. Does not copy comments or system notes unless `--with_notes` is provided as an argument. |
-| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. |
-| `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Mark issue or epic as confidential. Support for epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213741) in GitLab 15.6. |
-| `/convert_to_ticket <email address>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | [Convert an issue into a Service Desk ticket](service_desk/using_service_desk.md#convert-a-regular-issue-to-a-service-desk-ticket). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.9 |
-| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. |
-| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. |
-| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. |
-| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. |
-| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). |
-| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. |
-| `/duplicate <item>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this <work item type>. Marks as related to, and a duplicate of, <#item>. |
-| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. |
-| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. For epics, your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md). |
-| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). For epics, your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. |
-| `/iteration *iteration:<iteration ID> or <iteration name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"`. |
-| `/iteration [cadence:<iteration cadence ID> or <iteration cadence name>] <--current or --next>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration to the current or next upcoming iteration of the referenced iteration cadence. For example, `/iteration [cadence:"Team cadence"] --current` sets the iteration to the current iteration of the iteration cadence named "Team cadence". [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384885) in GitLab 16.9. |
-| `/iteration <--current or --next>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration to the current or next upcoming iteration when a group has one iteration cadence. For example, `/iteration --current` sets the iteration to the current iteration of the iteration cadence. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384885) in GitLab 16.9. |
-| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. |
-| `/link` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a link and description to [linked resources](../../operations/incident_management/linked_resources.md) in an incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5). |
-| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. |
-| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/auto_merge.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). |
-| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. |
-| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. |
-| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident. |
-| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. |
-| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident. In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. |
-| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. |
-| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md). |
-| `/react :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from `/award` in GitLab 16.7. `/award` is still available as an aliased command. |
-| `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). |
-| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. |
-| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. |
-| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch on the latest commit of the target branch. For help, see [troubleshooting information](../../topics/git/troubleshooting_git.md). |
-| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. |
-| `/relate <item1> <item2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark items as related. The `<item>` value should be in the format of `#item`, `group/project#item`, or the full URL. |
-| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. |
-| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/_index.md) |
-| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. |
-| `/remove_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove up to six [email participants](service_desk/external_participants.md). This action is behind the feature flag `issue_email_participants`. Not supported in issue templates, merge requests, or epics. |
-| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. |
-| `/remove_estimate` or `/remove_time_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. |
-| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration. |
-| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. |
-| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic. |
-| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. |
-| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. |
-| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. |
-| `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assigns or requests a new review from one or more users. |
-| `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assigns or requests a new review from one or more users. |
-| `/severity <severity>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. |
-| `/shrug` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add `¯\＿(ツ)＿/¯`. |
-| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. |
-| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review. |
-| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. |
-| `/tableflip` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add `(╯°□°)╯︵ â”»â”â”»`. |
-| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. |
-| `/timeline <timeline comment> \| <date(YYYY-MM-DD)> <time(HH:MM)>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a timeline event to this incident. For example, `/timeline DB load spiked \| 2022-09-07 09:30`. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4). |
-| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. |
-| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. |
-| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. |
-| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. |
-| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. |
-| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. |
-| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. |
-| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. |
-| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. |
-| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. |
-| `/unlink <item>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove link with to the provided issue. The `<item>` value should be in the format of `#item`, `group/project#item`, or the full URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414400) in GitLab 16.1). |
-| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. |
-| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. |
-| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid values are integers like `0`, `1`, or `2`. |
-| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). |
+| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Add one or more active [CRM contacts](../crm/_index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). |
+| `/add_email email1 email2` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Add up to six [email participants](service_desk/external_participants.md). This action is behind the feature flag `issue_email_participants`. Not supported in [issue templates](description_templates.md). |
+| `/approve` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Approve the merge request. |
+| `/assign @user1 @user2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Assign one or more users. |
+| `/assign me` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Assign yourself. |
+| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Assign one or more users as reviewers. |
+| `/assign_reviewer me` or `/reviewer me` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Assign yourself as a reviewer. |
+| `/blocked_by <item1> <item2>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Mark the item as blocked by other items. The `<item>` value should be in the format of `#item`, `group/project#item`, or the full URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). |
+| `/blocks <item1> <item2>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Mark the item as blocking other items. The `<item>` value should be in the format of `#item`, `group/project#item`, or the full URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). |
+| `/cc @user` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Mention a user. This command performs no action. You can instead type `CC @user` or only `@user`. |
+| `/child_epic <epic>` | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. |
+| `/clear_health_status` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Clear [health status](issues/managing_issues.md#health-status). For epics, your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md). |
+| `/clear_weight` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Clear weight. |
+| `/clone <path/to/project> [--with_notes]` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Clone the issue to given project, or the current one if no arguments are given. Copies as much data as possible as long as the target project contains equivalent objects like labels, milestones, or epics. Does not copy comments or system notes unless `--with_notes` is provided as an argument. |
+| `/close` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Close. |
+| `/confidential` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Mark issue or epic as confidential. Support for epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213741) in GitLab 15.6. |
+| `/convert_to_ticket <email address>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | [Convert an issue into a Service Desk ticket](service_desk/using_service_desk.md#convert-a-regular-issue-to-a-service-desk-ticket). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.9 |
+| `/copy_metadata <!merge_request>` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Copy labels and milestone from another merge request in the project. |
+| `/copy_metadata <#issue>` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Copy labels and milestone from another issue in the project. |
+| `/create_merge_request <branch name>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Create a new merge request starting from the current issue. |
+| `/done` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Mark to-do item as done. |
+| `/draft` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Set the [draft status](merge_requests/drafts.md). |
+| `/due <date>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. |
+| `/duplicate <item>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Close this <work item type>. Marks as related to, and a duplicate of, <#item>. |
+| `/epic <epic>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. |
+| `/estimate <time>` or `/estimate_time <time>` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. For epics, your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md). |
+| `/health_status <value>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Set [health status](issues/managing_issues.md#health-status). For epics, your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. |
+| `/iteration *iteration:<iteration ID> or <iteration name>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"`. |
+| `/iteration [cadence:<iteration cadence ID> or <iteration cadence name>] <--current or --next>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Set iteration to the current or next upcoming iteration of the referenced iteration cadence. For example, `/iteration [cadence:"Team cadence"] --current` sets the iteration to the current iteration of the iteration cadence named "Team cadence". [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384885) in GitLab 16.9. |
+| `/iteration <--current or --next>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Set iteration to the current or next upcoming iteration when a group has one iteration cadence. For example, `/iteration --current` sets the iteration to the current iteration of the iteration cadence. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384885) in GitLab 16.9. |
+| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. |
+| `/link` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Add a link and description to [linked resources](../../operations/incident_management/linked_resources.md) in an incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5). |
+| `/lock` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Lock the discussions. |
+| `/merge` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/auto_merge.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). |
+| `/milestone %milestone` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Set milestone. |
+| `/move <path/to/project>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. |
+| `/page <policy name>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Start escalations for the incident. |
+| `/parent_epic <epic>` | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. |
+| `/promote_to_incident` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Promote issue to incident. In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. |
+| `/promote` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Promote issue to epic. |
+| `/publish` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md). |
+| `/react :emoji:` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Toggle an emoji reaction. [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from `/award` in GitLab 16.7. `/award` is still available as an aliased command. |
+| `/ready` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). |
+| `/reassign @user1 @user2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Replace current assignees with those specified. |
+| `/reassign_reviewer @user1 @user2` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Replace current reviewers with those specified. |
+| `/rebase` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Rebase source branch on the latest commit of the target branch. For help, see [troubleshooting information](../../topics/git/troubleshooting_git.md). |
+| `/relabel ~label1 ~label2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Replace current labels with those specified. |
+| `/relate <item1> <item2>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Mark items as related. The `<item>` value should be in the format of `#item`, `group/project#item`, or the full URL. |
+| `/remove_child_epic <epic>` | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. |
+| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Remove one or more [CRM contacts](../crm/_index.md) |
+| `/remove_due_date` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Remove due date. |
+| `/remove_email email1 email2` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Remove up to six [email participants](service_desk/external_participants.md). This action is behind the feature flag `issue_email_participants`. Not supported in issue templates, merge requests, or epics. |
+| `/remove_epic` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Remove from epic. |
+| `/remove_estimate` or `/remove_time_estimate` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. |
+| `/remove_iteration` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Remove iteration. |
+| `/remove_milestone` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Remove milestone. |
+| `/remove_parent_epic` | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Remove parent epic from epic. |
+| `/remove_time_spent` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Remove time spent. |
+| `/remove_zoom` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Remove Zoom meeting from this issue. |
+| `/reopen` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Reopen. |
+| `/request_review @user1 @user2` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Assigns or requests a new review from one or more users. |
+| `/request_review me` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Assigns or requests a new review from one or more users. |
+| `/severity <severity>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. |
+| `/shrug` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Add `¯\＿(ツ)＿/¯`. |
+| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. |
+| `/submit_review` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Submit a pending review. |
+| `/subscribe` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Subscribe to notifications. |
+| `/tableflip` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Add `(╯°□°)╯︵ â”»â”â”»`. |
+| `/target_branch <local branch name>` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Set target branch. |
+| `/timeline <timeline comment> \| <date(YYYY-MM-DD)> <time(HH:MM)>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Add a timeline event to this incident. For example, `/timeline DB load spiked \| 2022-09-07 09:30`. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4). |
+| `/title <new title>` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Change title. |
+| `/todo` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Add a to-do item. |
+| `/unapprove` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Unapprove the merge request. |
+| `/unassign @user1 @user2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Remove specific assignees. |
+| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Remove specific reviewers. |
+| `/unassign_reviewer me` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Remove yourself as a reviewer. |
+| `/unassign_reviewer` or `/remove_reviewer` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Remove all reviewers. |
+| `/unassign` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Remove all assignees. |
+| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Remove specified labels. |
+| `/unlabel` or `/remove_label` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Remove all labels. |
+| `/unlink <item>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Remove link with to the provided issue. The `<item>` value should be in the format of `#item`, `group/project#item`, or the full URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414400) in GitLab 16.1). |
+| `/unlock` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Unlock the discussions. |
+| `/unsubscribe` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Unsubscribe from notifications. |
+| `/weight <value>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Set weight. Valid values are integers like `0`, `1`, or `2`. |
+| `/zoom <Zoom URL>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). |
## Work items
-> - Executing quick actions from comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391282) in GitLab 15.10.
+{{< history >}}
+
+- Executing quick actions from comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391282) in GitLab 15.10.
+
+{{< /history >}}
Work items in GitLab include [tasks](../tasks.md) and [OKRs](../okrs.md).
The following quick actions can be applied through the description field when editing or commenting on work items.
@@ -152,42 +159,42 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do
| Command | Task | Objective | Key Result | Action |
|:--------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------|
-| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Assign one or more users. |
-| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Assign yourself. |
-| `/add_child <work_item>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Add child to `<work_item>`. The `<work_item>` value should be in the format of `#item`, `group/project#item`, or a URL to a work item. Multiple work items can be added as children at the same time. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420797) in GitLab 16.5. |
-| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412275) in GitLab 16.5 |
-| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. |
-| `/checkin_reminder <cadence>` | **{dotted-circle}** No| **{check-circle}** Yes | **{dotted-circle}** No | Schedule [check-in reminders](../okrs.md#schedule-okr-check-in-reminders). Options are `weekly`, `twice-monthly`, `monthly`, or `never` (default). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422761) in GitLab 16.4 with flags named `okrs_mvc` and `okr_checkin_reminders`. |
-| `/clear_health_status` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). |
-| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. |
-| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. |
-| `/confidential` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark work item as confidential. [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412276) in GitLab 16.4. |
-| `/copy_metadata <work_item>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Copy labels and milestone from another work item in the same namespace. The `<work_item>` value should be in the format of `#item` or a URL to a work item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/509076) in GitLab 17.9. |
-| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. |
-| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. |
-| `/health_status <value>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, or `at_risk`. |
-| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. |
-| `/promote_to <type>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Promotes work item to specified type. Available options for `<type>`: `issue` (promote a task) or `objective` (promote a key result). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. |
-| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current assignees with those specified. |
-| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. |
-| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Remove due date. |
-| `/remove_child <work_item>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove the child `<work_item>`. The `<work_item>` value should be in the format of `#item`, `group/project#item`, or a URL to a work item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/132761) in GitLab 16.10. |
-| `/remove_parent` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Removes the parent work item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434344) in GitLab 16.9. |
-| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. |
-| `/set_parent <work_item>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Set parent work item to `<work_item>`. The `<work_item>` value should be in the format of `#item`, `group/project#item`, or a URL to a work item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420798) in GitLab 16.5. |
-| `/shrug` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add `¯\＿(ツ)＿/¯`. |
-| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420796) in GitLab 16.4 |
-| `/tableflip` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add `(╯°□°)╯︵ â”»â”â”»`. |
-| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. |
-| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. |
-| `/type` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `issue`, `task`, `objective` and `key result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0. |
-| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specific assignees. |
-| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | Remove all assignees. |
-| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. |
-| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. |
-| `/unlink` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove link to the provided work item. The `<work item>` value should be in the format of `#work_item`, `group/project#work_item`, or the full work item URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/481851) in GitLab 17.8. |
-| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe to notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420796) in GitLab 16.4 |
-| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. |
+| `/assign @user1 @user2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Assign one or more users. |
+| `/assign me` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Assign yourself. |
+| `/add_child <work_item>` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Add child to `<work_item>`. The `<work_item>` value should be in the format of `#item`, `group/project#item`, or a URL to a work item. Multiple work items can be added as children at the same time. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420797) in GitLab 16.5. |
+| `/award :emoji:` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Toggle an emoji reaction. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412275) in GitLab 16.5 |
+| `/cc @user` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. |
+| `/checkin_reminder <cadence>` | {{< icon name="dotted-circle" >}} No| {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Schedule [check-in reminders](../okrs.md#schedule-okr-check-in-reminders). Options are `weekly`, `twice-monthly`, `monthly`, or `never` (default). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422761) in GitLab 16.4 with flags named `okrs_mvc` and `okr_checkin_reminders`. |
+| `/clear_health_status` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Clear [health status](issues/managing_issues.md#health-status). |
+| `/clear_weight` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Clear weight. |
+| `/close` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Close. |
+| `/confidential` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Mark work item as confidential. [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412276) in GitLab 16.4. |
+| `/copy_metadata <work_item>` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Copy labels and milestone from another work item in the same namespace. The `<work_item>` value should be in the format of `#item` or a URL to a work item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/509076) in GitLab 17.9. |
+| `/done` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Mark to-do item as done. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. |
+| `/due <date>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. |
+| `/health_status <value>` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, or `at_risk`. |
+| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. |
+| `/promote_to <type>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Promotes work item to specified type. Available options for `<type>`: `issue` (promote a task) or `objective` (promote a key result). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. |
+| `/reassign @user1 @user2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Replace current assignees with those specified. |
+| `/relabel ~label1 ~label2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Replace current labels with those specified. |
+| `/remove_due_date` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Remove due date. |
+| `/remove_child <work_item>` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | Remove the child `<work_item>`. The `<work_item>` value should be in the format of `#item`, `group/project#item`, or a URL to a work item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/132761) in GitLab 16.10. |
+| `/remove_parent` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Removes the parent work item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434344) in GitLab 16.9. |
+| `/reopen` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Reopen. |
+| `/set_parent <work_item>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | Set parent work item to `<work_item>`. The `<work_item>` value should be in the format of `#item`, `group/project#item`, or a URL to a work item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420798) in GitLab 16.5. |
+| `/shrug` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Add `¯\＿(ツ)＿/¯`. |
+| `/subscribe` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Subscribe to notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420796) in GitLab 16.4 |
+| `/tableflip` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Add `(╯°□°)╯︵ â”»â”â”»`. |
+| `/title <new title>` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Change title. |
+| `/todo` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Add a to-do item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. |
+| `/type` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Converts work item to specified type. Available options for `<type>` include `issue`, `task`, `objective` and `key result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0. |
+| `/unassign @user1 @user2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Remove specific assignees. |
+| `/unassign` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Remove all assignees. |
+| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Remove specified labels. |
+| `/unlabel` or `/remove_label` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Remove all labels. |
+| `/unlink` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Remove link to the provided work item. The `<work item>` value should be in the format of `#work_item`, `group/project#work_item`, or the full work item URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/481851) in GitLab 17.8. |
+| `/unsubscribe` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Unsubscribe to notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420796) in GitLab 16.4 |
+| `/weight <value>` | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. |
## Commit messages
diff --git a/doc/user/project/releases/_index.md b/doc/user/project/releases/_index.md
index d487af8b064f5be07274608670bdb71e1c8c5927..ac3227dbe8244b39121f275e031932696b7783cc 100644
--- a/doc/user/project/releases/_index.md
+++ b/doc/user/project/releases/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Releases
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Create a release to capture a snapshot of your project that combines release notes, installation packages, and other assets for your users. Releases serve as a complete package of your project at a specific point in time, so your users can:
@@ -22,9 +25,12 @@ When you [create a release](#create-a-release), GitLab automatically:
- Archives a snapshot of your code.
- Generates release evidence (a JSON file for auditing and comparing releases).
-WARNING:
+{{< alert type="warning" >}}
+
Deleting a Git tag associated with a release also deletes the release.
+{{< /alert >}}
+
When you create a release, or after, you can:
- Add release notes.
@@ -91,8 +97,8 @@ GitLab provides an RSS feed of a project's releases, in Atom format. To view the
1. Select **Deploy > Releases**.
1. For all projects:
1. Go to the **Project overview** page.
- 1. On the right sidebar, select **Releases** (**{rocket-launch}**).
-1. In the upper-right corner, select the feed symbol (**{rss}**).
+ 1. On the right sidebar, select **Releases** ({{< icon name="rocket-launch" >}}).
+1. In the upper-right corner, select the feed symbol ({{< icon name="rss" >}}).
## Create a release
@@ -277,7 +283,11 @@ release tag. When the `released_at` date and time has passed, the badge is autom
## Historical releases
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199429) in GitLab 15.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199429) in GitLab 15.2.
+
+{{< /history >}}
You can create a release in the past using either the
[Releases API](../../../api/releases/_index.md#historical-releases) or the UI. When you set
@@ -303,7 +313,11 @@ In the UI:
## Delete a release
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213862) in GitLab 15.2
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213862) in GitLab 15.2
+
+{{< /history >}}
When you delete a release, its assets are also deleted. However, the associated
Git tag is not deleted.
@@ -321,7 +335,7 @@ In the UI:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Deploy > Releases**.
1. In the upper-right corner of the release you want to delete, select **Edit this release**
- (**{pencil}**).
+ ({{< icon name="pencil" >}}).
1. On the **Edit Release** page, select **Delete**.
1. Select **Delete release**.
@@ -353,11 +367,14 @@ Here is an example of milestones with no releases, one release, and two releases
-NOTE:
+{{< alert type="note" >}}
+
A subgroup's project releases cannot be associated with a parent group's milestone. To learn
more, read issue #328054,
[Releases cannot be associated with a supergroup milestone](https://gitlab.com/gitlab-org/gitlab/-/issues/328054).
+{{< /alert >}}
+
## Get notified when a release is created
You can be notified by email when a new release is created for your project.
@@ -422,7 +439,7 @@ To set a deploy freeze window in the UI, complete these steps:
1. Select **Add deploy freeze** to open the deploy freeze modal.
1. Enter the start time, end time, and time zone of the desired deploy freeze period.
1. Select **Add deploy freeze** in the modal.
-1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**) and remove it by selecting the delete button (**{remove}**).
+1. After the deploy freeze is saved, you can edit it by selecting the edit button ({{< icon name="pencil" >}}) and remove it by selecting the delete button ({{< icon name="remove" >}}).
If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the
@@ -444,7 +461,11 @@ For more information, see [Deployment safety](../../../ci/environments/deploymen
### Publish releases without giving access to source code
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216485) in GitLab 15.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216485) in GitLab 15.6.
+
+{{< /history >}}
You can make releases accessible to non-project members while keeping repository-related information, such as [source code](release_fields.md#source-code) and [release evidence](release_evidence.md), available only to project members. These settings are ideal for
projects that use releases to give access to new versions of software, but do not want the source code to be publicly available.
@@ -469,11 +490,18 @@ and set **Maintainer** in the **Allowed to create** column.
## Release Metrics
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9.
+{{< /history >}}
Group-level release metrics are available by navigating to **Group > Analytics > CI/CD**.
These metrics include:
diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md
index ce6ddabb237943762b02c42cb0d5c920c7e044b6..721c445045bb2a44d20b8d55c5a9b3490e2dc80f 100644
--- a/doc/user/project/releases/release_cicd_examples.md
+++ b/doc/user/project/releases/release_cicd_examples.md
@@ -19,10 +19,13 @@ In this CI/CD example, the release is triggered by one of the following events:
You can use this method if you prefer to create the Git tag manually, and create a release as a
result.
-NOTE:
+{{< alert type="note" >}}
+
Do not provide Release notes when you create the Git tag in the UI. Providing release notes
creates a release, resulting in the pipeline failing.
+{{< /alert >}}
+
Key points in the following _extract_ of an example `.gitlab-ci.yml` file:
- The `rules` stanza defines when the job is added to the pipeline.
@@ -67,11 +70,14 @@ release_job:
ref: '$CI_COMMIT_SHA' # The tag is created from the pipeline SHA.
```
-NOTE:
+{{< alert type="note" >}}
+
Environment variables set in `before_script` or `script` are not available for expanding
in the same job. Read more about
[potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400).
+{{< /alert >}}
+
## Create release metadata in a custom script
In this CI/CD example the release preparation is split into separate jobs for greater flexibility:
diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md
index 4a8fc399470ec5c7cdc0acd8767cd1c55dc5311f..10457d15f8c4fec26a72a378b69c60f3f4b18b20 100644
--- a/doc/user/project/releases/release_cli.md
+++ b/doc/user/project/releases/release_cli.md
@@ -5,13 +5,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab Release CLI tool
---
-WARNING:
+{{< alert type="warning" >}}
+
**The `release-cli` is in maintenance mode**.
The `release-cli` does not accept new features.
All new feature development happens in the `glab` CLI,
so you should use the [`glab` CLI](../../../editor_extensions/gitlab_cli/_index.md) whenever possible.
The `release-cli` is in maintenance mode, and [issue cli#7450](https://gitlab.com/gitlab-org/cli/-/issues/7450) proposes to deprecate it as the `glab` CLI matures.
+{{< /alert >}}
+
The [GitLab Release CLI (`release-cli`)](https://gitlab.com/gitlab-org/release-cli)
is a command-line tool for managing releases from the command line or from a CI/CD pipeline.
You can use the release CLI to create, update, modify, and delete releases.
@@ -33,9 +36,12 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description \
## Install the `release-cli` for the Shell executor
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The `release-cli` binaries are [available in the package registry](https://gitlab.com/gitlab-org/release-cli/-/packages).
diff --git a/doc/user/project/releases/release_evidence.md b/doc/user/project/releases/release_evidence.md
index b082edc1890b90028e7d4858544a739607ed9ee2..17b98778a72b711bf1f24f8f73c0bf14e7d1b788 100644
--- a/doc/user/project/releases/release_evidence.md
+++ b/doc/user/project/releases/release_evidence.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Release evidence
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Each time a release is created, GitLab takes a snapshot of data that's related to it.
This data is saved in a JSON file and called *release evidence*. The feature
@@ -69,9 +72,12 @@ Here is an example of a release evidence object:
## Collect release evidence
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/_index.md#collect-release-evidence). You can collect release evidence multiple times for one release.
@@ -79,9 +85,12 @@ Evidence collection snapshots are visible on the Releases page, along with the t
## Include report artifacts as release evidence
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you create a release, if [job artifacts](../../../ci/yaml/_index.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence.
diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md
index d7c4bdfbd7c39bbd18cbc9caae73930d64817e2f..f5db58b210dfee08664e9f6e0d8c28e3c9fb9f8e 100644
--- a/doc/user/project/releases/release_fields.md
+++ b/doc/user/project/releases/release_fields.md
@@ -68,7 +68,11 @@ Each link as an asset has the following attributes:
#### Permanent links to release assets
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375489) in GitLab 15.9, links for private releases can be accessed using a personal access token.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375489) in GitLab 15.9, links for private releases can be accessed using a personal access token.
+
+{{< /history >}}
The assets associated with a release are accessible through a permanent URL.
GitLab always redirects this URL to the actual asset
@@ -230,17 +234,23 @@ release:
- release-cli create --name $CI_COMMIT_TAG --description "Release $CI_COMMIT_TAG" --ref $CI_COMMIT_TAG --tag-name $CI_COMMIT_TAG --assets-link=$env:assetjson
```
-NOTE:
+{{< alert type="note" >}}
+
Directly attaching [job artifacts](../../../ci/jobs/job_artifacts.md)
links to a release is not recommended, because artifacts are ephemeral and
are used to pass data in the same pipeline. This means there's a risk that
they could either expire or someone might manually delete them.
+{{< /alert >}}
+
### Number of new and total features
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
On [GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/releases), you can view the number of new and total features in the project.
diff --git a/doc/user/project/remote_development/_index.md b/doc/user/project/remote_development/_index.md
index de6c42ded97f012acecdb81081529316729d452d..c171ed92a472b27db4588189dd0419270f08aec7 100644
--- a/doc/user/project/remote_development/_index.md
+++ b/doc/user/project/remote_development/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Remote Development
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
-description: "Use your web browser to write code in a secure environment."
+description: Use your web browser to write code in a secure environment.
title: Remote development
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Remote development is a set of features you can use to make code changes
without having to install any dependencies or clone any repositories locally.
@@ -26,8 +29,11 @@ The Web IDE, however, lacks a native runtime environment where you could compile
## Workspaces
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
You can use [workspaces](../../workspace/_index.md) to create a fully featured development environment directly from GitLab.
This environment runs on a remote server and provides you with a complete IDE experience
diff --git a/doc/user/project/repository/_index.md b/doc/user/project/repository/_index.md
index c45bce80cc11a13e784d885e37ac4432126e0b32..2b48f1189285115d8d0c565951dc4c549b941ee6 100644
--- a/doc/user/project/repository/_index.md
+++ b/doc/user/project/repository/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "How to create, clone, and use GitLab repositories."
+description: How to create, clone, and use GitLab repositories.
title: Repository
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)
is where you store your code, make changes, and track changes using version control.
@@ -40,7 +43,7 @@ To add or upload a file from the GitLab UI:
1. On the left sidebar, select **Search or go to** and find your project.
1. Go to the directory you want to upload the file to.
-1. Next to the directory name, select the plus icon (**{plus}**) > **Upload file**.
+1. Next to the directory name, select the plus icon ({{< icon name="plus" >}}) > **Upload file**.
1. Drop or upload your file.
1. Enter a commit message.
1. Optional. To create a merge request with your changes, in **Target branch**, enter a branch name
diff --git a/doc/user/project/repository/branches/_index.md b/doc/user/project/repository/branches/_index.md
index 8e4179f12b984439783faec44774a3084aa724bc..89c59318ff9f1228eb9fc9654241728280d02918 100644
--- a/doc/user/project/repository/branches/_index.md
+++ b/doc/user/project/repository/branches/_index.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Understand how to name, manage, and protect Git branches."
+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
+description: Understand how to name, manage, and protect Git branches.
title: Branches
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A branch is a version of a project's working tree. Branches are the
foundation of development in a project. When you create a new
@@ -52,7 +55,7 @@ On this page, you can:
- [Delete merged branches](#delete-merged-branches).
- See merge request links that point to the default branch.
- Branches with merge requests that do not point to the default branch display the **{merge-request}** **New** merge request button.
+ Branches with merge requests that do not point to the default branch display the {{< icon name="merge-request" >}} **New** merge request button.
- [View branch rules](branch_rules.md#view-branch-rules).
- See latest pipeline status on the branch.
@@ -112,7 +115,7 @@ To create a branch from an issue:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues** and find your issue.
1. Below the issue description, find the **Create merge request** dropdown list, and select
- **{chevron-down}** to display the dropdown list.
+ {{< icon name="chevron-down" >}} to display the dropdown list.
1. Select **Create branch**. A default **Branch name** is provided, based on the
[default pattern](#configure-default-pattern-for-branch-names-from-issues) for
this project. If desired, enter a different **Branch name**.
@@ -225,7 +228,7 @@ To compare branches in a repository:
[Git command](../../../../topics/git/commands.md).
<!-- vale gitlab_base.SubstitutionWarning = YES -->
1. Select **Compare** to show the list of commits, and changed files.
-1. Optional. To reverse the **Source** and **Target**, select **Swap revisions** (**{substitute}**).
+1. Optional. To reverse the **Source** and **Target**, select **Swap revisions** ({{< icon name="substitute" >}}).
## Delete merged branches
@@ -242,23 +245,33 @@ To do this:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Branches**.
-1. In the upper right corner of the page, select **More** **{ellipsis_v}**.
+1. In the upper right corner of the page, select **More** {{< icon name="ellipsis_v" >}}.
1. Select **Delete merged branches**.
1. In the dialog, enter the word `delete` to confirm, then select **Delete merged branches**.
-NOTE:
+{{< alert type="note" >}}
+
Deleting a branch does not completely erase all related data.
Some information persists to maintain project history and to support recovery processes.
For more information, see [Handle sensitive information](../../../../topics/git/undo.md#handle-sensitive-information).
+{{< /alert >}}
+
## Configure workflows for target branches
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127115) in GitLab 16.4 [with a flag](../../../../administration/feature_flags.md) named `target_branch_rules_flag`. Enabled by default.
+- [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136431) in GitLab 16.7.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127115) in GitLab 16.4 [with a flag](../../../../administration/feature_flags.md) named `target_branch_rules_flag`. Enabled by default.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136431) in GitLab 16.7.
+{{< /history >}}
Some projects use multiple long-term branches for development, like `develop` and `qa`.
In these projects, you might want to keep `main` as the default branch, but expect
diff --git a/doc/user/project/repository/branches/branch_rules.md b/doc/user/project/repository/branches/branch_rules.md
index c7fec8b1914e56663a20e365e28771dc298c1626..8ed7f4acfa6b914585c1f4e7bb3b8110aee100ae 100644
--- a/doc/user/project/repository/branches/branch_rules.md
+++ b/doc/user/project/repository/branches/branch_rules.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Understand how to name, manage, and protect Git branches."
+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
+description: Understand how to name, manage, and protect Git branches.
title: Branch rules
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides multiple methods to protect individual branches. These methods
ensure your branches receive oversight and quality checks from their creation to their deletion:
@@ -30,9 +33,13 @@ You can manage your branches:
## View branch rules
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.11.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123368) in GitLab 16.1. Feature flag `branch_rules` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.11.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123368) in GitLab 16.1. Feature flag `branch_rules` removed.
+
+{{< /history >}}
The **Branch rules overview** page shows all branches with any configured protections,
and their protection methods:
@@ -60,16 +67,23 @@ To view branch rules and protections for a single branch:
## Create a branch rule
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 16.8 with a flag named `add_branch_rules`. Disabled by default.
-> - Feature flag `add_branch_rules` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) to `edit_branch_rules` in GitLab 16.11. Disabled by default.
-> - **All branches** and **All protected branches** options [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388129) in GitLab 17.0.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.4.
-> - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 16.8 with a flag named `add_branch_rules`. Disabled by default.
+- Feature flag `add_branch_rules` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) to `edit_branch_rules` in GitLab 16.11. Disabled by default.
+- **All branches** and **All protected branches** options [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388129) in GitLab 17.0.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.4.
+- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.5.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Maintainer role for the project.
@@ -93,9 +107,12 @@ To create a branch rule:
### Add a branch rule protection
-NOTE:
+{{< alert type="note" >}}
+
Not available for `all branches`.
+{{< /alert >}}
+
To add protections to a new branch:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -107,13 +124,19 @@ To add protections to a new branch:
### Add an approval rule
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
Not available for `all branches`.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Maintainer role for the project.
@@ -138,12 +161,19 @@ For additional information, see [Approval rules](../../merge_requests/approvals/
### Edit squash commits option
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/181370) in GitLab 17.9 with a flag named `branch_rule_squash_settings`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/181370) in GitLab 17.9 with a flag named `branch_rule_squash_settings`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Maintainer role for the project.
@@ -163,17 +193,27 @@ To edit a squash option:
### Add a status check service
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12522) in GitLab 17.4 [with a flag](../../../../administration/feature_flags.md) named `edit_branch_rules`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.4.
-> - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.5.
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12522) in GitLab 17.4 [with a flag](../../../../administration/feature_flags.md) named `edit_branch_rules`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.4.
+- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.5.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
Not available for `all protected branches`.
+{{< /alert >}}
+
To add a status check service:
1. From the [branch rule details](#view-branch-rule-details) page, go to the **Status checks** section.
@@ -189,15 +229,22 @@ For more information, see [External status checks](../../merge_requests/status_c
## Edit a branch rule target
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 16.8 with a flag named `add_branch_rules`. Disabled by default.
-> - Feature flag `add_branch_rules` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) to `edit_branch_rules` in GitLab 16.11. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.4.
-> - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 16.8 with a flag named `add_branch_rules`. Disabled by default.
+- Feature flag `add_branch_rules` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) to `edit_branch_rules` in GitLab 16.11. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.4.
+- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.5.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Maintainer role for the project.
@@ -214,9 +261,12 @@ To edit a branch rule target:
### Edit a branch rule protection
-NOTE:
+{{< alert type="note" >}}
+
Not available for `all branches`.
+{{< /alert >}}
+
To edit branch rule protections:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -232,23 +282,33 @@ To edit branch rule protections:
1. If desired, search to add **Deploy keys**.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
In GitLab Premium and Ultimate, you can also add groups or individual users
to **Allowed to merge** and **Allowed to push and merge**.
+{{< /alert >}}
+
For additional information about branch protection controls, see [Protected branches](protected.md).
## Delete a branch rule
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 16.8 with a flag named `add_branch_rules`. Disabled by default.
-> - Feature flag `add_branch_rules` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) to `edit_branch_rules` in GitLab 16.11. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.4.
-> - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 16.8 with a flag named `add_branch_rules`. Disabled by default.
+- Feature flag `add_branch_rules` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) to `edit_branch_rules` in GitLab 16.11. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.4.
+- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/454501) in GitLab 17.5.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Maintainer role for the project.
diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md
index c0b9b32bf8d2510e3f59693ebd14d6b2e983768d..56febaa9e996392fc9bfb7786bfdf80d15862b5a 100644
--- a/doc/user/project/repository/branches/default.md
+++ b/doc/user/project/repository/branches/default.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Use Git branches to develop new features. Add branch protections to critical branches to ensure only trusted users can merge into them."
+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
+description: Use Git branches to develop new features. Add branch protections to critical branches to ensure only trusted users can merge into them.
title: Default branch
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you create a new [project](../../_index.md), GitLab creates a default branch
in the repository. A default branch has special configuration options not shared
@@ -56,9 +59,12 @@ API users can also use the `default_branch` attribute of the
## Change the default branch name for new projects in an instance
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Administrators](../../../permissions.md) of GitLab Self-Managed can
customize the initial branch for projects hosted on that instance. Individual
@@ -93,11 +99,18 @@ unless a subgroup configuration overrides it.
## Protect initial default branches
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
-> - Full protection after initial push [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118729) in GitLab 16.0.
+{{< /details >}}
+
+{{< history >}}
+
+- Full protection after initial push [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118729) in GitLab 16.0.
+
+{{< /history >}}
GitLab administrators and group owners can define [branch protections](protected.md)
to apply to every repository's default branch for the instance, or for individual groups, with one of these options:
@@ -113,14 +126,20 @@ to apply to every repository's default branch for the instance, or for individua
- **Not protected** - Both developers and maintainers can push new commits
and force push.
-WARNING:
+{{< alert type="warning" >}}
+
Unless **Fully protected** is chosen, a malicious developer could attempt to steal your sensitive data. For example, a malicious `.gitlab-ci.yml` file could be committed to a protected branch and later, if a pipeline is run against that branch, result in exfiltration of group CI/CD variables.
+{{< /alert >}}
+
### For all projects in an instance
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This setting applies only to each repository's default branch. To protect other branches,
you must either:
@@ -141,9 +160,12 @@ groups and subgroups can override the instance default setting for their project
#### Prevent overrides of default branch protection
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Group owners can override protections for default branches set for an entire instance
on a per-group basis. In
@@ -156,14 +178,20 @@ disable this privilege for group owners, enforcing the protection rule set for t
1. Clear the **Allow owners to manage default branch protection per group** checkbox.
1. Select **Save changes**.
-NOTE:
+{{< alert type="note" >}}
+
GitLab administrators can still update the default branch protection of a group.
+{{< /alert >}}
+
### For all projects in a group
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Group owners can override protections for default branches set for an entire instance
on a per-group basis. In
@@ -179,13 +207,16 @@ which locks this setting for group owners.
## Update the default branch name in your repository
-WARNING:
+{{< alert type="warning" >}}
+
Changing the name of your default branch can potentially break tests,
CI/CD configuration, services, helper utilities, and any integrations your repository
uses. Before you change this branch name, consult with your project owners and maintainers.
Ensure they understand the scope of this change includes references to the old
branch name in related code and scripts.
+{{< /alert >}}
+
When you change the default branch name for an existing repository, don't create a new branch.
Preserve the history of your default branch by renaming it. This example renames a Git repository's
(`example`) default branch:
diff --git a/doc/user/project/repository/branches/protected.md b/doc/user/project/repository/branches/protected.md
index da0b3fb32e464d4cb5b33b2f9453869281b2161a..28a16144024a90d6038cb674a09112fc941f9849 100644
--- a/doc/user/project/repository/branches/protected.md
+++ b/doc/user/project/repository/branches/protected.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Protected branches in GitLab restrict who can push to, merge, or modify a Git branch."
+description: Protected branches in GitLab restrict who can push to, merge, or modify a Git branch.
title: Protected branches
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In GitLab, [permissions](../../../permissions.md) are fundamentally defined around the
idea of having read or write permission to the repository and branches. To impose
@@ -28,7 +31,11 @@ The [default branch](default.md) for your repository is protected by default.
## Who can modify a protected branch
-> - Branch push permission [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118532) to require GitLab administrators to also have the **allowed** permission in GitLab 16.0.
+{{< history >}}
+
+- Branch push permission [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118532) to require GitLab administrators to also have the **allowed** permission in GitLab 16.0.
+
+{{< /history >}}
When a branch is protected, the default behavior enforces these restrictions on the branch.
@@ -109,22 +116,32 @@ To protect a branch:
1. From the **Allowed to merge** list, select a role that can merge into this branch.
1. From the **Allowed to push and merge** list, select a role that can push to this branch.
- NOTE:
- In GitLab Premium and Ultimate, you can also add groups or individual users
+ {{< alert type="note" >}}
+
+In GitLab Premium and Ultimate, you can also add groups or individual users
to **Allowed to merge** and **Allowed to push and merge**.
+ {{< /alert >}}
+
1. Select **Protect**.
The protected branch displays in the list of protected branches.
### For all projects in a group
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 [with a flag](../../../../administration/feature_flags.md) named `group_protected_branches`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/500250) in GitLab 17.6. Feature flag `group_protected_branches` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 [with a flag](../../../../administration/feature_flags.md) named `group_protected_branches`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/500250) in GitLab 17.6. Feature flag `group_protected_branches` removed.
+
+{{< /history >}}
Group owners can create protected branches for a group. These settings are inherited
by all projects in the group and can't be overridden by project settings.
@@ -166,10 +183,13 @@ to a protected branch:
Allowed to push and merge: @group-x/subgroup-y
```
-NOTE:
+{{< alert type="note" >}}
+
When you assign a group to a protected branch, only direct members of that group are included.
Members from parent groups are not automatically granted permissions to the protected branch.
+{{< /alert >}}
+
#### Group inheritance and eligibility
```mermaid
@@ -215,10 +235,13 @@ To grant access to **Subgroup Y** members for **Project A**, you must share the
the subgroup. Adding the subgroup directly to the protected branch settings is not effective
and isn't applicable to subgroup members.
-NOTE:
+{{< alert type="note" >}}
+
For a group to have protected branch permissions, the project must be directly shared with the group.
Inherited project membership from parent groups is not sufficient for protected branch permissions.
+{{< /alert >}}
+
## Protect multiple branches with wildcard rules
When using wildcards, multiple rules can apply to a single branch.
@@ -369,9 +392,12 @@ As the most permissive option determines the behavior, the resulting permissions
## Require Code Owner approval on a protected branch
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
For a protected branch, you can require at least one approval by a [Code Owner](../../codeowners/_index.md).
If a branch is protected by multiple rules, code owner approval is required if _any_ of
@@ -454,7 +480,7 @@ branches by using the GitLab web interface:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Branches**.
-1. Next to the branch you want to delete, select **Delete** (**{remove}**).
+1. Next to the branch you want to delete, select **Delete** ({{< icon name="remove" >}}).
1. On the confirmation dialog, enter the branch name and select **Yes, delete protected branch**.
Branch names [are case-sensitive](_index.md#name-your-branch).
diff --git a/doc/user/project/repository/code_explain.md b/doc/user/project/repository/code_explain.md
index 1dba94c2d38cdc2107b44e29e00c93e004b99b20..c4206090f99204acdfb46d2eb0614ba9c7821eef 100644
--- a/doc/user/project/repository/code_explain.md
+++ b/doc/user/project/repository/code_explain.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Explain code in a file
---
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**LLM:** Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+{{< details >}}
-> - Introduced in GitLab 15.11 as an [experiment](../../../policy/development_stages_support.md#experiment) on GitLab.com.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) in GitLab 16.8.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- LLM: Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet)
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced in GitLab 15.11 as an [experiment](../../../policy/development_stages_support.md#experiment) on GitLab.com.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/429915) in GitLab 16.8.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+
+{{< /history >}}
If you spend a lot of time trying to understand code that others have created, or
you struggle to understand code written in a language you are not familiar with,
@@ -29,7 +36,7 @@ To explain the code in a file:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select a file that contains code.
1. Select the lines you want explained.
-1. On the left side, select the question mark (**{question}**).
+1. On the left side, select the question mark ({{< icon name="question" >}}).
You might have to scroll to the first line of your selection to view it.
diff --git a/doc/user/project/repository/code_suggestions/_index.md b/doc/user/project/repository/code_suggestions/_index.md
index 8595ed57de19fa0d50b8a8f6e9b891e285003234..b188c048662a3c27cb005441df47d2c587248095 100644
--- a/doc/user/project/repository/code_suggestions/_index.md
+++ b/doc/user/project/repository/code_suggestions/_index.md
@@ -2,26 +2,36 @@
stage: Create
group: Code Creation
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
-description: "Code Suggestions helps you write code in GitLab more efficiently by using AI to suggest code as you type."
+description: Code Suggestions helps you write code in GitLab more efficiently by using AI to suggest code as you type.
title: Code Suggestions
---
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
-**LLMs:** For code completion, Fireworks AI-hosted [`Qwen2.5 7B`](https://fireworks.ai/models/fireworks/qwen2p5-coder-7b) and Vertex AI Codey [`code-gecko`](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/code-gecko). For code generation, Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet).
+{{< details >}}
-> - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1.
-> - [Removed support for GitLab native model](https://gitlab.com/groups/gitlab-org/-/epics/10752) in GitLab 16.2.
-> - [Introduced support for Code Generation](https://gitlab.com/gitlab-org/gitlab/-/issues/415583) in GitLab 16.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435271) in GitLab 16.7.
-> - Subscription changed to require GitLab Duo Pro on February 15, 2024.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
-> - [Introduced support for Fireworks AI-hosted Qwen2.5 code completion model](https://gitlab.com/groups/gitlab-org/-/epics/15850) in GitLab 17.6, with a flag named `fireworks_qwen_code_completion`.
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- LLMs: For code completion, Fireworks AI-hosted [`Qwen2.5 7B`](https://fireworks.ai/models/fireworks/qwen2p5-coder-7b) and Vertex AI Codey [`code-gecko`](https://console.cloud.google.com/vertex-ai/publishers/google/model-garden/code-gecko). For code generation, Anthropic [Claude 3.5 Sonnet](https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden/claude-3-5-sonnet).
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1.
+- [Removed support for GitLab native model](https://gitlab.com/groups/gitlab-org/-/epics/10752) in GitLab 16.2.
+- [Introduced support for Code Generation](https://gitlab.com/gitlab-org/gitlab/-/issues/415583) in GitLab 16.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/435271) in GitLab 16.7.
+- Subscription changed to require GitLab Duo Pro on February 15, 2024.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- [Introduced support for Fireworks AI-hosted Qwen2.5 code completion model](https://gitlab.com/groups/gitlab-org/-/epics/15850) in GitLab 17.6, with a flag named `fireworks_qwen_code_completion`.
+
+{{< /history >}}
+
+{{< alert type="note" >}}
-NOTE:
GitLab Duo requires GitLab 17.2 and later for the best user experience and results. Earlier versions may continue to work, however the experience may be degraded. You should [upgrade to the latest version of GitLab](../../../../update/_index.md#upgrade-gitlab) for the best experience.
+{{< /alert >}}
+
Use GitLab Duo Code Suggestions to write code more efficiently by using generative AI to suggest code while you're developing.
Before you start using Code Suggestions, decide if you want to use the default GitLab-hosted LLM to manage Code Suggestions requests, or [deploy a self-hosted model](../../../../administration/gitlab_duo_self_hosted/_index.md). Self-hosted models maximize security and privacy by making sure nothing is sent to an external model.
@@ -57,7 +67,11 @@ To use Code Suggestions:
## View multiple code suggestions
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues/1325) in GitLab 17.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues/1325) in GitLab 17.1.
+
+{{< /history >}}
For a code completion suggestion in VS Code, multiple suggestion options
might be available. To view all available suggestions:
@@ -151,18 +165,25 @@ For more information, see [epic 57](https://gitlab.com/groups/gitlab-org/editor-
### Using open files as context
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464767) in GitLab 17.1 [with a flag](../../../../administration/feature_flags.md) named `advanced_context_resolver`. Disabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462750) in GitLab 17.1 [with a flag](../../../../administration/feature_flags.md) named `code_suggestions_context`. Disabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/issues/276) in GitLab Workflow for VS Code 4.20.0.
-> - [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/issues/462) in GitLab Duo for JetBrains 2.7.0.
-> - [Added](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim/-/merge_requests/152) to the GitLab Neovim plugin on July 16, 2024.
-> - Feature flags `advanced_context_resolver` and `code_suggestions_context` enabled on GitLab.com in GitLab 17.2.
-> - Feature flags `advanced_context_resolver` and `code_suggestions_context` [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161538) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464767) in GitLab 17.1 [with a flag](../../../../administration/feature_flags.md) named `advanced_context_resolver`. Disabled by default.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462750) in GitLab 17.1 [with a flag](../../../../administration/feature_flags.md) named `code_suggestions_context`. Disabled by default.
+- [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/issues/276) in GitLab Workflow for VS Code 4.20.0.
+- [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/issues/462) in GitLab Duo for JetBrains 2.7.0.
+- [Added](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim/-/merge_requests/152) to the GitLab Neovim plugin on July 16, 2024.
+- Feature flags `advanced_context_resolver` and `code_suggestions_context` enabled on GitLab.com in GitLab 17.2.
+- Feature flags `advanced_context_resolver` and `code_suggestions_context` [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161538) in GitLab 17.4.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
As well as using files from your repository, Code Suggestions can use the files
open in tabs in your IDE as context.
@@ -183,9 +204,9 @@ Prerequisites:
To confirm that files open in tabs are being used as context:
-::Tabs
+{{< tabs >}}
-:::TabTitle Visual Studio Code
+{{< tab title="Visual Studio Code" >}}
1. On the top bar, go to **Code > Settings > Extensions**.
1. Search for GitLab Workflow in the list, and select the gear icon.
@@ -193,7 +214,9 @@ To confirm that files open in tabs are being used as context:
1. In your **User** settings, under **GitLab › Duo Code Suggestions: Open Tabs Context**,
select **Use the contents of open tabs as context**.
-:::TabTitle JetBrains IDEs
+{{< /tab >}}
+
+{{< tab title="JetBrains IDEs" >}}
1. Go to your IDE's top menu bar and select **Settings**.
1. On the left sidebar, expand **Tools**, then select **GitLab Duo**.
@@ -201,7 +224,9 @@ To confirm that files open in tabs are being used as context:
1. Under **Code Completion**, select **Send open tabs as context**.
1. Select **OK** or **Save**.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Use files open in tabs as context
@@ -284,7 +309,11 @@ Other supported IDEs offer slower response times and will return the generated c
### Direct and indirect connections
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462791) in GitLab 17.2 [with a flag](../../../../administration/feature_flags.md) named `code_suggestions_direct_access`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462791) in GitLab 17.2 [with a flag](../../../../administration/feature_flags.md) named `code_suggestions_direct_access`. Disabled by default.
+
+{{< /history >}}
By default, code completion requests are sent from the IDE directly to the AI gateway to minimize the latency.
For this direct connection to work, the IDE must be able to connect to `https://cloud.gitlab.com:443`. If this is not
@@ -298,9 +327,9 @@ Prerequisites:
- You must be an administrator for the GitLab Self-Managed instance.
-::Tabs
+{{< tabs >}}
-:::TabTitle In 17.4 and later
+{{< tab title="In 17.4 and later" >}}
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Settings > General**.
@@ -310,7 +339,9 @@ Prerequisites:
- To disable direct connections for all users, select **Indirect connections through the GitLab self-managed instance**.
1. Select **Save changes**.
-:::TabTitle In 17.3 and earlier
+{{< /tab >}}
+
+{{< tab title="In 17.3 and earlier" >}}
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Settings > General**.
@@ -319,7 +350,9 @@ Prerequisites:
- To enable direct connections and minimize latency for code completion requests, clear the **Disable direct connections for code suggestions** checkbox.
- To disable direct connections, select the **Disable direct connections for code suggestions** checkbox.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
## Feedback
diff --git a/doc/user/project/repository/code_suggestions/repository_xray.md b/doc/user/project/repository/code_suggestions/repository_xray.md
index ba110287dfa10ddebc0c6cbcdb287188cc36ae7c..96cc032373622a48e1a4b9e0b680eabf9ab8d1de 100644
--- a/doc/user/project/repository/code_suggestions/repository_xray.md
+++ b/doc/user/project/repository/code_suggestions/repository_xray.md
@@ -2,16 +2,23 @@
stage: Create
group: Code Creation
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
-description: "Repository X-Ray gives Code Suggestions more insight into your project's codebase and dependencies."
+description: Repository X-Ray gives Code Suggestions more insight into your project's codebase and dependencies.
title: Repository X-Ray
---
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12060) in GitLab 16.7.
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12060) in GitLab 16.7.
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+
+{{< /history >}}
Repository X-Ray automatically enriches:
@@ -28,12 +35,19 @@ By understanding the libraries and other dependencies in use, Repository X-Ray h
tailor suggestions to match the coding patterns, styles, and technologies used in the project. This results
in code suggestions that integrate more seamlessly and follow best practices for the given stack.
-NOTE:
+{{< alert type="note" >}}
+
Repository X-Ray only enhances code generation requests and not code completion requests.
+{{< /alert >}}
+
## How Repository X-Ray works
-> - Maximum number of libraries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/500365) in GitLab 17.6.
+{{< history >}}
+
+- Maximum number of libraries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/500365) in GitLab 17.6.
+
+{{< /history >}}
When you push a new commit to your project's default branch, Repository X-Ray triggers a background job.
This job scans and parses the applicable configuration files in your repository.
@@ -46,8 +60,12 @@ When a code generation request is made, a maximum of 300 libraries from the pars
## Enable Repository X-Ray
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/476180) in GitLab 17.4 [with a flag](../../../feature_flags.md) named `ai_enable_internal_repository_xray_service`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/483928) in GitLab 17.6. Feature flag `ai_enable_internal_repository_xray_service` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/476180) in GitLab 17.4 [with a flag](../../../feature_flags.md) named `ai_enable_internal_repository_xray_service`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/483928) in GitLab 17.6. Feature flag `ai_enable_internal_repository_xray_service` removed.
+
+{{< /history >}}
The Repository X-Ray service is automatically enabled if your project has access to [GitLab Duo Code Suggestions](_index.md).
@@ -80,10 +98,13 @@ The Repository X-Ray searches a maximum of two directory levels from the reposit
## Enable Repository X-Ray in your CI pipeline (deprecated)
-WARNING:
+{{< alert type="warning" >}}
+
This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/500146) in GitLab 17.6
and is planned for removal in 18.0. Use [Enable Repository X-Ray](#enable-repository-x-ray) instead.
+{{< /alert >}}
+
Prerequisites:
- You must have access to [GitLab Duo Code Suggestions](_index.md) in the project.
diff --git a/doc/user/project/repository/code_suggestions/set_up.md b/doc/user/project/repository/code_suggestions/set_up.md
index 22a82f01c41bd319e187a8772af13783643a78b9..e9608a518f74a424a17769ca000f767bc4e654d7 100644
--- a/doc/user/project/repository/code_suggestions/set_up.md
+++ b/doc/user/project/repository/code_suggestions/set_up.md
@@ -2,7 +2,7 @@
stage: Create
group: Code Creation
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
-description: "Set up Code Suggestions."
+description: Set up Code Suggestions.
title: Set up Code Suggestions
---
@@ -42,7 +42,7 @@ However, you can confirm that Code Suggestions is turned on.
To verify that Code Suggestions is turned on in VS Code:
1. In VS Code, go to **Settings > Extensions > GitLab Workflow**.
-1. Select **Manage** (**{settings}**).
+1. Select **Manage** ({{< icon name="settings" >}}).
1. Ensure that **GitLab › Duo Code Suggestions: Enabled** is selected.
1. Optional. For **GitLab › Duo Code Suggestions: Enabled Supported Languages**,
select the languages you want to suggest or generate code for.
@@ -67,7 +67,11 @@ To verify that Code Suggestions is turned on in JetBrains IDEs:
#### Add a custom certificate for Code Suggestions
-> - [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/issues/561) in GitLab Duo 2.10.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/issues/561) in GitLab Duo 2.10.0.
+
+{{< /history >}}
GitLab Duo attempts to detect [trusted root certificates](https://www.jetbrains.com/help/idea/ssl-certificates.html)
without configuration on your part. If needed, configure your JetBrains IDE to allow the GitLab Duo plugin
@@ -114,8 +118,8 @@ For example, in Visual Studio:
| Icon | Status | Meaning |
| :--- | :----- | :------ |
-| **{tanuki-ai}** | **Ready** | You've configured and enabled GitLab Duo, and you're using a language that supports Code Suggestions. |
-| **{tanuki-ai-off}** | **Not configured** | You haven't entered a personal access token, or you're using a language that Code Suggestions doesn't support. |
+| {{< icon name="tanuki-ai" >}} | **Ready** | You've configured and enabled GitLab Duo, and you're using a language that supports Code Suggestions. |
+| {{< icon name="tanuki-ai-off" >}} | **Not configured** | You haven't entered a personal access token, or you're using a language that Code Suggestions doesn't support. |
|  | **Loading suggestion** | GitLab Duo is fetching Code Suggestions for you. |
|  | **Error** | GitLab Duo has encountered an error. |
@@ -123,15 +127,18 @@ For example, in Visual Studio:
The process for turning off Code Suggestions is different for each IDE.
-NOTE:
+{{< alert type="note" >}}
+
You cannot turn off code generation and code completion separately.
+{{< /alert >}}
+
### VS Code
To turn off Code Suggestions in VS Code:
1. Go to **Code > Settings > Extensions**.
-1. Select **Manage** (**{settings}**) **> Settings**.
+1. Select **Manage** ({{< icon name="settings" >}}) **> Settings**.
1. Clear the **GitLab Duo Code Suggestions** checkbox.
Instead, you can [set `gitlab.duoCodeSuggestions.enabled` to `false` in the VS Code `settings.json` file](../../../../editor_extensions/visual_studio_code/settings.md#extension-settings).
diff --git a/doc/user/project/repository/code_suggestions/supported_extensions.md b/doc/user/project/repository/code_suggestions/supported_extensions.md
index 29b9ceb94b5791776977ada9b90e8126c784492b..74f8f9af515eae257d55b55b6b964725bd7a5182 100644
--- a/doc/user/project/repository/code_suggestions/supported_extensions.md
+++ b/doc/user/project/repository/code_suggestions/supported_extensions.md
@@ -2,15 +2,22 @@
stage: Create
group: Code Creation
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
-description: "Code Suggestions supports multiple editors and languages."
+description: Code Suggestions supports multiple editors and languages.
title: Supported extensions and languages
---
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+
+{{< /history >}}
Code Suggestions is available in the following editor extensions and
for the following languages.
@@ -54,52 +61,62 @@ When working with these languages, Code Suggestions leverages [files open in tab
The following table provides more information on the languages Code Suggestions supports by default, and the IDEs.
-NOTE:
+{{< alert type="note" >}}
+
Code Suggestions works with other languages that are not in this table, but you must manually [add support for that language](#add-support-for-more-languages).
+{{< /alert >}}
+
| Language | Web IDE | VS Code | JetBrains IDEs | Visual Studio 2022 for Windows | Neovim |
|-------------------------------|----------------------------|---------------------------------------------------------------------------------------------|-----------------------|--------------------------------|--------------------------------------------------------------------------------------------------------|
-| C | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes |
-| C++ | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| C# | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| CSS | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| Go | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Google SQL | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| HAML | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| HTML | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| Java | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| JavaScript | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Kotlin | **{dotted-circle}** No | **{check-circle}** Yes <br><br>(Requires third-party extension providing Kotlin support) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Markdown | **{check-circle}** Yes |**{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No |
-| PHP | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Python | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Ruby | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Rust | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Scala | **{dotted-circle}** No | **{check-circle}** Yes <br><br>(Requires third-party extension providing Scala support) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Shell scripts (`bash` only) | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Svelte | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Swift | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| TypeScript | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-| Terraform | **{dotted-circle}** No | **{check-circle}** Yes <br><br>(Requires third-party extension providing Terraform support) | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes <br><br>(Requires third-party extension providing the `terraform` file type) |
-| Vue | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
-
-NOTE:
+| C | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| C++ | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| C# | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| CSS | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Go | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Google SQL | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| HAML | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| HTML | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| Java | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| JavaScript | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Kotlin | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes <br><br>(Requires third-party extension providing Kotlin support) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Markdown | {{< icon name="check-circle" >}} Yes |{{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No | {{< icon name="dotted-circle" >}} No |
+| PHP | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Python | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Ruby | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Rust | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Scala | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes <br><br>(Requires third-party extension providing Scala support) | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Shell scripts (`bash` only) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Svelte | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Swift | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| TypeScript | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+| Terraform | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes <br><br>(Requires third-party extension providing Terraform support) | {{< icon name="check-circle" >}} Yes | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes <br><br>(Requires third-party extension providing the `terraform` file type) |
+| Vue | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes |
+
+{{< alert type="note" >}}
+
Some languages are not supported in all JetBrains IDEs, or might require additional
plugin support. Refer to the JetBrains documentation for specifics on your IDE.
+{{< /alert >}}
+
Locally, you can add [more languages](#add-support-for-more-languages). For languages not listed in the table,
Code Suggestions might not function as expected.
## Manage languages for Code Suggestions
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/CHANGELOG.md#4210-2024-07-16) in GitLab Workflow for VS Code 4.21.0
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/CHANGELOG.md#4210-2024-07-16) in GitLab Workflow for VS Code 4.21.0
+
+{{< /history >}}
You can customize your coding experience in VS Code by enabling or disabling Code Suggestions for specific supported languages.
You can do this by editing your `settings.json` file directly, or from the VS Code user interface:
1. In VS Code, open the extension settings for **GitLab Workflow**:
1. On the top bar, go to **Code > Settings > Extensions**.
- 1. Search for **GitLab Workflow** in the list, and select **Manage** (**{settings}**).
+ 1. Search for **GitLab Workflow** in the list, and select **Manage** ({{< icon name="settings" >}}).
1. Select **Extension Settings**.
1. In your **User** settings, find the section titled **AI Assisted Code Suggestions: Enabled Supported Languages**.
1. To enable Code Suggestions for a language, select its checkbox.
@@ -114,9 +131,9 @@ for this language. On hover, it shows **Code Suggestions are disabled for this l
If your desired language doesn't have Code Suggestions available by default,
you can add support for your language locally.
-::Tabs
+{{< tabs >}}
-:::TabTitle Visual Studio Code
+{{< tab title="Visual Studio Code" >}}
Prerequisites:
@@ -132,7 +149,9 @@ To do this:
You need the **Identifier** for your languages in a later step.
1. In VS Code, open the extension settings for **GitLab Workflow**:
1. On the top bar, go to **Code > Settings > Extensions**.
- 1. Search for **GitLab Workflow** in the list, and select **Manage** (**{settings}**).
+
+ 1. Search for **GitLab Workflow** in the list, and select **Manage** ({{< icon name="settings" >}}).
+
1. Select **Extension Settings**.
1. In your **User** settings, find
**GitLab › Ai Assisted Code Suggestions: Additional Languages** and select **Add Item**.
@@ -140,7 +159,9 @@ To do this:
lowercase, like `html` or `powershell`. Don't add leading periods from file suffixes to each identifier.
1. Select **OK**.
-:::TabTitle JetBrains IDEs
+{{< /tab >}}
+
+{{< tab title="JetBrains IDEs" >}}
Prerequisites:
@@ -161,4 +182,6 @@ To do this:
like `html,powershell,latex`, and don't add leading periods to each identifier.
1. Select **OK**.
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/user/project/repository/code_suggestions/troubleshooting.md b/doc/user/project/repository/code_suggestions/troubleshooting.md
index cd65aec23a4fb025a42d1fdff77a49e1e20bd926..be9fbe8c95b68939eb71cd3c41a8e3afbef6572f 100644
--- a/doc/user/project/repository/code_suggestions/troubleshooting.md
+++ b/doc/user/project/repository/code_suggestions/troubleshooting.md
@@ -2,15 +2,22 @@
stage: Create
group: Code Creation
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
-description: "Troubleshooting tips for common problems in Code Suggestions."
+description: Troubleshooting tips for common problems in Code Suggestions.
title: Troubleshooting Code Suggestions
---
-DETAILS:
-**Tier:** Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+- Tier: Premium with GitLab Duo Pro, Ultimate with GitLab Duo Pro or Enterprise - [Start a trial](https://about.gitlab.com/solutions/gitlab-duo-pro/sales/?type=free-trial)
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Changed to require GitLab Duo add-on in GitLab 17.6 and later.
+
+{{< /history >}}
When working with GitLab Duo Code Suggestions, you might encounter the following issues.
@@ -69,7 +76,7 @@ For non-Code Suggestions troubleshooting for VS Code, see [Troubleshooting the G
If you are on GitLab Self-Managed, ensure that Code Suggestions for the [GitLab Web IDE](../../web_ide/_index.md) is enabled. The same settings apply to VS Code as local IDE.
1. On the left sidebar, select **Extensions > GitLab Workflow**.
-1. Select **Settings** (**{settings}**), and then select **Extension Settings**.
+1. Select **Settings** ({{< icon name="settings" >}}), and then select **Extension Settings**.
1. In **GitLab > Duo Code Suggestions**, select the **GitLab Duo Code Suggestions**
checkbox.
@@ -107,7 +114,11 @@ as taking longer to resolve. To disable streaming:
### Error: Direct connection fails
-> - Direct connection [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13252) in GitLab 17.2.
+{{< history >}}
+
+- Direct connection [introduced](https://gitlab.com/groups/gitlab-org/-/epics/13252) in GitLab 17.2.
+
+{{< /history >}}
To reduce latency, the Workflow extension tries to send suggestion completion requests directly to GitLab Cloud Connector,
bypassing the GitLab instance. This network connection does not use the proxy and certificate settings of the VS Code extension.
diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md
index ce27ccda3449a8fc9bc51b0975ff881a8ed7ea40..2338a07a0fe5fc753b7e26901814bd1c5601ea31 100644
--- a/doc/user/project/repository/file_finder.md
+++ b/doc/user/project/repository/file_finder.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'files/_index.md'
-remove_date: '2025-06-11'
+redirect_to: files/_index.md
+remove_date: "2025-06-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/project/repository/files/_index.md b/doc/user/project/repository/files/_index.md
index 3b33e5333ed8b99bf9de7fcf82cb87a7ef7f6691..57c81a8807dcee94175f64d9dff90d4afa34a4eb 100644
--- a/doc/user/project/repository/files/_index.md
+++ b/doc/user/project/repository/files/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Remote Development
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
-description: "Search for files in your GitLab repository directly from the GitLab user interface."
+description: Search for files in your GitLab repository directly from the GitLab user interface.
title: File management
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The GitLab UI extends the history and tracking capabilities of Git with user-friendly
features in your browser. You can:
@@ -76,10 +79,13 @@ To render an OpenAPI file:
1. Select **Display rendered file**.
1. To display the `operationId` in the operations list, add `displayOperationId=true` to the query string.
-NOTE:
+{{< alert type="note" >}}
+
When `displayOperationId` is present in the query string and has _any_ value, it
evaluates to `true`. This behavior matches the default behavior of Swagger.
+{{< /alert >}}
+
## View Git records for a file
Historical information about files in your repository is available in the GitLab UI:
@@ -90,7 +96,11 @@ Historical information about files in your repository is available in the GitLab
## Search for a file
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148025) to a dialog in GitLab 16.11.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148025) to a dialog in GitLab 16.11.
+
+{{< /history >}}
Use the file finder to search directly from the GitLab UI for a file in your repository.
The file finder uses fuzzy search and highlights results as you type.
diff --git a/doc/user/project/repository/files/csv.md b/doc/user/project/repository/files/csv.md
index 0876e8a6a6f106b2c59c54aae0e71ee3c61d2381..8bb3d263a9b2f16f0e201c90deecb606a21c27ba 100644
--- a/doc/user/project/repository/files/csv.md
+++ b/doc/user/project/repository/files/csv.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "How comma-separated values (CSV) files display in GitLab projects."
+description: How comma-separated values (CSV) files display in GitLab projects.
title: CSV files
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A comma-separated values (CSV) file is a delimited text file that uses a comma to separate values.
Each line of the file is a data record. Each record consists of one or more fields, separated by
diff --git a/doc/user/project/repository/files/geojson.md b/doc/user/project/repository/files/geojson.md
index ee88721ebb290199e5bedfbca02bb1e059e67016..1a5d0af40fe4f1dd4aa89d125c1fdca357daebb2 100644
--- a/doc/user/project/repository/files/geojson.md
+++ b/doc/user/project/repository/files/geojson.md
@@ -2,15 +2,22 @@
stage: Create
group: Source Code
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
-description: "How GeoJSON files are rendered when viewed in GitLab projects."
+description: How GeoJSON files are rendered when viewed in GitLab projects.
title: GeoJSON files
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14134) in GitLab 16.1.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14134) in GitLab 16.1.
+
+{{< /history >}}
A GeoJSON file is a format for encoding geographical data structures using JavaScript Object Notation (JSON).
It is commonly used for representing geographic features, such as points, lines, and polygons, along with their associated attributes.
diff --git a/doc/user/project/repository/files/git_attributes.md b/doc/user/project/repository/files/git_attributes.md
index cbc6373a775772cd379fad3abb04e1b1e1d7196a..1f3c73c087f093dbd8a362e302a3dbd7855d9007 100644
--- a/doc/user/project/repository/files/git_attributes.md
+++ b/doc/user/project/repository/files/git_attributes.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Define custom Git attributes for your GitLab project to set options for file handling, display, locking, and storage."
+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
+description: Define custom Git attributes for your GitLab project to set options for file handling, display, locking, and storage.
title: Git attributes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab supports defining custom Git attributes in a `.gitattributes` file in the
root directory of your repository. Use the `.gitattributes` file to declare changes
@@ -62,11 +65,18 @@ syntax highlighting files and diffs. For more information, see
## Custom merge drivers
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - Configuring custom merge drivers through GitLab introduced in GitLab 15.10.
+{{< history >}}
+
+- Configuring custom merge drivers through GitLab introduced in GitLab 15.10.
+
+{{< /history >}}
GitLab Self-Managed administrators can define [custom merge drivers](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver)
in a GitLab configuration file, then use the custom merge drivers in a Git `.gitattributes` file. Custom merge drivers are not supported on GitLab.com.
@@ -84,9 +94,9 @@ GitLab.
How to configure a custom merge driver depends on the type of installation.
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb`.
1. Add configuration similar to the following:
@@ -104,7 +114,9 @@ How to configure a custom merge driver depends on the type of installation.
}
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `gitaly.toml`.
1. Add configuration similar to the following:
@@ -115,7 +127,9 @@ How to configure a custom merge driver depends on the type of installation.
value = "true"
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
In this example, during a merge, Git uses the `driver` value as the command to execute. In
this case, because we are using [`true`](https://man7.org/linux/man-pages/man1/true.1.html)
diff --git a/doc/user/project/repository/files/git_blame.md b/doc/user/project/repository/files/git_blame.md
index 2de44a8fbae812d94de579be9a07957028f45c8e..9b46638abe954090bc486e94450e8e89bdb32184 100644
--- a/doc/user/project/repository/files/git_blame.md
+++ b/doc/user/project/repository/files/git_blame.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Documentation on Git file blame."
+description: Documentation on Git file blame.
title: Git file blame
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Git blame](https://git-scm.com/docs/git-blame) provides more information
about every line in a file, including the last modified time, author, and
@@ -16,7 +19,11 @@ commit hash.
## View blame for a file
-> - Viewing blame directly in the file view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/430950) in GitLab 16.7 [with flag](../../../../administration/feature_flags.md) named `inline_blame`. Disabled by default.
+{{< history >}}
+
+- Viewing blame directly in the file view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/430950) in GitLab 16.7 [with flag](../../../../administration/feature_flags.md) named `inline_blame`. Disabled by default.
+
+{{< /history >}}
Prerequisites:
@@ -50,7 +57,7 @@ To see earlier revisions of a specific line:
1. Select **Code > Repository**.
1. Select the file you want to review.
1. In the upper-right corner, select **Blame**, and go to the line you want to see.
-1. Select **View blame prior to this change** (**{doc-versions}**)
+1. Select **View blame prior to this change** ({{< icon name="doc-versions" >}})
until you've found the changes you're interested in viewing.
## Related topics
diff --git a/doc/user/project/repository/files/git_history.md b/doc/user/project/repository/files/git_history.md
index 23e0c7cc4dfbf690f31391ad8655367add29be66..5ab7754e126dd71c902f986c4e83a60318d2faa6 100644
--- a/doc/user/project/repository/files/git_history.md
+++ b/doc/user/project/repository/files/git_history.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "How to view a file's Git history in GitLab."
+description: How to view a file's Git history in GitLab.
title: Git file history
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Git file history provides information about the commit history associated
with a file:
@@ -23,8 +26,8 @@ Each commit shows:
- The date of the commit, in time-ago format. To see the precise date and time of
the commit, hover over the date.
- If the [commit is signed](../signed_commits/_index.md), a **Verified** badge.
-- The commit SHA. GitLab shows the first 8 characters. Select **Copy commit SHA** (**{copy-to-clipboard}**) to copy the entire SHA.
-- A link to **browse** (**{folder-open}**) the file as it appeared at the time of this commit.
+- The commit SHA. GitLab shows the first 8 characters. Select **Copy commit SHA** ({{< icon name="copy-to-clipboard" >}}) to copy the entire SHA.
+- A link to **browse** ({{< icon name="folder-open" >}}) the file as it appeared at the time of this commit.
GitLab retrieves the user name and email information from the
[Git configuration](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration)
@@ -49,7 +52,11 @@ To see a file's Git history in the UI:
## Limit history range of results
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423108) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423108) in GitLab 16.9.
+
+{{< /history >}}
When reviewing history for old files, or files with many commits, you can
limit the search results by date. Limiting the dates for commits helps fix
diff --git a/doc/user/project/repository/files/highlighting.md b/doc/user/project/repository/files/highlighting.md
index f60eb930cad6370756d3d206921e5a17a982cc30..36f0beec8c775678243a97279033661aae762291 100644
--- a/doc/user/project/repository/files/highlighting.md
+++ b/doc/user/project/repository/files/highlighting.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Syntax highlighting helps you read files in your GitLab project more easily, and identify what files contain."
+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
+description: Syntax highlighting helps you read files in your GitLab project more easily, and identify what files contain.
title: Syntax Highlighting
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab provides syntax highlighting on all files through [Highlight.js](https://github.com/highlightjs/highlight.js/) and the
[Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language
@@ -16,16 +19,22 @@ to use based on the file extension, which most of the time is sufficient.
The paths here use the [`.gitattributes` interface](https://git-scm.com/docs/gitattributes) in Git.
-NOTE:
+{{< alert type="note" >}}
+
The [Web IDE](../../web_ide/_index.md) and [Snippets](../../../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/)
for text editing, which internally uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html)
library for syntax highlighting.
+{{< /alert >}}
+
## Override syntax highlighting for a file type
-NOTE:
+{{< alert type="note" >}}
+
The Web IDE [does not support `.gitattribute` files](https://gitlab.com/gitlab-org/gitlab/-/issues/22014).
+{{< /alert >}}
+
To override syntax highlighting for a file type:
1. If a `.gitattributes` file does not exist in the root directory of your project,
diff --git a/doc/user/project/repository/files/jupyter_notebooks/_index.md b/doc/user/project/repository/files/jupyter_notebooks/_index.md
index 42d69b0bd6728a0b88ce09f96637c5989cebe327..451a980b22855121b1f941e0727b01cd65dbe508 100644
--- a/doc/user/project/repository/files/jupyter_notebooks/_index.md
+++ b/doc/user/project/repository/files/jupyter_notebooks/_index.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "GitLab projects display Jupyter Notebook files as clean, human-readable files instead of raw files."
+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
+description: GitLab projects display Jupyter Notebook files as clean, human-readable files instead of raw files.
title: Jupyter Notebook files
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[Jupyter Notebook](https://jupyter.org/) (previously, IPython Notebook) files are used for
interactive computing in many fields. They contain a complete record of the
@@ -29,8 +32,12 @@ GitLab.
## Cleaner diffs and raw diffs
-> - [Reintroduced toggle](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85079) in GitLab 15.0 [with a flag](../../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 15.6. Feature flag `ipynb_semantic_diff` removed.
+{{< history >}}
+
+- [Reintroduced toggle](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85079) in GitLab 15.0 [with a flag](../../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 15.6. Feature flag `ipynb_semantic_diff` removed.
+
+{{< /history >}}
When commits include changes to Jupyter Notebook files, GitLab:
diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md
index b61f1343b3136911bba9b25d2c640c50d8864883..3e873de8ebd7586b75f76aa3c9d08efcf2cd89ca 100644
--- a/doc/user/project/repository/forking_workflow.md
+++ b/doc/user/project/repository/forking_workflow.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Fork a Git repository when you want to contribute changes back to an upstream repository you don't have permission to contribute to directly."
+description: Fork a Git repository when you want to contribute changes back to an upstream repository you don't have permission to contribute to directly.
title: Forks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A fork is a personal copy of another Git repository, placed in the namespace of your choice.
Your copy contains the upstream repository's content, including all branches, tags,
@@ -27,11 +30,15 @@ use a personal fork of a public repository.
## Create a fork
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24894) in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24894) in GitLab 16.6.
+
+{{< /history >}}
To fork an existing project in GitLab:
-1. On the project's homepage, in the upper-right corner, select **Fork** (**{fork}**).
+1. On the project's homepage, in the upper-right corner, select **Fork** ({{< icon name="fork" >}}).
1. Optional. Edit the **Project name**.
1. For **Project URL**, select the [namespace](../../namespace/_index.md)
your fork should belong to.
@@ -70,8 +77,12 @@ or the command line. GitLab Premium and Ultimate tiers can also automate updates
### From the UI
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 16.0. Feature flag `synchronize_fork` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 16.0. Feature flag `synchronize_fork` removed.
+
+{{< /history >}}
Prerequisites:
@@ -82,7 +93,7 @@ To update your fork from the GitLab UI:
1. On the left sidebar, select **Search or go to**.
1. Select **View all my projects**.
1. Select the fork you want to update.
-1. Below the dropdown list for branch name, find the **Forked from** (**{fork}**)
+1. Below the dropdown list for branch name, find the **Forked from** ({{< icon name="fork" >}})
information box to determine if your fork is ahead, behind, or both. In this example,
the fork is behind the upstream repository:
@@ -114,9 +125,12 @@ To update your fork from the command line, follow the instruction in
### With repository mirroring
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A fork can be configured as a mirror of the upstream if all these conditions are met:
@@ -129,9 +143,12 @@ A fork can be configured as a mirror of the upstream if all these conditions are
This method updates your fork once per hour, with no manual `git pull` required.
For instructions, read [Configure pull mirroring](mirror/pull.md#configure-pull-mirroring).
-WARNING:
+{{< alert type="warning" >}}
+
With mirroring, before approving a merge request, you are asked to sync. You should automate it.
+{{< /alert >}}
+
## Merge changes back upstream
When you are ready to send your code back to the upstream repository, create a new merge request as
@@ -147,11 +164,14 @@ Prerequisites:
- You must be a project owner to unlink a fork.
-WARNING:
+{{< alert type="warning" >}}
+
If you remove a fork relationship, you can't send merge requests to the source.
If anyone has forked your repository, their fork also loses the relationship.
To restore the fork relationship, [use the API](../../../api/project_forks.md#create-a-fork-relationship-between-projects).
+{{< /alert >}}
+
To remove a fork relationship:
1. On the left sidebar, select **Search or go to** and find your project.
diff --git a/doc/user/project/repository/mirror/_index.md b/doc/user/project/repository/mirror/_index.md
index 7679783690a2e9932b84bd1d56452915fa4e52c6..b9c65203001c94e8ecce113aab35f01231c4852a 100644
--- a/doc/user/project/repository/mirror/_index.md
+++ b/doc/user/project/repository/mirror/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Use repository mirroring to push or pull the contents of a Git repository into another repository."
+description: Use repository mirroring to push or pull the contents of a Git repository into another repository.
title: Repository mirroring
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can _mirror_ a repository to and from external sources. You can select which repository
serves as the source. Branches, tags, and commits are synced automatically.
@@ -103,14 +106,21 @@ To use this option, select **Only mirror protected branches** when you create a
### Mirror specific branches
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - Mirroring branches matching a regex as an option in API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default.
-> - Option in the project setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102499) in GitLab 15.9.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/410354) in GitLab 16.2. Feature flag `mirror_only_branches_match_regex` removed.
+- Mirroring branches matching a regex as an option in API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default.
+- Option in the project setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102499) in GitLab 15.9.
+- [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/410354) in GitLab 16.2. Feature flag `mirror_only_branches_match_regex` removed.
+
+{{< /history >}}
To mirror only branches with names matching an [re2 regular expression](https://github.com/google/re2/wiki/Syntax),
enter a regular expression into the **Mirror specific branches** field. Branches with names that
@@ -126,9 +136,12 @@ You can also manually trigger an update:
- According to [the pull mirroring interval limit](../../../../administration/instance_limits.md#pull-mirroring-interval)
set by the administrator on GitLab Self-Managed instances.
-NOTE:
+{{< alert type="note" >}}
+
[GitLab Silent Mode](../../../../administration/silent_mode/_index.md) disables both push and pull updates.
+{{< /alert >}}
+
### Force an update
While mirrors are scheduled to update automatically, you can force an immediate update unless:
@@ -145,7 +158,7 @@ Prerequisites:
1. Select **Settings > Repository**.
1. Expand **Mirroring repositories**.
1. Scroll to **Mirrored repositories** and identify the mirror to update.
-1. Select **Update now** (**{retry}**).
+1. Select **Update now** ({{< icon name="retry" >}}).
## Authentication methods for mirrors
@@ -186,7 +199,7 @@ needs this key to establish trust with your GitLab repository. To copy your SSH
1. Select **Settings > Repository**.
1. Expand **Mirroring repositories**.
1. Scroll to **Mirrored repositories**.
-1. Identify the correct repository, and select **Copy SSH public key** (**{copy-to-clipboard}**).
+1. Identify the correct repository, and select **Copy SSH public key** ({{< icon name="copy-to-clipboard" >}}).
1. Add the public SSH key to the other repository's configuration:
- If the other repository is hosted on GitLab, add the public SSH key
as a [deploy key](../../deploy_keys/_index.md).
@@ -198,10 +211,13 @@ If you must change the key at any time, you can remove and re-add the mirror
to generate a new key. Update the other repository with the new
key to keep the mirror running.
-NOTE:
+{{< alert type="note" >}}
+
The generated keys are stored in the GitLab database, not in the file system. Therefore,
SSH public key authentication for mirrors cannot be used in a pre-receive hook.
+{{< /alert >}}
+
### Verify a host key
When using a host key, always verify the fingerprints match what you expect.
diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md
index 5c03431434b55c8dfcbede0339edb12e43fef54d..d55ea4f1c3b83e9ecf7cbbd1f28ffba52585ef4f 100644
--- a/doc/user/project/repository/mirror/bidirectional.md
+++ b/doc/user/project/repository/mirror/bidirectional.md
@@ -2,19 +2,29 @@
stage: Create
group: Source Code
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
-description: "Create bidirectional mirrors to push and pull changes between two Git repositories."
+description: Create bidirectional mirrors to push and pull changes between two Git repositories.
title: Bidirectional mirroring
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Moved to GitLab Premium in 13.9.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
Bidirectional mirroring may cause conflicts.
+{{< /alert >}}
+
Bidirectional [mirroring](_index.md) configures two repositories to both pull from,
and push to, each other. There is no guarantee that either repository can update
without errors.
@@ -65,10 +75,13 @@ To test the integration, select **Test** and confirm GitLab doesn't return an er
## Prevent conflicts by using a pre-receive hook
-WARNING:
+{{< alert type="warning" >}}
+
This solution negatively affects the performance of Git push operations, because
they are proxied to the upstream Git repository.
+{{< /alert >}}
+
In this configuration, one Git repository acts as the authoritative upstream, and
the other as downstream. This server-side `pre-receive` hook accepts a push only
after first pushing the commit to the upstream repository. Install this hook on
@@ -144,16 +157,26 @@ This sample has a few limitations:
## Mirror with Perforce Helix with Git Fusion
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
-> - Moved to GitLab Premium in 13.9.
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
Bidirectional mirroring should not be used as a permanent configuration. Refer to
[Migrating from Perforce Helix](../../import/perforce.md) for alternative migration approaches.
+{{< /alert >}}
+
[Git Fusion](https://www.perforce.com/manuals/git-fusion/#Git-Fusion/section_avy_hyc_gl.html) provides a Git interface
to [Perforce Helix](https://www.perforce.com/products). GitLab can use the Perforce Helix
interface to bidirectionally mirror projects. It can help when migrating from Perforce Helix
diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md
index c67733e287b15fc955aca969d979f28015d56f97..ec63faf292a049bdc45ea5c700a4cb45e5835691 100644
--- a/doc/user/project/repository/mirror/pull.md
+++ b/doc/user/project/repository/mirror/pull.md
@@ -2,15 +2,22 @@
stage: Create
group: Source Code
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
-description: "Create a pull mirror to pull changes from a remote repository into GitLab, and keep your copy of it up-to-date."
+description: Create a pull mirror to pull changes from a remote repository into GitLab, and keep your copy of it up-to-date.
title: Pull from a remote repository
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Moved to GitLab Premium in 13.9.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
You can use the GitLab interface to browse the content and activity of a repository,
even if it isn't hosted on GitLab. Create a pull [mirror](_index.md) to copy the
@@ -34,11 +41,14 @@ local repository, GitLab stops updating the branch. This prevents data loss.
Deleted branches and tags in the upstream repository are not reflected in the
downstream repository.
-NOTE:
+{{< alert type="note" >}}
+
Items deleted from the downstream pull mirror repository, but still in the upstream repository,
are restored upon the next pull. For example: a branch deleted _only_ in the mirrored repository
reappears after the next pull.
+{{< /alert >}}
+
## How pull mirroring works
After you configure a GitLab repository as a pull mirror:
@@ -73,10 +83,13 @@ Prerequisites:
1. Expand **Mirroring repositories**.
1. Enter the **Git repository URL**.
- NOTE:
- To mirror the `gitlab` repository, use `gitlab.com:gitlab-org/gitlab.git`
+ {{< alert type="note" >}}
+
+To mirror the `gitlab` repository, use `gitlab.com:gitlab-org/gitlab.git`
or `https://gitlab.com/gitlab-org/gitlab.git`.
+ {{< /alert >}}
+
1. In **Mirror direction**, select **Pull**.
1. In **Authentication method**, select your authentication method. For more information, see
[Authentication methods for mirrors](_index.md#authentication-methods-for-mirrors).
@@ -88,18 +101,29 @@ Prerequisites:
### Overwrite diverged branches
-> - Moved to GitLab Premium in 13.9.
+{{< history >}}
+
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
To always update your local branches with remote versions, even if they have
diverged from the remote, select **Overwrite diverged branches** when you
create a mirror.
-WARNING:
+{{< alert type="warning" >}}
+
For mirrored branches, enabling this option results in the loss of local changes.
+{{< /alert >}}
+
### Trigger pipelines for mirror updates
-> - Moved to GitLab Premium in 13.9.
+{{< history >}}
+
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
You can configure your mirror to automatically trigger pipelines when
the remote repository updates branches or tags. Before you enable this feature:
@@ -111,7 +135,11 @@ the remote repository updates branches or tags. Before you enable this feature:
## Trigger an update by using the API
-> - moved to GitLab Premium in 13.9.
+{{< history >}}
+
+- moved to GitLab Premium in 13.9.
+
+{{< /history >}}
Pull mirroring uses polling to detect new branches and commits added upstream,
often minutes afterwards. You can notify GitLab using an
@@ -123,7 +151,11 @@ For more information, read
## Fix hard failures when mirroring
-> - Moved to GitLab Premium in 13.9.
+{{< history >}}
+
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
After 14 consecutive unsuccessful retries, the mirroring process is marked as a hard failure
and mirroring attempts stop. This failure is visible in either the:
diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md
index 2953b5e7e8e2efebe54b3f56932ba303717b6417..4ed5f2a64ec37377c854795b42ae23df5ab5c001 100644
--- a/doc/user/project/repository/mirror/push.md
+++ b/doc/user/project/repository/mirror/push.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Create a push mirror to passively receive changes from an upstream repository."
+description: Create a push mirror to passively receive changes from an upstream repository.
title: Push mirroring
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
A _push mirror_ is a downstream repository that [mirrors](_index.md) the commits made
to the upstream repository. Push mirrors passively receive copies of the commits made to the
@@ -101,7 +104,7 @@ The mirrored repository is listed. For example:
https://*****:*****@github.com/<your_github_group>/<your_github_project>.git
```
-The repository pushes shortly thereafter. To force a push, select **Update now** (**{retry}**).
+The repository pushes shortly thereafter. To force a push, select **Update now** ({{< icon name="retry" >}}).
## Set up a push mirror from GitLab to AWS CodeCommit
@@ -116,9 +119,12 @@ these tools to create a deployment:
- GitLab CI/CD pipelines.
- The AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy.
-NOTE:
+{{< alert type="note" >}}
+
GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved.
+{{< /alert >}}
+
To set up a mirror from GitLab to AWS CodeCommit:
1. In the AWS IAM console, create an IAM user.
@@ -152,10 +158,13 @@ To set up a mirror from GitLab to AWS CodeCommit:
1. Select the **Security credentials** tab.
1. Under **HTTPS Git credentials for AWS CodeCommit**, select **Generate credentials**.
- NOTE:
- This Git user ID and password is specific to communicating with CodeCommit. Do
+ {{< alert type="note" >}}
+
+This Git user ID and password is specific to communicating with CodeCommit. Do
not confuse it with the IAM user ID or AWS keys of this user.
+ {{< /alert >}}
+
1. Copy or download the special Git HTTPS user ID and password.
1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository.
1. Open your new repository, in the upper-right corner, select **Code > Clone HTTPS** (not **Clone HTTPS (GRC)**).
diff --git a/doc/user/project/repository/mirror/troubleshooting.md b/doc/user/project/repository/mirror/troubleshooting.md
index aad71c12f56db319b629beb19ded07d923fcfdc8..047b97469e987179d3b9db75bf3426235393322c 100644
--- a/doc/user/project/repository/mirror/troubleshooting.md
+++ b/doc/user/project/repository/mirror/troubleshooting.md
@@ -2,15 +2,18 @@
stage: Create
group: Source Code
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
-description: "Troubleshooting problems with repository mirroring for GitLab projects."
+description: Troubleshooting problems with repository mirroring for GitLab projects.
title: Troubleshooting repository mirroring
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-When mirroring fails, project maintainers can see a link similar to **{warning-solid}** **Pull mirroring failed 1 hour ago.**
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+When mirroring fails, project maintainers can see a link similar to {{< icon name="warning-solid" >}} **Pull mirroring failed 1 hour ago.**
on the project details page. Select this link to go directly to the mirroring settings,
where GitLab displays an **Error** badge for the mirrored repository. You can hover your mouse cursor
over the badge to display the text of the error:
@@ -172,9 +175,12 @@ Use case: If you have multiple users using their own GitHub credentials to set u
repository mirroring, mirroring breaks when people leave the company. Use this
script to migrate disparate mirroring users and tokens into a single service account:
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
svc_user = User.find_by(username: 'ourServiceUser')
token = 'githubAccessToken'
diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md
index 2546a6b23339448b7993ab12056df0217341c10f..f4b7f72a220c55f6241c0908d6161b5a2bb52f93 100644
--- a/doc/user/project/repository/push_rules.md
+++ b/doc/user/project/repository/push_rules.md
@@ -1,16 +1,23 @@
---
stage: Create
group: Source Code
-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"
-description: "Use push rules to control the content and format of Git commits your repository will accept. Set standards for commit messages, and block secrets or credentials from being added accidentally."
+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
+description: Use push rules to control the content and format of Git commits your repository will accept. Set standards for commit messages, and block secrets or credentials from being added accidentally.
title: Push rules
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Maximum regular expression length for push rules [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/411901) from 255 to 511 characters in GitLab 16.3.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Maximum regular expression length for push rules [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/411901) from 255 to 511 characters in GitLab 16.3.
+
+{{< /history >}}
Push rules are [`pre-receive` Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#:~:text=pre%2Dreceive,with%20the%20push.) you
can enable in a user-friendly interface. Push rules give you more control over what
@@ -65,9 +72,12 @@ for an existing project to match new global push rules:
Use these rules to validate users who make commits.
-NOTE:
+{{< alert type="note" >}}
+
These push rules apply only to commits and not [tags](tags/_index.md).
+{{< /alert >}}
+
- **Reject unverified users**: Users must have a [confirmed email address](../../../security/user_email_confirmation.md).
- **Check whether the commit author is a GitLab user**: The commit author and committer must have an email address that's been verified by GitLab.
- **Commit author's email**: Both the author and committer email addresses must match the regular expression.
@@ -105,7 +115,11 @@ Use these rules for your commit messages.
## Reject commits that aren't signed-off
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98810) in GitLab 15.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98810) in GitLab 15.5.
+
+{{< /history >}}
Commits signed with the [Developer Certificate of Origin](https://developercertificate.org/) (DCO)
certify the contributor wrote, or has the right to submit, the code contributed in that commit.
@@ -240,10 +254,13 @@ In Git, filenames include both the file's name, and all directories preceding th
When you `git push`, each filename in the push is compared to the regular expression
in **Prohibited filenames**.
-NOTE:
+{{< alert type="note" >}}
+
This feature uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax),
which does not support positive or negative lookaheads.
+{{< /alert >}}
+
The regular expression can:
- Match file names in any location in your repository.
@@ -340,9 +357,12 @@ or write a script to update each project using the [push rules API endpoint](../
For example, to enable **Check whether the commit author is a GitLab user** and **Do not allow users to remove Git tags with `git push`** checkboxes,
and create a filter for allowing commits from a specific email domain only through rails console:
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
``` ruby
Project.find_each do |p|
pr = p.push_rule || PushRule.new(project: p)
diff --git a/doc/user/project/repository/repository_size.md b/doc/user/project/repository/repository_size.md
index ee933dfffe4bd42f71bc74f1201a0e2645dbb187..b8c5db198e0f5b1710b63ac7a685e52679ea35c7 100644
--- a/doc/user/project/repository/repository_size.md
+++ b/doc/user/project/repository/repository_size.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "To remove unwanted large files from a Git repository and reduce its storage size, use the filter-repo command."
+description: To remove unwanted large files from a Git repository and reduce its storage size, use the filter-repo command.
title: Repository size
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
The size of a Git repository can significantly impact performance and storage costs.
It can differ slightly from one instance to another due to compression, housekeeping, and other factors.
@@ -69,10 +72,13 @@ This process:
- Does not specify commit signatures.
- Is irreversible.
-NOTE:
+{{< alert type="note" >}}
+
Information about commits, including file content, is cached in the database, and remains visible
even after they have been removed from the repository.
+{{< /alert >}}
+
### Clean up repository
Use this method to remove internal Git references and unreferenced objects from your repository.
@@ -86,10 +92,13 @@ This process:
- Recalculates repository size on disk.
- Is irreversible.
-WARNING:
+{{< alert type="warning" >}}
+
Removing internal Git references causes associated merge request commits, pipelines, and change
details to become unavailable.
+{{< /alert >}}
+
Prerequisites:
- The list of objects to remove. Use the [`git filter-repo`](https://github.com/newren/git-filter-repo)
@@ -116,10 +125,14 @@ GitLab sends an email notification with the recalculated repository size after t
### Remove blobs
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/450701) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `rewrite_history_ui`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/462999) in GitLab 17.2.
-> - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/462999) in GitLab 17.3.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472018) in GitLab 17.9. Feature flag `rewrite_history_ui` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/450701) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `rewrite_history_ui`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/462999) in GitLab 17.2.
+- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/462999) in GitLab 17.3.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/472018) in GitLab 17.9. Feature flag `rewrite_history_ui` removed.
+
+{{< /history >}}
A Git binary large object (blob) stores file contents without metadata.
Each blob has a unique SHA hash that represents a specific version of a file in the repository.
@@ -136,9 +149,12 @@ This process:
- Requires re-cloning of local repositories.
- Is irreversible.
-NOTE:
+{{< alert type="note" >}}
+
To replace strings with `***REMOVED***`, see [Redact information](../../../topics/git/undo.md#redact-information).
+{{< /alert >}}
+
Prerequisites:
- You must have the Owner role for the project
@@ -242,6 +258,9 @@ If you've reached the repository size limit:
- If you still can't push changes, contact your GitLab administrator to temporarily [increase the limit for your project](../../../administration/settings/account_and_limit_settings.md#repository-size-limit).
- As a last resort, create a new project and migrate your data.
-NOTE:
+{{< alert type="note" >}}
+
Deleting files in a new commit doesn't reduce repository size immediately, as earlier commits and blobs still exist.
To effectively reduce size, you must rewrite history using a tool like [`git filter-repo`](https://github.com/newren/git-filter-repo).
+
+{{< /alert >}}
diff --git a/doc/user/project/repository/signed_commits/_index.md b/doc/user/project/repository/signed_commits/_index.md
index b99f4fe13aa69d188b45419025025150d3cb4590..71fd09ad492143abdd83c5d3670617e535ebf9dd 100644
--- a/doc/user/project/repository/signed_commits/_index.md
+++ b/doc/user/project/repository/signed_commits/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Why you should sign your GitLab commits cryptographically, and how to verify signed commits."
+description: Why you should sign your GitLab commits cryptographically, and how to verify signed commits.
title: Signed commits
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
When you add a digital signature to your commit, you provide extra assurance that a commit
originated from you, rather than an impersonator. A digital signature is a cryptographic output
@@ -66,12 +69,19 @@ using the [Web Commits API](../../../../api/web_commits.md#get-public-signing-ke
### Use gitmailmap with verified commits
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425042) in GitLab 17.5 [with a flag](../../../../administration/feature_flags.md) named `check_for_mailmapped_commit_emails`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425042) in GitLab 17.5 [with a flag](../../../../administration/feature_flags.md) named `check_for_mailmapped_commit_emails`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
The [`gitmailmap`](https://git-scm.com/docs/gitmailmap) feature allows users to map author names and email addresses.
GitLab uses these email addresses to provide links to the commit author.
When using a `mailmap` author mapping, it's possible to have a verified commit with an unverified author email.
diff --git a/doc/user/project/repository/signed_commits/gpg.md b/doc/user/project/repository/signed_commits/gpg.md
index 0df5527a41826667ddbcf7689e79c132a002740d..fbcbd89fa6db31a94cddeb172c47fec15b8954d4 100644
--- a/doc/user/project/repository/signed_commits/gpg.md
+++ b/doc/user/project/repository/signed_commits/gpg.md
@@ -2,21 +2,27 @@
stage: Create
group: Source Code
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
-description: "Sign commits in your GitLab repository with GPG (GNU Privacy Guard) keys."
+description: Sign commits in your GitLab repository with GPG (GNU Privacy Guard) keys.
title: Sign commits with GPG
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can sign the commits you make in a GitLab repository with a
GPG ([GNU Privacy Guard](https://gnupg.org/)) key.
-NOTE:
+{{< alert type="note" >}}
+
GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and
implementations.
+{{< /alert >}}
+
For GitLab to consider a commit verified:
- The committer must have a GPG public/private key pair.
@@ -42,7 +48,7 @@ To view a user's public GPG key, you can either:
- Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key,
if the user has configured one, or a blank page for users without a configured GPG key.
- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper-right corner
- of the user's profile, select **View public GPG keys** (**{key}**).
+ of the user's profile, select **View public GPG keys** ({{< icon name="key" >}}).
This button is shown only if the user has configured the key.
## Configure commit signing
@@ -120,7 +126,7 @@ To add a GPG key to your user settings:
1. Sign in to GitLab.
1. On the left sidebar, select your avatar.
1. Select **Edit profile**.
-1. Select **GPG Keys** (**{key}**).
+1. Select **GPG Keys** ({{< icon name="key" >}}).
1. Select **Add new key**.
1. In **Key**, paste your _public_ key.
1. To add the key to your account, select **Add key**. GitLab shows the key's
@@ -232,7 +238,7 @@ To revoke a GPG key:
1. On the left sidebar, select your avatar.
1. Select **Edit profile**.
-1. Select **GPG Keys** (**{key}**).
+1. Select **GPG Keys** ({{< icon name="key" >}}).
1. Select **Revoke** next to the GPG key you want to delete.
## Remove a GPG key
@@ -247,8 +253,8 @@ To remove a GPG key from your account:
1. On the left sidebar, select your avatar.
1. Select **Edit profile**.
-1. Select **GPG Keys** (**{key}**).
-1. Select **Remove** (**{remove}**) next to the GPG key you want to delete.
+1. Select **GPG Keys** ({{< icon name="key" >}}).
+1. Select **Remove** ({{< icon name="remove" >}}) next to the GPG key you want to delete.
If you must unverify both future and past commits,
[revoke the associated GPG key](#revoke-a-gpg-key) instead.
@@ -302,5 +308,8 @@ If the password entry prompt doesn't appear:
- Restart your terminal.
- Run `source ~/.bashrc` or `source ~/.zshrc`.
-NOTE:
+{{< alert type="note" >}}
+
The exact steps may vary depending on your operating system and shell configuration.
+
+{{< /alert >}}
diff --git a/doc/user/project/repository/signed_commits/ssh.md b/doc/user/project/repository/signed_commits/ssh.md
index 3e7e9ab755babdf4db55a73ae16898563b3d1049..838bf2d20e0e1140dcb39a511463e14b22dbfabe 100644
--- a/doc/user/project/repository/signed_commits/ssh.md
+++ b/doc/user/project/repository/signed_commits/ssh.md
@@ -2,16 +2,23 @@
stage: Create
group: Source Code
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
-description: "Sign commits in your GitLab repository with SSH keys."
+description: Sign commits in your GitLab repository with SSH keys.
title: Sign commits with SSH keys
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384202) in GitLab 15.8. Feature flag `ssh_commit_signatures` removed.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384202) in GitLab 15.8. Feature flag `ssh_commit_signatures` removed.
+
+{{< /history >}}
When you sign commits with SSH keys, GitLab uses the SSH public keys associated
with your GitLab account to cryptographically verify the commit signature.
@@ -36,8 +43,11 @@ Prerequisites:
- Git 2.34.0 or newer.
- OpenSSH 8.1 or newer.
- NOTE:
- OpenSSH 8.7 has broken signing functionality. If you are on OpenSSH 8.7, upgrade to OpenSSH 8.8.
+ {{< alert type="note" >}}
+
+OpenSSH 8.7 has broken signing functionality. If you are on OpenSSH 8.7, upgrade to OpenSSH 8.8.
+
+ {{< /alert >}}
- A SSH key with the usage type of either **Authentication & Signing** or **Signing**.
The SSH key must be one of these types:
diff --git a/doc/user/project/repository/signed_commits/web_commits.md b/doc/user/project/repository/signed_commits/web_commits.md
index d1524d1731b1587ed4dd74ce4140fe2114962003..2b1e80f8398bfa32ce533fbd20fa7aa7167fd1ce 100644
--- a/doc/user/project/repository/signed_commits/web_commits.md
+++ b/doc/user/project/repository/signed_commits/web_commits.md
@@ -5,20 +5,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Signed commits from the GitLab UI
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19185) in GitLab 15.4.
-> - Displaying **Verified** badge for signed GitLab UI commits [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124218) in GitLab 16.3 [with a flag](../../../../administration/feature_flags.md) named `gitaly_gpg_signing`. Disabled by default.
-> - Verifying the signatures using multiple keys specified in `rotated_signing_keys` option [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6163) in GitLab 16.3.
-> - `gitaly_gpg_signing` feature flag [enabled by default](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6876) on GitLab Self-Managed and GitLab Dedicated in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19185) in GitLab 15.4.
+- Displaying **Verified** badge for signed GitLab UI commits [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124218) in GitLab 16.3 [with a flag](../../../../administration/feature_flags.md) named `gitaly_gpg_signing`. Disabled by default.
+- Verifying the signatures using multiple keys specified in `rotated_signing_keys` option [introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6163) in GitLab 16.3.
+- `gitaly_gpg_signing` feature flag [enabled by default](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/6876) on GitLab Self-Managed and GitLab Dedicated in GitLab 17.0.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
When you create a commit using the GitLab user interface, the commit is not pushed directly by you.
Instead, the commit is created on your behalf.
diff --git a/doc/user/project/repository/signed_commits/x509.md b/doc/user/project/repository/signed_commits/x509.md
index 3d11f8636a1ee52e6d37721dcbf7a4b009540133..fc9cc625a732af5b48f631b7841fb96a85a7325b 100644
--- a/doc/user/project/repository/signed_commits/x509.md
+++ b/doc/user/project/repository/signed_commits/x509.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Sign commits and tags in your GitLab repository with X.509 certificates."
+description: Sign commits and tags in your GitLab repository with X.509 certificates.
title: Sign commits and tags with X.509 certificates
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key
certificates issued by a public or private Public Key Infrastructure (PKI).
@@ -40,10 +43,13 @@ For a commit or tag to be *verified* by GitLab:
which is usually up to three years.
- The signing time is equal to, or later than, the commit time.
-NOTE:
+{{< alert type="note" >}}
+
If a Root CA or intermediate certificate in the trust chain expires and is renewed,
commits may temporarily show as "unverified" until you [re-verify them](#re-verify-commits).
+{{< /alert >}}
+
If a commit's status has already been determined and stored in the database,
use the Rake task [to re-check the status](../../../../raketasks/x509_signatures.md).
Refer to the [Troubleshooting section](#troubleshooting).
diff --git a/doc/user/project/repository/tags/_index.md b/doc/user/project/repository/tags/_index.md
index ce458f0eef3b1662149c0c1adc68e756fc47a9a5..811009110e086ea81df8cc40bdf5ea263145a84d 100644
--- a/doc/user/project/repository/tags/_index.md
+++ b/doc/user/project/repository/tags/_index.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Use Git tags to mark important points in a repository's history, and trigger CI/CD pipelines."
+description: Use Git tags to mark important points in a repository's history, and trigger CI/CD pipelines.
title: Tags
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
In Git, a tag marks an important point in a repository's history.
Git supports two types of tags:
@@ -34,14 +37,14 @@ In the GitLab UI, each tag displays:
-- The tag name. (**{tag}**)
+- The tag name. ({{< icon name="tag" >}})
- Optional. If the tag is [protected](../../protected_tags.md), a **protected** badge.
-- The commit SHA (**{commit}**), linked to the commit's contents.
+- The commit SHA ({{< icon name="commit" >}}), linked to the commit's contents.
- The commit's title and creation date.
-- Optional. A link to the release (**{rocket}**).
+- Optional. A link to the release ({{< icon name="rocket" >}}).
- Optional. If a pipeline has been run, the current pipeline status.
- Download links to the source code and artifacts linked to the tag.
-- A [**Create release**](../../releases/_index.md#create-a-release) (**{pencil}**) link.
+- A [**Create release**](../../releases/_index.md#create-a-release) ({{< icon name="pencil" >}}) link.
- A link to delete the tag.
## View tags for a project
@@ -53,11 +56,15 @@ To view all existing tags for a project:
## View tagged commits in the commits list
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10.
+
+{{< /history >}}
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Commits**.
-1. Commits with a tag are labeled with a tag icon (**{tag}**) and the name of the tag.
+1. Commits with a tag are labeled with a tag icon ({{< icon name="tag" >}}) and the name of the tag.
This example shows a commit tagged `v1.26.0`:
@@ -116,9 +123,12 @@ GitLab enforces these additional rules on all tags:
## Prevent tag deletion
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To prevent users from removing a tag with `git push`, create a [push rule](../push_rules.md).
diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md
index 51676e81ca5efd4dce9166b85c146562b882d0a6..e69b394ce892249bd980f90b12f9fcf73a71c752 100644
--- a/doc/user/project/repository/web_editor.md
+++ b/doc/user/project/repository/web_editor.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "Use the Web Editor to create, upload, and edit text files directly in the GitLab UI."
+description: Use the Web Editor to create, upload, and edit text files directly in the GitLab UI.
title: Web Editor
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can use the Web Editor directly in the GitLab UI without
cloning repositories locally or using the command line.
@@ -28,10 +31,13 @@ for Web Editor commits.
For changes to multiple files, use the [Web IDE](../web_ide/_index.md).
-NOTE:
+{{< alert type="note" >}}
+
To manage files in a [protected branch](branches/protected.md),
you must have the appropriate [permissions](../../permissions.md).
+{{< /alert >}}
+
## Manage files
You can create, edit, upload, and delete files with the Web Editor, directly from the GitLab UI.
@@ -42,7 +48,7 @@ To create a text file in the Web Editor:
1. On the left sidebar, select **Search or go to** and find your project.
1. Go to the directory where you want to create the new file.
-1. Next to the directory name, select the plus icon (**{plus}**) > **New file**.
+1. Next to the directory name, select the plus icon ({{< icon name="plus" >}}) > **New file**.
1. Next to the branch name, enter a filename and extension. For example, `my_file.md`.
1. Add content to your file.
1. Select **Commit changes**.
@@ -70,7 +76,7 @@ To create a text file from a template in the Web Editor:
1. On the left sidebar, select **Search or go to** and find your project.
1. Go to the directory where you want to create the new file.
-1. Next to the directory name, select the plus icon (**{plus}**) > **New file**.
+1. Next to the directory name, select the plus icon ({{< icon name="plus" >}}) > **New file**.
1. In **Filename**, enter a name that GitLab provides a template for:
- `.gitignore`
- `.gitlab-ci.yml`
@@ -108,15 +114,22 @@ To edit a text file in the Web Editor:
1. Select **Commit changes**.
1. Fill out the fields and select **Create merge request**.
-NOTE:
+{{< alert type="note" >}}
+
If someone edits and commits changes to the same file while your are editing,
you can't commit your changes. The following error message is displayed:
`Someone edited the file the same time you did. Please check out the file and
make sure your change will not unintentionally remove theirs.`
+{{< /alert >}}
+
#### Markdown preview
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378966) in GitLab 15.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378966) in GitLab 15.6.
+
+{{< /history >}}
To preview a Markdown file in the Web Editor:
@@ -163,7 +176,7 @@ To upload a file in the Web Editor:
1. On the left sidebar, select **Search or go to** and find your project.
1. Go to the directory where you want to upload the file.
-1. Next to the directory name, select the plus icon (**{plus}**) > **Upload file**.
+1. Next to the directory name, select the plus icon ({{< icon name="plus" >}}) > **Upload file**.
1. Drop or upload the file your want to add.
1. In the **Commit message** field, enter a reason for the commit.
1. Choose one of the following options:
@@ -209,12 +222,15 @@ To delete a file in the Web Editor:
1. Ensure the **Create a merge request for this change** checkbox is selected.
1. Select **Commit changes**.
-NOTE:
+{{< alert type="note" >}}
+
If someone edits and commits changes to the same file while your are editing,
you can't commit your changes. The following error message is displayed:
`Someone edited the file the same time you did. Please check out the file and
make sure your change will not unintentionally remove theirs.`
+{{< /alert >}}
+
### Replace a file
To replace a file in the Web Editor:
@@ -257,7 +273,7 @@ To create a directory in the Web Editor:
1. On the left sidebar, select **Search or go to** and find your project.
1. Go to the directory where you want to create the new directory.
-1. Next to the directory name, select the plus icon (**{plus}**) > **New directory**.
+1. Next to the directory name, select the plus icon ({{< icon name="plus" >}}) > **New directory**.
1. In the **Directory name** field, enter your directory name.
1. In **Commit message**, enter a reason for the commit.
1. Choose between the following options:
@@ -282,7 +298,7 @@ To create a directory in the Web Editor:
To create a [branch](branches/_index.md) in the Web Editor:
1. On the left sidebar, select **Search or go to** and find your project.
-1. Next to the repository name, select the plus icon (**{plus}**) > **New branch**.
+1. Next to the repository name, select the plus icon ({{< icon name="plus" >}}) > **New branch**.
1. Complete the fields.
1. Select **Create branch**.
@@ -292,7 +308,7 @@ You can create [tags](tags/_index.md) to mark milestones such as
production releases and release candidates. To create a tag in the Web Editor:
1. On the left sidebar, select **Search or go to** and find your project.
-1. Next to the repository name, select the plus icon (**{plus}**) > **New tag**.
+1. Next to the repository name, select the plus icon ({{< icon name="plus" >}}) > **New tag**.
1. Complete the fields.
1. Select **Create tag**.
diff --git a/doc/user/project/requirements/_index.md b/doc/user/project/requirements/_index.md
index 1323ec790aa172c1d6298cba1c7c5e13e8c65967..bb6738a2a5689589cad8332833ba6d36b20a69ed 100644
--- a/doc/user/project/requirements/_index.md
+++ b/doc/user/project/requirements/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Requirements management
---
-DETAILS:
-**Tier:** Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With requirements, you can set criteria to check your products against. They can be based on users,
stakeholders, system, software, or anything else you find important to capture.
@@ -19,12 +22,15 @@ If an industry standard *requires* that your application has a certain feature o
[create a requirement](#create-a-requirement) to reflect this.
When a feature is no longer necessary, you can [archive the related requirement](#archive-a-requirement).
-NOTE:
+{{< alert type="note" >}}
+
Requirements and [test cases](../../../ci/test_cases/_index.md) are being
[migrated to work items](https://gitlab.com/groups/gitlab-org/-/epics/5171).
[Issue 323790](https://gitlab.com/gitlab-org/gitlab/-/issues/323790) proposes to link requirements to test cases.
For more information, see [Product Stage Direction - Plan](https://about.gitlab.com/direction/plan/).
+{{< /alert >}}
+
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU).
<!-- Video published on 2020-04-09 -->
@@ -36,7 +42,11 @@ For a more in-depth walkthrough see [GitLab Requirements Traceability Walkthroug
## Create a requirement
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
A paginated list of requirements is available in each project, and there you
can create a new requirement.
@@ -62,13 +72,17 @@ You can view a requirement from the list by selecting it.
-To edit a requirement while viewing it, select the **Edit** icon (**{pencil}**)
+To edit a requirement while viewing it, select the **Edit** icon ({{< icon name="pencil" >}})
next to the requirement title.
## Edit a requirement
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424961) in GitLab 16.11: Authors and assignees can edit requirements even if they don't have the Reporter role.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424961) in GitLab 16.11: Authors and assignees can edit requirements even if they don't have the Reporter role.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can edit a requirement from the requirements list page.
@@ -78,15 +92,19 @@ Prerequisites:
To edit a requirement:
-1. From the requirements list, select the **Edit** icon (**{pencil}**).
+1. From the requirements list, select the **Edit** icon ({{< icon name="pencil" >}}).
1. Update the title and description in text input field. You can also mark a
requirement as satisfied in the edit form by using the checkbox **Satisfied**.
1. Select **Save changes**.
## Archive a requirement
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424961) in GitLab 16.11: Authors and assignees can archive requirements even if they don't have the Reporter role.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424961) in GitLab 16.11: Authors and assignees can archive requirements even if they don't have the Reporter role.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can archive an open requirement while
you're in the **Open** tab.
@@ -95,14 +113,18 @@ Prerequisites:
- You must have at least the Planner role or be the author or assignee of the requirement.
-To archive a requirement, select **Archive** (**{archive}**).
+To archive a requirement, select **Archive** ({{< icon name="archive" >}}).
As soon as a requirement is archived, it no longer appears in the **Open** tab.
## Reopen a requirement
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424961) in GitLab 16.11: Authors and assignees can re-open requirements even if they don't have the Reporter role.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424961) in GitLab 16.11: Authors and assignees can re-open requirements even if they don't have the Reporter role.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can view the list of archived requirements in the **Archived** tab.
@@ -227,7 +249,11 @@ in a project, you must replace `requirements` in above configs with `requirement
## Import requirements from a CSV file
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You must have at least the Planner role.
@@ -248,8 +274,8 @@ To import requirements:
1. In a project, go to **Plan > Requirements**.
- For a project with requirements, in the
- upper-right corner, select the vertical ellipsis (**{ellipsis_v}**),
- then select **Import requirements** (**{import}**).
+ upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}),
+ then select **Import requirements** ({{< icon name="import" >}}).
- For a project without requirements, in the middle of the page, select **Import CSV**.
1. Select the file and select **Import requirements**.
@@ -290,7 +316,11 @@ For GitLab.com, it is set to 10 MB.
## Export requirements to a CSV file
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can export GitLab requirements to a
[CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) sent to your default notification
@@ -307,8 +337,8 @@ Prerequisites:
To export requirements:
1. In a project, go to **Plan > Requirements**.
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**),
- then select **Export as CSV** (**{export}**).
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}),
+ then select **Export as CSV** ({{< icon name="export" >}}).
A confirmation modal appears.
diff --git a/doc/user/project/service_desk/_index.md b/doc/user/project/service_desk/_index.md
index 0daf593f7de57722ae8dabc516ec63aeeac20ad3..c7bc46a176bd18e4f0fc131c804a6ef5037d16b4 100644
--- a/doc/user/project/service_desk/_index.md
+++ b/doc/user/project/service_desk/_index.md
@@ -5,11 +5,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Service Desk
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< alert type="note" >}}
-NOTE:
This feature is not under active development, but
[community contributions](https://about.gitlab.com/community/contribute/) are welcome.
To determine if the feature as it is meets your needs, explore the existing documentation or see the
@@ -19,6 +23,8 @@ The decision to deprioritize Service Desk has been made to
focus on building and extending the work item framework which
the Service Desk category will also benefit from long-term.
+{{< /alert >}}
+
With Service Desk, your customers
can email you bug reports, feature requests, or general feedback.
Service Desk provides a unique email address, so they don't need their own GitLab accounts.
@@ -106,9 +112,9 @@ Service Desk and other reply-by-email features don't work.
The workaround is to run the following commands in your GitLab installation
to patch the affected files:
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
```shell
curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
@@ -116,7 +122,9 @@ patch -p1 -d /opt/gitlab/embedded/service/gitlab-rails < /tmp/mailroom.patch
gitlab-ctl restart mailroom
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
```shell
curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
@@ -125,4 +133,6 @@ patch -p1 < /tmp/mailroom.patch
gitlab-ctl restart mailroom
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
diff --git a/doc/user/project/service_desk/configure.md b/doc/user/project/service_desk/configure.md
index c14f209c5cba57ff4598d44461667e464d09434f..df6b477c12a906c18a3fc7ab010eee99689c1e37 100644
--- a/doc/user/project/service_desk/configure.md
+++ b/doc/user/project/service_desk/configure.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Configure Service Desk
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
By default, Service Desk is active in new projects.
If it's not active, you can do it in the project's settings.
@@ -58,9 +61,13 @@ To improve your Service Desk project's security, you should:
## Customize emails sent to external participants
-> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9.
-> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0.
-> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1.
+{{< history >}}
+
+- `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9.
+- `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0.
+- `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1.
+
+{{< /history >}}
An email is sent to external participants when:
@@ -77,12 +84,12 @@ content specific to the Service Desk ticket or your GitLab instance.
| Placeholder | `thank_you.md` and `new_participant` | `new_note.md` | Description |
|------------------------|--------------------------------------|------------------------|-------------|
-| `%{ISSUE_ID}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket IID. |
-| `%{ISSUE_PATH}` | **{check-circle}** Yes | **{check-circle}** Yes | Project path appended with the ticket IID. |
-| `%{ISSUE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). |
-| `%{ISSUE_DESCRIPTION}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify descriptions or your team is aware of the template design. |
-| `%{UNSUBSCRIBE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe URL. Learn how to [unsubscribe as an external participant](external_participants.md#unsubscribing-from-notification-emails) and [use unsubscribe headers in notification emails from GitLab](../../profile/notifications.md#using-an-email-client-or-other-software). |
-| `%{NOTE_TEXT}` | **{dotted-circle}** No | **{check-circle}** Yes | The new comment added to the ticket by a user. Take care to include this placeholder in `new_note.md`. Otherwise, the external participants may never see the updates on their Service Desk ticket. |
+| `%{ISSUE_ID}` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Ticket IID. |
+| `%{ISSUE_PATH}` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Project path appended with the ticket IID. |
+| `%{ISSUE_URL}` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). |
+| `%{ISSUE_DESCRIPTION}` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify descriptions or your team is aware of the template design. |
+| `%{UNSUBSCRIBE_URL}` | {{< icon name="check-circle" >}} Yes | {{< icon name="check-circle" >}} Yes | Unsubscribe URL. Learn how to [unsubscribe as an external participant](external_participants.md#unsubscribing-from-notification-emails) and [use unsubscribe headers in notification emails from GitLab](../../profile/notifications.md#using-an-email-client-or-other-software). |
+| `%{NOTE_TEXT}` | {{< icon name="dotted-circle" >}} No | {{< icon name="check-circle" >}} Yes | The new comment added to the ticket by a user. Take care to include this placeholder in `new_note.md`. Otherwise, the external participants may never see the updates on their Service Desk ticket. |
### Thank you email
@@ -98,7 +105,11 @@ To create a custom thank you email template:
### New participant email
-> - `new_participant` email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299261) in GitLab 17.0.
+{{< history >}}
+
+- `new_participant` email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299261) in GitLab 17.0.
+
+{{< /history >}}
When an [external participant](external_participants.md) is added to the ticket, GitLab sends a **new participant email** to let them know they are part of the conversation.
Without additional configuration, GitLab sends the default new participant email.
@@ -125,11 +136,18 @@ To keep your emails on brand, you can create a custom new note email template. T
### Instance-wide email header, footer, and additional text
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9.
+
+{{< /history >}}
Instance administrators can add a header, footer or additional text to the GitLab instance and apply
them to all emails sent from GitLab. If you're using a custom `thank_you.md`, `new_participant` or `new_note.md`, to include
@@ -187,7 +205,11 @@ To edit the custom email display name:
## Default ticket visibility
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33091) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33091) in GitLab 17.2.
+
+{{< /history >}}
New tickets are confidential by default, so only project members with at least the Reporter role
can view them.
@@ -210,7 +232,11 @@ To disable this setting:
## Reopen issues when an external participant comments
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8549) in GitLab 16.7
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8549) in GitLab 16.7
+
+{{< /history >}}
You can configure GitLab to reopen closed issues when an external participant adds
a new comment on an issue by email. This also adds an internal comment that mentions
@@ -234,14 +260,21 @@ To enable this setting:
## Custom email address
-DETAILS:
-**Status**: Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329990) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `service_desk_custom_email`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) in GitLab 16.4.
+- Ability to select the SMTP authentication method [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429680) in GitLab 16.6.
+- [Feature flag `service_desk_custom_email` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) in GitLab 16.7.
+- Local network allowed for SMTP host on GitLab Self-Managed [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435206) in GitLab 16.7.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329990) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `service_desk_custom_email`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) in GitLab 16.4.
-> - Ability to select the SMTP authentication method [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429680) in GitLab 16.6.
-> - [Feature flag `service_desk_custom_email` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) in GitLab 16.7.
-> - Local network allowed for SMTP host on GitLab Self-Managed [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435206) in GitLab 16.7.
+{{< /history >}}
Configure a custom email address to show as the sender of your support communication.
Maintain brand identity and instill confidence among support requesters with a domain they recognize.
@@ -492,7 +525,11 @@ In GitLab:
### Use Microsoft 365 (Exchange online) with your own domain
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/496396) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/496396) in GitLab 17.5.
+
+{{< /history >}}
Set up a custom email address for Service Desk when using Microsoft 365 (Exchange) with your own domain.
@@ -631,9 +668,12 @@ In GitLab:
## Use an additional Service Desk alias email
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
You can use an additional alias email address for Service Desk for an instance.
@@ -643,10 +683,13 @@ a [`service_desk_email`](#configure-service-desk-alias-email) in the instance co
### Configure Service Desk alias email
-NOTE:
+{{< alert type="note" >}}
+
On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address. You can still configure the
[custom suffix](#configure-a-suffix-for-service-desk-alias-email) in project settings.
+{{< /alert >}}
+
Service Desk uses the [incoming email](../../../administration/incoming_email.md)
configuration by default. However, to have a separate email address for Service Desk,
configure `service_desk_email` with a [custom suffix](#configure-a-suffix-for-service-desk-alias-email)
@@ -661,11 +704,12 @@ Prerequisites:
To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full:
-::Tabs
+{{< tabs >}}
+
+{{< tab title="Linux package (Omnibus)" >}}
-:::TabTitle Linux package (Omnibus)
+{{< alert type="note" >}}
-NOTE:
In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job.
To use `webhook` on a Linux package installation running GitLab 15.3, you must generate a secret file.
For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927).
@@ -673,6 +717,8 @@ In GitLab 15.4, reconfiguring a Linux package installation generates this secret
secret file configuration setting is needed.
For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462).
+{{< /alert >}}
+
```ruby
gitlab_rails['service_desk_email_enabled'] = true
gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com"
@@ -687,7 +733,9 @@ gitlab_rails['service_desk_email_ssl'] = true
gitlab_rails['service_desk_email_start_tls'] = false
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
```yaml
service_desk_email:
@@ -707,14 +755,20 @@ service_desk_email:
expunge_deleted: true
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
The configuration options are the same as for configuring
[incoming email](../../../administration/incoming_email.md#set-it-up).
#### Use encrypted credentials
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9.
+
+{{< /history >}}
Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally
use an encrypted file for the incoming email credentials.
@@ -729,9 +783,9 @@ The supported configuration items for the encrypted file are:
- `user`
- `password`
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like:
@@ -760,12 +814,16 @@ The supported configuration items for the encrypted file are:
sudo gitlab-ctl reconfigure
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the Service Desk email password. For more information,
read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails).
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. If initially your Service Desk configuration in `docker-compose.yml` looked like:
@@ -803,7 +861,9 @@ read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secre
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like:
@@ -838,19 +898,25 @@ read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secre
sudo service gitlab restart
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Microsoft Graph
-> - [Introduced for self-compiled (source) installs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116494) in GitLab 15.11.
+{{< history >}}
+
+- [Introduced for self-compiled (source) installs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116494) in GitLab 15.11.
+
+{{< /history >}}
`service_desk_email` can be configured to read Microsoft Exchange Online mailboxes with the Microsoft
Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph
[the same way as for incoming email](../../../administration/incoming_email.md#microsoft-graph).
-::Tabs
+{{< tabs >}}
-:::TabTitle Linux package (Omnibus)
+{{< tab title="Linux package (Omnibus)" >}}
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting
the values you want:
@@ -884,7 +950,9 @@ Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph
}
```
-:::TabTitle Helm chart (Kubernetes)
+{{< /tab >}}
+
+{{< tab title="Helm chart (Kubernetes)" >}}
1. Create the [Kubernetes Secret containing the OAuth 2.0 application client secret](https://docs.gitlab.com/charts/installation/secrets.html#microsoft-graph-client-secret-for-service-desk-emails):
@@ -948,7 +1016,9 @@ configure the `azureAdEndpoint` and `graphEndpoint` settings. These fields are c
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
-:::TabTitle Docker
+{{< /tab >}}
+
+{{< tab title="Docker" >}}
1. Edit `docker-compose.yml`:
@@ -1011,7 +1081,9 @@ configure the `azure_ad_endpoint` and `graph_endpoint` settings:
docker compose up -d
```
-:::TabTitle Self-compiled (source)
+{{< /tab >}}
+
+{{< tab title="Self-compiled (source)" >}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
@@ -1054,7 +1126,9 @@ configure the `azure_ad_endpoint` and `graph_endpoint` settings:
poll_interval: 60 # Optional
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Configure a suffix for Service Desk alias email
@@ -1114,23 +1188,27 @@ or completely separately.
Find the `incoming_email` or `service_desk_email` section in `/etc/gitlab/gitlab.rb`:
- ::Tabs
+ {{< tabs >}}
- :::TabTitle `incoming_email`
+ {{< tab title="`incoming_email`" >}}
```ruby
gitlab_rails['incoming_email_enabled'] = true
gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com"
```
- :::TabTitle `service_desk_email`
+ {{< /tab >}}
+
+ {{< tab title="`service_desk_email`" >}}
```ruby
gitlab_rails['service_desk_email_enabled'] = true
gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com"
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. GitLab offers two methods to transport emails from `mail_room` to the GitLab
application. You can configure the `delivery_method` for each email setting individually:
@@ -1139,9 +1217,9 @@ or completely separately.
make sure the `mail_room` process can access the API endpoint and distribute the shared
token across all application nodes.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle `incoming_email`
+ {{< tab title="`incoming_email`" >}}
```ruby
gitlab_rails['incoming_email_delivery_method'] = "webhook"
@@ -1155,7 +1233,9 @@ or completely separately.
gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret"
```
- :::TabTitle `service_desk_email`
+ {{< /tab >}}
+
+ {{< tab title="`service_desk_email`" >}}
```ruby
gitlab_rails['service_desk_email_delivery_method'] = "webhook"
@@ -1170,28 +1250,34 @@ or completely separately.
gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret"
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. [Deprecated in GitLab 16.0 and planned for removal in 19.0)](../../../update/deprecations.md#sidekiq-delivery-method-for-incoming_email-and-service_desk_email-is-deprecated):
If you experience issues with the `webhook` setup, use `sidekiq` to deliver the email payload directly to GitLab Sidekiq using Redis.
- ::Tabs
+ {{< tabs >}}
- :::TabTitle `incoming_email`
+ {{< tab title="`incoming_email`" >}}
```ruby
# It uses the Redis configuration to directly add Sidekiq jobs
gitlab_rails['incoming_email_delivery_method'] = "sidekiq"
```
- :::TabTitle `service_desk_email`
+ {{< /tab >}}
+
+ {{< tab title="`service_desk_email`" >}}
```ruby
# It uses the Redis configuration to directly add Sidekiq jobs
gitlab_rails['service_desk_email_delivery_method'] = "sidekiq"
```
- ::EndTabs
+ {{< /tab >}}
+
+ {{< /tabs >}}
1. Disable `mail_room` on all nodes that should not run email ingestion. For example, in `/etc/gitlab/gitlab.rb`:
diff --git a/doc/user/project/service_desk/external_participants.md b/doc/user/project/service_desk/external_participants.md
index b1a480f167ca1eb087c676d9f7bf218db621d760..861f352b02647bbe39abe38f62f420d0a1d54472 100644
--- a/doc/user/project/service_desk/external_participants.md
+++ b/doc/user/project/service_desk/external_participants.md
@@ -5,11 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: External participants
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3758) in GitLab 17.0.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3758) in GitLab 17.0.
+
+{{< /history >}}
External participants are users without a GitLab account that can interact with an issue or Service Desk ticket only by email.
They get notified of public comments on an issue or ticket by [Service Desk emails](configure.md#customize-emails-sent-to-external-participants).
@@ -119,11 +126,18 @@ To see a list of all external participants:
### Add an external participant
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350460) in GitLab 13.8 [with a flag](../../feature_flags.md) named `issue_email_participants`. Enabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350460) in GitLab 13.8 [with a flag](../../feature_flags.md) named `issue_email_participants`. Enabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
Add an external participant using the `/add_email` [quick action](../quick_actions.md) when you want
to include them in the conversation at any time.
@@ -149,11 +163,18 @@ You should see a success message and a new system note with the email address.
### Remove an external participant
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350460) in GitLab 13.8 [with a flag](../../feature_flags.md) named `issue_email_participants`. Enabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350460) in GitLab 13.8 [with a flag](../../feature_flags.md) named `issue_email_participants`. Enabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
Remove an external participant from an issue or Service Desk ticket using the `/remove_email`
[quick action](../quick_actions.md) when they should stop receiving notifications.
diff --git a/doc/user/project/service_desk/using_service_desk.md b/doc/user/project/service_desk/using_service_desk.md
index 847cffa32db85ad318d2bcfd2cfc31f7581a1f8a..6c97829bf460d67b75296527429ff24f9141a431 100644
--- a/doc/user/project/service_desk/using_service_desk.md
+++ b/doc/user/project/service_desk/using_service_desk.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use Service Desk
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue).
In these issues, you can also see our friendly neighborhood [Support Bot](configure.md#support-bot-user).
@@ -43,8 +46,12 @@ For additional information see [External participants](external_participants.md)
### Create a Service Desk ticket in GitLab UI
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `convert_to_ticket_quick_action`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.10. Feature flag `convert_to_ticket_quick_action` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `convert_to_ticket_quick_action`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.10. Feature flag `convert_to_ticket_quick_action` removed.
+
+{{< /history >}}
To create a Service Desk ticket from the UI:
@@ -88,8 +95,12 @@ To view Service Desk issues:
#### Redesigned issue list
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413092) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `service_desk_vue_list`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415385) in GitLab 16.10. Feature flag `service_desk_vue_list` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413092) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `service_desk_vue_list`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415385) in GitLab 16.10. Feature flag `service_desk_vue_list` removed.
+
+{{< /history >}}
The Service Desk issue list more closely matches the regular issue list.
Available features include:
@@ -138,8 +149,12 @@ when you [filter the list of issues](#filter-the-list-of-issues) by:
### Special HTML formatting in HTML emails
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed.
+
+{{< /history >}}
HTML emails show HTML formatting, such as:
@@ -150,9 +165,13 @@ HTML emails show HTML formatting, such as:
### Files attached to comments
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 16.6. Feature flag `service_desk_new_note_email_native_attachments` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 16.6. Feature flag `service_desk_new_note_email_native_attachments` removed.
+
+{{< /history >}}
If a comment contains any attachments and their total size is less than or equal to 10 MB, these
attachments are sent as part of the email. In other cases, the email contains links to the attachments.
@@ -161,8 +180,12 @@ In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email.
## Convert a regular issue to a Service Desk ticket
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `convert_to_ticket_quick_action`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.10. Feature flag `convert_to_ticket_quick_action` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.9 [with a flag](../../../administration/feature_flags.md) named `convert_to_ticket_quick_action`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/433376) in GitLab 16.10. Feature flag `convert_to_ticket_quick_action` removed.
+
+{{< /history >}}
Use the quick action `/convert_to_ticket external-issue-author@example.com` to convert any regular issue
into a Service Desk ticket. This assigns the provided email address as the external author of the ticket
@@ -174,7 +197,11 @@ You can add a public comment on the ticket to let the end user know that the tic
## Privacy considerations
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9.
+
+{{< /history >}}
Service Desk issues are [confidential](../issues/confidential_issues.md), so they are
only visible to project members. The project owner can
@@ -195,7 +222,11 @@ displayed in the information note.
### Moving a Service Desk issue
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved.
+
+{{< /history >}}
You can move a Service Desk issue the same way you
[move a regular issue](../issues/managing_issues.md#move-an-issue) in GitLab.
diff --git a/doc/user/project/settings/_index.md b/doc/user/project/settings/_index.md
index 7855653f7f4ffe7db89d2b482f2d76dc305e9bbd..736dafabac82f10e55c681f32a2b88c0491d4f9a 100644
--- a/doc/user/project/settings/_index.md
+++ b/doc/user/project/settings/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project features and permissions
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Configure project features and permissions
@@ -72,11 +75,18 @@ To turn this feature off and remove the **Analyze** item from the left sidebar:
## Turn off CVE identifier request in issues
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com.
+{{< /history >}}
In some environments, users can submit a [CVE identifier request](../../application_security/cve_id_request.md) in an issue.
@@ -101,8 +111,12 @@ Prerequisites:
### Turn off diff previews in project email notifications
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24733) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `diff_preview_in_email`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/382055) in GitLab 17.1. Feature flag `diff_preview_in_email` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24733) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `diff_preview_in_email`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/382055) in GitLab 17.1. Feature flag `diff_preview_in_email` removed.
+
+{{< /history >}}
When you review code in a merge request and comment on a line of code, GitLab
includes a few lines of the diff in the email notification to participants.
@@ -154,11 +168,18 @@ To set this default:
## Add additional webhook triggers for project access token expiration
-> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) 60 day and 30 days triggers to project and group access tokens webhooks in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+{{< history >}}
+
+- [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) 60 day and 30 days triggers to project and group access tokens webhooks in GitLab 17.9 [with a flag](../../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
GitLab sends multiple [expiry emails](project_access_tokens.md#project-access-token-expiry-emails) and triggers a related [webhook](../integrations/webhook_events.md#project-and-group-access-token-events) before a project token expires. By default, GitLab only triggers these webhooks 7 days before the token expires. When this feature is enabled, GitLab also triggers these webhooks 60 days and 30 days before the token expires.
To enable additional triggers for these webhooks:
diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md
index 656c9bc1b466a644be2d63b853cc09194e61d89c..d72924f01fb2765247e5119bf6accc0da709449e 100644
--- a/doc/user/project/settings/import_export.md
+++ b/doc/user/project/settings/import_export.md
@@ -1,13 +1,16 @@
---
stage: Foundations
group: Import and Integrate
-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"
+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
title: Migrate projects and groups by using file exports
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Migrating groups and projects by using [direct transfer](../../group/import/_index.md) is recommended. However, in some
situations, you might need to migrate groups and project by using file exports.
@@ -84,7 +87,11 @@ You can also make sure that all members were exported by checking the `project_m
### Compatibility
-> - Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389888) in GitLab 15.11.
+{{< history >}}
+
+- Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389888) in GitLab 15.11.
+
+{{< /history >}}
Project file exports are in NDJSON format.
@@ -100,8 +107,11 @@ For example:
### Configure file exports as an import source
-DETAILS:
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Before you can migrate projects on GitLab Self-Managed using file exports, GitLab administrators must:
@@ -231,13 +241,20 @@ You can import a project and its data. The amount of data you can import depends
[set maximum import file size](#set-maximum-import-file-size).
- On GitLab.com, the value is [set to 5 GB](../../gitlab_com/_index.md#account-and-limit-settings).
-WARNING:
+{{< alert type="warning" >}}
+
Only import projects from sources you trust. If you import a project from an untrusted source, it
may be possible for an attacker to steal your sensitive data.
+{{< /alert >}}
+
#### Prerequisites
-> - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+{{< history >}}
+
+- Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
+
+{{< /history >}}
- You must have [exported the project and its data](#export-a-project-and-its-data).
- Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later
@@ -249,7 +266,7 @@ may be possible for an attacker to steal your sensitive data.
To import a project:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
1. Select **Import project**.
1. In **Import project from**, select **GitLab export**.
1. Enter your project name and URL. Then select the file you exported previously.
@@ -273,15 +290,21 @@ Deploy keys aren't imported. To use deploy keys, you must enable them in your im
#### Import large projects
-DETAILS:
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you have a larger project, consider [using a Rake task](../../../administration/raketasks/project_import_export.md#import-large-projects).
### Set maximum import file size
-DETAILS:
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Administrators can set the maximum import file size one of two ways:
@@ -302,14 +325,21 @@ To help avoid abuse, by default, users are rate limited to:
## Migrate groups by uploading an export file (deprecated)
-> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6.
+{{< history >}}
+
+- [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6 and replaced by
[migrating groups by direct transfer](../../group/import/_index.md). However, this feature is still recommended for migrating groups between
offline systems. To follow progress on an alternative solution for [offline environments](../../application_security/offline_deployments/_index.md), see
[the relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/8985).
+{{< /alert >}}
+
Prerequisites:
- Owner role on the group to migrate.
@@ -348,7 +378,11 @@ The maximum import file size depends on whether you import to GitLab Self-Manage
### Compatibility
-> - Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/383682) in GitLab 15.8.
+{{< history >}}
+
+- Support for JSON-formatted project file exports [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/383682) in GitLab 15.8.
+
+{{< /history >}}
Group file exports are in NDJSON format.
@@ -417,7 +451,7 @@ To export the contents of a group:
To import the group:
-1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**.
+1. On the left sidebar, at the top, select **Create new** ({{< icon name="plus" >}}) and **New group**.
1. Select **Import group**.
1. In the **Import group from file** section, enter a group name and accept or modify the associated group URL.
1. Select **Choose file**.
diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md
index 5396276ddb7cc96ab4948ff73b491661f9ff3bed..bfa472516ef19830e4345e196b032857d3ecf969 100644
--- a/doc/user/project/settings/import_export_troubleshooting.md
+++ b/doc/user/project/settings/import_export_troubleshooting.md
@@ -1,13 +1,16 @@
---
stage: Foundations
group: Import and Integrate
-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"
+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
title: Troubleshooting file export project migrations
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you have problems with [migrating projects by using file exports](import_export.md), see the possible solutions below.
@@ -120,9 +123,12 @@ reduce the repository size for another import attempt:
### Workaround option 2
-NOTE:
+{{< alert type="note" >}}
+
This workaround does not account for LFS objects.
+{{< /alert >}}
+
Rather than attempting to push all changes at once, this workaround:
- Separates the project import from the Git Repository import
diff --git a/doc/user/project/settings/migrate_projects.md b/doc/user/project/settings/migrate_projects.md
index b6aba3dd060d34a6efe65678aa80d96f4115b3fb..c9e57bd9b6dbad0e7630f36dd54716b6a2765c83 100644
--- a/doc/user/project/settings/migrate_projects.md
+++ b/doc/user/project/settings/migrate_projects.md
@@ -5,14 +5,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Transfer projects
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
## Transfer a project to another namespace
-> - Support for transferring projects with container images within the same top-level namespace [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/499163) on GitLab.com in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `transfer_project_with_tags`. Disabled by default.
-> - Support for transferring projects with container images within the same top-level namespace [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/499163) in GitLab 17.7. Feature flag removed.
+{{< history >}}
+
+- Support for transferring projects with container images within the same top-level namespace [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/499163) on GitLab.com in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `transfer_project_with_tags`. Disabled by default.
+- Support for transferring projects with container images within the same top-level namespace [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/499163) in GitLab 17.7. Feature flag removed.
+
+{{< /history >}}
Transfer a project to move it to a different group.
A project transfer includes:
@@ -26,18 +33,24 @@ A project transfer includes:
- Direct members
- Membership invitations
- NOTE:
- Members who inherited their access from the original group lose access
+ {{< alert type="note" >}}
+
+Members who inherited their access from the original group lose access
unless they are also members of the target group. The project inherits
new member permissions from the group you transfer it to.
+ {{< /alert >}}
+
The project's [path also changes](../repository/_index.md#repository-path-changes), so make sure to update the URLs to the project components where necessary.
New project-level labels are created for issues and merge requests if matching group labels don't already exist in the target namespace.
-WARNING:
+{{< alert type="warning" >}}
+
Errors during the transfer process may lead to data loss of the project's components or dependencies of end users.
+{{< /alert >}}
+
Prerequisites:
- You must have at least the Maintainer role for the [group](../../group/_index.md#create-a-group) you are transferring to.
@@ -66,10 +79,13 @@ To transfer a project:
You are redirected to the project's new page and GitLab applies a redirect. For more information about repository redirects, see [What happens when a repository path changes](../repository/_index.md#repository-path-changes).
-NOTE:
+{{< alert type="note" >}}
+
If you are an administrator, you can also use the [administration interface](../../../administration/admin_area.md#administering-projects)
to move any project to any namespace.
+{{< /alert >}}
+
## Transferring a GitLab.com project to a different subscription tier
When you transfer a project from a namespace licensed for GitLab.com Premium or Ultimate to GitLab Free:
diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md
index 3c0dcb8ef36a23cfbd122c3ee7c1909265dad67c..f05190cb62dc3778e190329ef0665144aede1038 100644
--- a/doc/user/project/settings/project_access_tokens.md
+++ b/doc/user/project/settings/project_access_tokens.md
@@ -1,18 +1,25 @@
---
stage: Software Supply Chain Security
group: Authentication
-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"
+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
title: Project access tokens
---
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386041) for trial subscriptions in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386041) for trial subscriptions in GitLab 16.1.
+
+{{< /history >}}
Project access tokens are similar to passwords, except you can [limit access to resources](#scopes-for-a-project-access-token),
select a limited role, and provide an expiry date.
-NOTE:
+{{< alert type="note" >}}
+
Actual access to a project is controlled by a combination of [roles and permissions](../../permissions.md), and the [token scopes](#scopes-for-a-project-access-token).
+{{< /alert >}}
+
Use a project access token to authenticate:
- With the [GitLab API](../../../api/rest/authentication.md#personalprojectgroup-access-tokens).
@@ -38,19 +45,29 @@ configured for personal access tokens.
## Create a project access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days and default role of Guest is populated in the UI.
-> - Ability to create non-expiring project access tokens [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0.
-> - Maximum allowable lifetime limit [extended to 400 days](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) in GitLab 17.6 [with a flag](../../../administration/feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
-> - Project access token description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443819) in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days and default role of Guest is populated in the UI.
+- Ability to create non-expiring project access tokens [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0.
+- Maximum allowable lifetime limit [extended to 400 days](https://gitlab.com/gitlab-org/gitlab/-/issues/461901) in GitLab 17.6 [with a flag](../../../administration/feature_flags.md) named `buffered_token_expiration_limit`. Disabled by default.
+- Project access token description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/443819) in GitLab 17.7.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the extended maximum allowable lifetime limit is controlled by a feature flag.
For more information, see the history.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
The ability to create project access tokens without an expiry date was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0. For more information on expiry dates added to existing tokens, see the documentation on [access token expiration](#access-token-expiration).
+{{< /alert >}}
+
To create a project access token:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -69,15 +86,22 @@ To create a project access token:
A project access token is displayed. Save the project access token somewhere safe. After you leave or refresh the page, you can't view it again.
-WARNING:
+{{< alert type="warning" >}}
+
Project access tokens are treated as [internal users](../../../administration/internal_users.md).
If an internal user creates a project access token, that token is able to access
all projects that have visibility level set to [Internal](../../public_access.md).
+{{< /alert >}}
+
## Revoke or rotate a project access token
-> - Ability to view expired and revoked tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `retain_resource_access_token_user_after_revoke`. Disabled by default.
-> - Ability to view expired and revoked tokens limited to 30 days and [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/471683) in GitLab 17.9. Feature flag `retain_resource_access_token_user_after_revoke` removed.
+{{< history >}}
+
+- Ability to view expired and revoked tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.3 [with a flag](../../../administration/feature_flags.md) named `retain_resource_access_token_user_after_revoke`. Disabled by default.
+- Ability to view expired and revoked tokens limited to 30 days and [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/471683) in GitLab 17.9. Feature flag `retain_resource_access_token_user_after_revoke` removed.
+
+{{< /history >}}
In GitLab 17.9 and later, you can view both active and inactive project
access tokens on the access tokens page.
@@ -90,20 +114,27 @@ To revoke or rotate a project access token:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings > Access tokens**.
-1. For the relevant token, select **Revoke** (**{remove}**) or **Rotate** (**{retry}**).
+1. For the relevant token, select **Revoke** ({{< icon name="remove" >}}) or **Rotate** ({{< icon name="retry" >}}).
1. On the confirmation dialog, select **Revoke** or **Rotate**.
## Scopes for a project access token
-> - `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default.
-> - Feature flag `k8s_proxy_pat` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131518) in GitLab 16.5.
-> - `self_rotate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178111) in GitLab 17.9. Enabled by default.
+{{< history >}}
+
+- `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default.
+- Feature flag `k8s_proxy_pat` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131518) in GitLab 16.5.
+- `self_rotate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/178111) in GitLab 17.9. Enabled by default.
+
+{{< /history >}}
The scope determines the actions you can perform when you authenticate with a project access token.
-NOTE:
+{{< alert type="note" >}}
+
See the warning in [create a project access token](#create-a-project-access-token) regarding internal projects.
+{{< /alert >}}
+
| Scope | Description |
|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `api` | Grants complete read and write access to the scoped project API, including the [container registry](../../packages/container_registry/_index.md), the [dependency proxy](../../packages/dependency_proxy/_index.md), and the [package registry](../../packages/package_registry/_index.md). |
@@ -164,13 +195,20 @@ automatically applied:
### Project access token expiry emails
-> - Sixty and thirty day expiry notification emails [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464040) in GitLab 17.6 [with a flag](../../../administration/feature_flags.md) named `expiring_pats_30d_60d_notifications`. Disabled by default.
-> - Sixty and thirty day notification emails [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173792) in GitLab 17.7. Feature flag `expiring_pats_30d_60d_notifications` removed.
-> - Notifications to inherited group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+{{< history >}}
+
+- Sixty and thirty day expiry notification emails [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/464040) in GitLab 17.6 [with a flag](../../../administration/feature_flags.md) named `expiring_pats_30d_60d_notifications`. Disabled by default.
+- Sixty and thirty day notification emails [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173792) in GitLab 17.7. Feature flag `expiring_pats_30d_60d_notifications` removed.
+- Notifications to inherited group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463016) in GitLab 17.7 [with a flag](../../../administration/feature_flags.md) named `pat_expiry_inherited_members_notification`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of the sixty and thirty day expiry notification emails is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
GitLab runs a check every day at 1:00 AM UTC to identify project access tokens that are expiring in the near future. Members of the project with at least the Maintainer role are notified by email when these tokens expire in a certain number of days. The number of days differs depending on the version of GitLab:
- In GitLab 17.6 and later, project maintainers and owners are notified by email when the check identifies their project access tokens as expiring in the next sixty days. An additional email is sent when the check identifies their project access tokens as expiring in the next thirty days.
@@ -183,8 +221,12 @@ Your expired access tokens are listed in the [inactive project access tokens tab
## Bot users for projects
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `retain_resource_access_token_user_after_revoke`. Disabled by default. When enabled new bot users are made members with no expiry date and, when the token is later revoked or expires, the bot user is retained for 30 days.
-> - Inactive bot users retention is [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.9. Feature flag `retain_resource_access_token_user_after_revoke` removed.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.2 [with a flag](../../../administration/feature_flags.md) named `retain_resource_access_token_user_after_revoke`. Disabled by default. When enabled new bot users are made members with no expiry date and, when the token is later revoked or expires, the bot user is retained for 30 days.
+- Inactive bot users retention is [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/462217) in GitLab 17.9. Feature flag `retain_resource_access_token_user_after_revoke` removed.
+
+{{< /history >}}
Bot users for projects are [GitLab-created non-billable users](../../../subscriptions/self_managed/_index.md#billable-users).
Each time you create a project access token, a bot user is created and added to the project.
diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md
index 5426e88318a2f641ed767334733499a4cbbb6812..644ef6bac3949f9c449704067b44605f9e243bd8 100644
--- a/doc/user/project/system_notes.md
+++ b/doc/user/project/system_notes.md
@@ -2,13 +2,16 @@
stage: Create
group: Source Code
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
-description: "System notes track the history of changes made to an object, like a merge request or issue, in your GitLab project."
+description: System notes track the history of changes made to an object, like a merge request or issue, in your GitLab project.
title: System notes
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
System notes are short descriptions that help you understand the history of events
that occur during the lifecycle of a GitLab object, such as:
diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md
index 9b5828625db7f832ff8597b962b8bb2f5c397e8b..76f137f9e35a11c1704256d70ae2c2181d4808e9 100644
--- a/doc/user/project/time_tracking.md
+++ b/doc/user/project/time_tracking.md
@@ -5,13 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Time tracking
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Time tracking for tasks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438577) in GitLab 17.0.
-> - Time tracking for epics [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12396) in GitLab 17.5. Your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md).
-> - Minimum role to add, edit, and remove estimate [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Time tracking for tasks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438577) in GitLab 17.0.
+- Time tracking for epics [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12396) in GitLab 17.5. Your administrator must have [enabled the new look for epics](../group/epics/epic_work_items.md).
+- Minimum role to add, edit, and remove estimate [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can estimate and track the time you spend on an item, such as:
@@ -90,12 +97,16 @@ Prerequisites:
#### Using the user interface
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101563) in GitLab 15.7.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150564) in GitLab 17.0. When you don't specify when time was spent, current time is used.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101563) in GitLab 15.7.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150564) in GitLab 17.0. When you don't specify when time was spent, current time is used.
+
+{{< /history >}}
To add a time entry using the user interface:
-1. In the **Time tracking** section of the sidebar, select **Add time entry** (**{plus}**). A dialog opens.
+1. In the **Time tracking** section of the sidebar, select **Add time entry** ({{< icon name="plus" >}}). A dialog opens.
1. Enter:
- The amount of time spent.
@@ -143,7 +154,11 @@ so if you remove more time than already entered, GitLab ignores the subtraction.
### Delete time spent
-> - Delete button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356796) in GitLab 15.1.
+{{< history >}}
+
+- Delete button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356796) in GitLab 15.1.
+
+{{< /history >}}
A timelog is a single entry of time spent, either positive or negative.
@@ -153,7 +168,7 @@ Prerequisites:
To delete a timelog, either:
-- In the time tracking report, on the right of a timelog entry, select **Delete time spent** (**{remove}**).
+- In the time tracking report, on the right of a timelog entry, select **Delete time spent** ({{< icon name="remove" >}}).
- Use the [GraphQL API](../../api/graphql/reference/_index.md#mutationtimelogdelete).
### Delete all the time spent
@@ -184,17 +199,27 @@ The breakdown of spent time displayed is limited to a maximum of 100 entries.
## Global time tracking report
-DETAILS:
-**Status**: Experiment
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344002) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `global_time_tracking_report`. Disabled by default.
-> - Enabled on GitLab.com in GitLab 16.5.
+- Status: Experiment
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344002) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `global_time_tracking_report`. Disabled by default.
+- Enabled on GitLab.com in GitLab 16.5.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `global_time_tracking_report`.
On GitLab.com, this feature is available. On GitLab Dedicated, this feature is not available.
This feature is not ready for production use.
+{{< /alert >}}
+
View a report of time spent in issues, tasks, and merge requests across all of GitLab.
This feature is an [experiment](../../policy/development_stages_support.md).
@@ -225,9 +250,12 @@ The following time units are available:
### Limit displayed units to hours
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
On GitLab Self-Managed, you can limit the display of time units to hours.
To do so:
diff --git a/doc/user/project/troubleshooting.md b/doc/user/project/troubleshooting.md
index 9dd9448362266aa3cb64af0f2eb6f054e025d5f7..9fbc302d050521a8efea0f0f204435c0dc8750b9 100644
--- a/doc/user/project/troubleshooting.md
+++ b/doc/user/project/troubleshooting.md
@@ -28,9 +28,12 @@ projects = Project.find_by_sql("SELECT * FROM projects WHERE name LIKE '%ject'")
If a project or repository has been updated but the state is not reflected in the UI, you may need to clear the project's or repository's cache.
You can do so through [a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) and one of the following:
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
## Clear project cache
ProjectCacheWorker.perform_async(project.id)
@@ -57,9 +60,12 @@ end
If a project cannot be deleted, you can attempt to delete it through [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session).
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
project = Project.find_by_full_path('<project_path>')
user = User.find_by_username('<username>')
@@ -81,9 +87,12 @@ you may need to do this for a large number of projects.
To toggle a specific feature, you can [start a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session)
and run the following function:
-WARNING:
+{{< alert type="warning" >}}
+
Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+{{< /alert >}}
+
```ruby
projects = Group.find_by_name('_group_name').projects
projects.each do |p|
diff --git a/doc/user/project/use_project_as_go_package.md b/doc/user/project/use_project_as_go_package.md
index a208d52c7621060aace29a1910c2054423720c75..9b75b5702341ab36f90efd18cb2bc442b42e2279 100644
--- a/doc/user/project/use_project_as_go_package.md
+++ b/doc/user/project/use_project_as_go_package.md
@@ -1,15 +1,22 @@
---
stage: Tenant Scale
group: Organizations
-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"
+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
title: Use a project as a Go package
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Changed in [GitLab 17.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161162) to return 404 errors for unauthorized `go get` requests.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Changed in [GitLab 17.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161162) to return 404 errors for unauthorized `go get` requests.
+
+{{< /history >}}
Prerequisites:
@@ -22,10 +29,13 @@ To use a project as a Go package, use the `go get` and `godoc.org` discovery req
- [`go-import`](https://pkg.go.dev/cmd/go#hdr-Remote_import_paths)
- [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links)
-NOTE:
+{{< alert type="note" >}}
+
If you make a `go get` request with invalid HTTP credentials, you receive a 404 error.
You can find the HTTP credentials in `~/.netrc` (MacOS and Linux) or `~/_netrc` (Windows).
+{{< /alert >}}
+
## Authenticate Go requests to private projects
Prerequisites:
diff --git a/doc/user/project/web_ide/_index.md b/doc/user/project/web_ide/_index.md
index 055beb1376f6e038e6e6f31f2f5bfc0928e527a0..02b2ff3c134cacb4b75300b3b60e05aec709f1f7 100644
--- a/doc/user/project/web_ide/_index.md
+++ b/doc/user/project/web_ide/_index.md
@@ -2,22 +2,32 @@
stage: Create
group: Remote Development
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
-description: "Use the Web IDE to edit multiple files in the GitLab UI, stage commits, and create merge requests."
+description: Use the Web IDE to edit multiple files in the GitLab UI, stage commits, and create merge requests.
title: Web IDE
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7.
-> - [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7.
+- [Enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
The Web IDE is an advanced editor with commit staging.
You can use the Web IDE to make changes to multiple files directly from the GitLab UI.
For a more basic implementation, see [Web Editor](../repository/web_editor.md).
@@ -51,7 +61,7 @@ To open the Web IDE from a merge request:
The Web IDE opens new and modified files in separate tabs and displays changes side by side.
To reduce load time, only 10 files with the most lines changed open automatically.
-The left **Explorer** sidebar adds a merge request icon (**{merge-request}**) next to new or modified files.
+The left **Explorer** sidebar adds a merge request icon ({{< icon name="merge-request" >}}) next to new or modified files.
To view changes to a file, right-click the file and select **Compare with merge request base**.
## Open a file
@@ -102,7 +112,7 @@ To upload a file in the Web IDE:
To create a new directory:
- On the left **Explorer** sidebar, in the upper right,
- select **New Folder** (**{folder-new}**).
+ select **New Folder** ({{< icon name="folder-new" >}}).
1. Right-click the directory and select **Upload**.
1. Select the file you want to upload.
@@ -218,23 +228,33 @@ You cannot sync user profiles or go back to an earlier version of synced setting
When you perform actions in the Web IDE, notifications appear in the lower right.
To view any notification you might have missed:
-1. On the bottom status bar, on the right, select the bell icon (**{notifications}**) for a list of notifications.
+1. On the bottom status bar, on the right, select the bell icon ({{< icon name="notifications" >}}) for a list of notifications.
1. Select the notification you want to view.
## Extension marketplace
-DETAILS:
-**Offering:** GitLab.com
+{{< details >}}
+
+- Offering: GitLab.com
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151352) as a [beta](../../../policy/development_stages_support.md#beta) in GitLab 17.0 [with flags](../../../administration/feature_flags.md) named `web_ide_oauth` and `web_ide_extensions_marketplace`. Disabled by default.
-> - Feature flag `web_ide_oauth` [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163181) in GitLab 17.4.
-> - Feature flag `web_ide_extensions_marketplace` [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/459028) in GitLab 17.4.
-> - Feature flag `web_ide_oauth` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167464) in GitLab 17.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151352) as a [beta](../../../policy/development_stages_support.md#beta) in GitLab 17.0 [with flags](../../../administration/feature_flags.md) named `web_ide_oauth` and `web_ide_extensions_marketplace`. Disabled by default.
+- Feature flag `web_ide_oauth` [enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/163181) in GitLab 17.4.
+- Feature flag `web_ide_extensions_marketplace` [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/459028) in GitLab 17.4.
+- Feature flag `web_ide_oauth` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167464) in GitLab 17.5.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Prerequisites:
- In user preferences, you must
@@ -290,8 +310,11 @@ For more information, see [VS Code issue 80170](https://github.com/microsoft/vsc
### Update the OAuth callback URL
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Prerequisites:
@@ -316,8 +339,11 @@ To update the OAuth callback URL:
### Workhorse dependency
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
On GitLab Self-Managed, [Workhorse](../../../development/workhorse/_index.md) must be installed
and running in front of the GitLab Rails server.
diff --git a/doc/user/project/wiki/_index.md b/doc/user/project/wiki/_index.md
index 0444176807ce233780bc0025d69dac5203cc5d34..7f7c6ab04c4b1e8de26e625ff2970308353ee68b 100644
--- a/doc/user/project/wiki/_index.md
+++ b/doc/user/project/wiki/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Wiki
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you don't want to keep your documentation in your repository, but you want
to keep it in the same project as your code, you can use the wiki GitLab provides
@@ -42,8 +45,12 @@ To rename your wiki's default branch,see [Update the default branch name in your
## Create the wiki home page
-> - Separation of page title and path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30758) in GitLab 17.2 [with flags](../../../administration/feature_flags.md) named `wiki_front_matter` and `wiki_front_matter_title`. Enabled by default.
-> - Feature flags `wiki_front_matter` and `wiki_front_matter_title` removed in GitLab 17.3.
+{{< history >}}
+
+- Separation of page title and path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30758) in GitLab 17.2 [with flags](../../../administration/feature_flags.md) named `wiki_front_matter` and `wiki_front_matter_title`. Enabled by default.
+- Feature flags `wiki_front_matter` and `wiki_front_matter_title` removed in GitLab 17.3.
+
+{{< /history >}}
When a wiki is created, it is empty. On your first visit, you can create the
home page users see when viewing the wiki. This page requires a specific path
@@ -64,8 +71,12 @@ to be used as your wiki's home page. To create it:
## Create a new wiki page
-> - Separation of page title and path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30758) in GitLab 17.2 [with flags](../../../administration/feature_flags.md) named `wiki_front_matter` and `wiki_front_matter_title`. Enabled by default.
-> - Feature flags `wiki_front_matter` and `wiki_front_matter_title` removed in GitLab 17.3.
+{{< history >}}
+
+- Separation of page title and path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30758) in GitLab 17.2 [with flags](../../../administration/feature_flags.md) named `wiki_front_matter` and `wiki_front_matter_title`. Enabled by default.
+- Feature flags `wiki_front_matter` and `wiki_front_matter_title` removed in GitLab 17.3.
+
+{{< /history >}}
Prerequisites:
@@ -73,7 +84,7 @@ Prerequisites:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Wiki**.
-1. Select **Wiki actions** (**{ellipsis_v}**), then **New page** on this page, or any other wiki page.
+1. Select **Wiki actions** ({{< icon name="ellipsis_v" >}}), then **New page** on this page, or any other wiki page.
1. Select a content format.
1. Add a **Title** for your new page.
1. Optional. Uncheck **Generate page path from title** and change the **Path** of the page.
@@ -93,7 +104,7 @@ locally:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Wiki**.
-1. Select **Wiki actions** (**{ellipsis_v}**), then **Clone repository**.
+1. Select **Wiki actions** ({{< icon name="ellipsis_v" >}}), then **Clone repository**.
1. Follow the on-screen instructions.
Files you add to your wiki locally must use one of the following
@@ -106,9 +117,13 @@ Files with unsupported extensions don't display when pushed to GitLab:
### Special characters in page paths
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133521) front matter based titles in GitLab 16.7 [with flags](../../../administration/feature_flags.md) named `wiki_front_matter` and `wiki_front_matter_title`. Disabled by default.
-> - Feature flags [`wiki_front_matter`](https://gitlab.com/gitlab-org/gitlab/-/issues/435056) and [`wiki_front_matter_title`](https://gitlab.com/gitlab-org/gitlab/-/issues/428259) enabled by default in GitLab 17.2.
-> - Feature flags `wiki_front_matter` and `wiki_front_matter_title` removed in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133521) front matter based titles in GitLab 16.7 [with flags](../../../administration/feature_flags.md) named `wiki_front_matter` and `wiki_front_matter_title`. Disabled by default.
+- Feature flags [`wiki_front_matter`](https://gitlab.com/gitlab-org/gitlab/-/issues/435056) and [`wiki_front_matter_title`](https://gitlab.com/gitlab-org/gitlab/-/issues/428259) enabled by default in GitLab 17.2.
+- Feature flags `wiki_front_matter` and `wiki_front_matter_title` removed in GitLab 17.3.
+
+{{< /history >}}
Wiki pages are stored as files in a Git repository, and by default, the filename of
a page is also its title. Certain characters in the filename have a special meaning:
@@ -163,7 +178,11 @@ Unsaved changes to a wiki page are preserved in local browser storage to prevent
### Create a table of contents
-> - Table of contents in the wiki sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/281570) in GitLab 17.2.
+{{< history >}}
+
+- Table of contents in the wiki sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/281570) in GitLab 17.2.
+
+{{< /history >}}
Wiki pages with headings in their contents automatically display a table of contents
section in the sidebar.
@@ -181,14 +200,18 @@ Prerequisites:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Wiki**.
1. Go to the page you want to delete.
-1. Select **Wiki actions** (**{ellipsis_v}**), then **Delete page**.
+1. Select **Wiki actions** ({{< icon name="ellipsis_v" >}}), then **Delete page**.
1. Confirm the deletion.
## Move or rename a wiki page
-> - Redirects for moved or renamed wiki pages [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/257892) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `wiki_redirection`. Enabled by default.
-> - Separation of page title and path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30758) in GitLab 17.2 [with flags](../../../administration/feature_flags.md) named `wiki_front_matter` and `wiki_front_matter_title`. Enabled by default.
-> - Feature flags `wiki_redirection`, `wiki_front_matter` and `wiki_front_matter_title` removed in GitLab 17.3.
+{{< history >}}
+
+- Redirects for moved or renamed wiki pages [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/257892) in GitLab 17.1 [with a flag](../../../administration/feature_flags.md) named `wiki_redirection`. Enabled by default.
+- Separation of page title and path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30758) in GitLab 17.2 [with flags](../../../administration/feature_flags.md) named `wiki_front_matter` and `wiki_front_matter_title`. Enabled by default.
+- Feature flags `wiki_redirection`, `wiki_front_matter` and `wiki_front_matter_title` removed in GitLab 17.3.
+
+{{< /history >}}
In GitLab 17.1 and later, when you move or rename a page, a redirect is
automatically set up from the old page to the new page. A list of redirects
@@ -210,22 +233,30 @@ Prerequisites:
## Export a wiki page
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414691) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `print_wiki`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134251/) in GitLab 16.5.
-> - Feature flag `print_wiki` removed in GitLab 16.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414691) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `print_wiki`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134251/) in GitLab 16.5.
+- Feature flag `print_wiki` removed in GitLab 16.6.
+
+{{< /history >}}
You can export a wiki page as a PDF file:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Wiki**.
1. Go to the page you want to export.
-1. On the top right, select **Wiki actions** (**{ellipsis_v}**), then select **Print as PDF**.
+1. On the top right, select **Wiki actions** ({{< icon name="ellipsis_v" >}}), then select **Print as PDF**.
A PDF of the wiki page is created.
## Wiki page templates
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442228) in GitLab 16.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442228) in GitLab 16.10.
+
+{{< /history >}}
You can create templates to use when creating new pages, or to apply
to existing pages. Templates are wiki pages that are stored in the `templates/`
@@ -239,7 +270,7 @@ Prerequisites:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Wiki**.
-1. Select **Wiki actions** (**{ellipsis_v}**), then **Templates**.
+1. Select **Wiki actions** ({{< icon name="ellipsis_v" >}}), then **Templates**.
1. Select **New Template**.
1. Enter template title, format and content, as if creating a regular wiki page.
@@ -276,7 +307,7 @@ To view the changes for a wiki page:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Wiki**.
1. Go to the page you want to view history for.
-1. Select **Wiki actions** (**{ellipsis_v}**), then **Page history**.
+1. Select **Wiki actions** ({{< icon name="ellipsis_v" >}}), then **Page history**.
### View changes between page versions
@@ -285,13 +316,17 @@ You can see the changes made in a version of a wiki page, similar to versioned d
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Wiki**.
1. Go to the wiki page you're interested in.
-1. Select **Wiki actions** (**{ellipsis_v}**), then **Page history** to see all page versions.
+1. Select **Wiki actions** ({{< icon name="ellipsis_v" >}}), then **Page history** to see all page versions.
1. Select the commit message in the **Diff** column for the version you're interested in.
## Sidebar
-> - Searching by title in the sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/156054) in GitLab 17.1.
-> - Limit of 15 items in the sidebar [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158084) in GitLab 17.2.
+{{< history >}}
+
+- Searching by title in the sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/156054) in GitLab 17.1.
+- Limit of 15 items in the sidebar [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/158084) in GitLab 17.2.
+
+{{< /history >}}
Wiki pages display a sidebar that contains a list of pages in the wiki,
displayed as a nested tree, with sibling pages listed in alphabetical order.
@@ -315,7 +350,7 @@ replaces the default sidebar navigation:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Plan > Wiki**.
-1. In the upper-right corner of the page, select **Add custom sidebar** (**{settings}**).
+1. In the upper-right corner of the page, select **Add custom sidebar** ({{< icon name="settings" >}}).
1. When complete, select **Save changes**.
A `_sidebar` example, formatted with Markdown:
@@ -391,7 +426,11 @@ to disable the wiki but toggle it on (in blue).
## Rich text editor
-> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/398152) from content editor to rich text editor in GitLab 16.2.
+{{< history >}}
+
+- [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/398152) from content editor to rich text editor in GitLab 16.2.
+
+{{< /history >}}
GitLab provides a rich text editing experience for GitLab Flavored Markdown in wikis.
@@ -447,17 +486,25 @@ line of your Apache configuration to ensure your page slugs render correctly.
### Recreate a project wiki with the Rails console
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< alert type="warning" >}}
-WARNING:
This operation deletes all data in the wiki.
-WARNING:
+{{< /alert >}}
+
+{{< alert type="warning" >}}
+
Any command that changes data directly could be damaging if not run correctly, or under the
right conditions. We highly recommend running them in a test environment with a backup of the
instance ready to be restored, just in case.
+{{< /alert >}}
To clear all data from a project wiki and recreate it in a blank state:
diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md
index 80211261b141b025ffa5fd32b709c59a0eefc559..ba53ed5155152ba3dabd9e011a46da59885f7933 100644
--- a/doc/user/project/wiki/group.md
+++ b/doc/user/project/wiki/group.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Group wikis
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
If you use GitLab groups to manage multiple projects, some of your documentation
might span multiple groups. You can create group wikis, instead of [project wikis](_index.md),
@@ -58,7 +61,11 @@ All files in the wiki are available in this Git repository.
## Configure group wiki visibility
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208412) in GitLab 15.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208412) in GitLab 15.0.
+
+{{< /history >}}
Wikis are enabled by default in GitLab. Group [administrators](../../permissions.md)
can enable or disable a group wiki through the group settings.
diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md
index d8e68a77ab506ccbf892eb0c01ae67b923ea7901..4cc58ce15878f525148385fc581ec76e82eb0cfb 100644
--- a/doc/user/project/working_with_projects.md
+++ b/doc/user/project/working_with_projects.md
@@ -1,20 +1,27 @@
---
stage: Tenant Scale
group: Organizations
-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"
+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
title: Manage projects
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Most work in GitLab is done in a [project](_index.md). Files and
code are saved in projects, and most features are in the scope of projects.
## Project overview
-> - Project creation date [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19452) in GitLab 16.10.
+{{< history >}}
+
+- Project creation date [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19452) in GitLab 16.10.
+
+{{< /history >}}
When you select a project, the **Project overview** page shows the project contents:
@@ -50,21 +57,28 @@ For users without permission to view the project's code, the overview page shows
### Access a project by using the project ID
-> - Project ID [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7.
+{{< history >}}
+
+- Project ID [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7.
+
+{{< /history >}}
You can access a project by using its ID instead of its name at `https://gitlab.example.com/projects/<id>`.
For example, if in your personal namespace `alex` you have a project `my-project` with the ID `123456`,
you can access the project either at `https://gitlab.example.com/alex/my-project` or `https://gitlab.example.com/projects/123456`.
-NOTE:
+{{< alert type="note" >}}
+
In GitLab 17.5 and later, you can also use `https://gitlab.example.com/-/p/<id>` for this endpoint.
+{{< /alert >}}
+
You might also need the project ID if you want to interact with the project using the [GitLab API](../../api/_index.md).
To copy the project ID:
1. On the left sidebar, select **Search or go to** and find your project.
-1. On the project overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**).
+1. On the project overview page, in the upper-right corner, select **Actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Copy project ID**.
## View all projects for the instance
@@ -81,11 +95,18 @@ If you are not authenticated, the list shows public projects only.
## View projects you have contributed to
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13066) in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `your_work_projects_vue`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13066) in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `your_work_projects_vue`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag. For more information, see the history.
+{{< /alert >}}
+
The **Contributed** tab displays projects where you have:
- Created issues, merge requests, or epics
@@ -103,7 +124,11 @@ To view projects you have contributed to:
## View projects you are a member of
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/13066) tab label from "Yours" to "Member" in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `your_work_projects_vue`. Disabled by default.
+{{< history >}}
+
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/13066) tab label from "Yours" to "Member" in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `your_work_projects_vue`. Disabled by default.
+
+{{< /history >}}
To view projects you are a member of:
@@ -111,9 +136,12 @@ To view projects you are a member of:
1. Select **View all my projects**.
1. Select the **Yours** tab.
-NOTE:
+{{< alert type="note" >}}
+
This tab appears as **Member** when the `your_work_projects_vue` feature flag is enabled.
+{{< /alert >}}
+
## View personal projects
Personal projects are projects created under your personal namespace.
@@ -217,8 +245,12 @@ To star a project:
## Delete a project
-> - Default deletion behavior for projects on the Premium and Ultimate tier changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 16.0.
-> - Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+{{< history >}}
+
+- Default deletion behavior for projects on the Premium and Ultimate tier changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 16.0.
+- Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+
+{{< /history >}}
You can mark a project to be deleted.
After you delete a project:
@@ -245,13 +277,20 @@ You can also [delete projects using the Rails console](troubleshooting.md#delete
### Delayed project deletion
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1.
-> - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3.
-> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1.
+- [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3.
+- Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+
+{{< /history >}}
Prerequisites:
@@ -269,16 +308,26 @@ and use the Rails console to
If the user who scheduled the project deletion loses access to the project (for example, by leaving the project, having their role downgraded, or being banned from the project) before the deletion occurs,
the deletion job will instead restore and unarchive the project, so the project will no longer be scheduled for deletion.
- WARNING:
+ {{< alert type="warning" >}}
+
If the user who scheduled the project deletion regains Owner role or administrator access before the job runs, then the job removes the project permanently.
+ {{< /alert >}}
+
### Delete a project immediately
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Option to delete projects immediately from the **Admin** area and as a group setting removed [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Option to delete projects immediately from the **Admin** area and as a group setting removed [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
+
+{{< /history >}}
If you don't want to wait for delayed deletion, you can delete a project immediately. To do this, perform the steps for [deleting a projects](#delete-a-project) again.
@@ -300,11 +349,18 @@ To immediately delete a project marked for deletion:
### View projects pending deletion
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/13066) tab label from "Pending deletion" to "Inactive" in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `your_work_projects_vue`. Disabled by default.
+{{< history >}}
+
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/13066) tab label from "Pending deletion" to "Inactive" in GitLab 17.9 [with a flag](../../administration/feature_flags.md) named `your_work_projects_vue`. Disabled by default.
+
+{{< /history >}}
To view a list of all projects that are pending deletion:
@@ -312,9 +368,12 @@ To view a list of all projects that are pending deletion:
1. Select **View all my projects**.
1. Select the **Pending deletion** tab.
-NOTE:
+{{< alert type="note" >}}
+
This tab appears as **Inactive** when the `your_work_projects_vue` feature flag is enabled.
+{{< /alert >}}
+
Each project in the list shows:
- A badge indicating that the project has been marked for deletion.
@@ -324,9 +383,12 @@ Each project in the list shows:
## Restore a project
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Prerequisites:
@@ -342,7 +404,11 @@ To restore a project marked for deletion:
## Archive a project
-> - Pages removal [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343109) in GitLab 17.5.
+{{< history >}}
+
+- Pages removal [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343109) in GitLab 17.5.
+
+{{< /history >}}
When you archive a project, some features become read-only.
These features are still accessible, but not writable.
@@ -443,8 +509,12 @@ You can sort projects by:
### Filter projects by language
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385465) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `project_language_search`. Enabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110956) in GitLab 15.9. Feature flag `project_language_search` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385465) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `project_language_search`. Enabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110956) in GitLab 15.9. Feature flag `project_language_search` removed.
+
+{{< /history >}}
You can filter projects by the programming language they use. To do this:
@@ -477,10 +547,13 @@ Prerequisites:
- You must be an administrator or have the Maintainer or Owner role for the project.
-NOTE:
+{{< alert type="note" >}}
+
When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see
[redirects when renaming repositories](repository/_index.md#repository-path-changes).
+{{< /alert >}}
+
To rename a repository:
1. On the left sidebar, select **Search or go to** and find your project.
@@ -491,7 +564,11 @@ To rename a repository:
## Leave a project
-> - The button to leave a project [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7.
+{{< history >}}
+
+- The button to leave a project [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7.
+
+{{< /history >}}
When you leave a project:
@@ -507,14 +584,17 @@ Prerequisites:
To leave a project:
1. On the left sidebar, select **Search or go to** and find your project.
-1. On the project overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**).
+1. On the project overview page, in the upper-right corner, select **Actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Leave project**, then **Leave project** again.
## Add a compliance framework to a project
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can add compliance frameworks to projects in a group that has a [compliance framework](../group/compliance_frameworks.md).
@@ -536,9 +616,12 @@ Prerequisites:
## Project aliases
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab repositories are usually accessed with a namespace and a project name. When migrating
frequently accessed repositories to GitLab, however, you can use project aliases to access those
diff --git a/doc/user/public_access.md b/doc/user/public_access.md
index 9cdbbd5af6569687a4a97a736465958f5ce1f456..ff8f3875c12fc963fb854b9a03d5964d0611ae0c 100644
--- a/doc/user/public_access.md
+++ b/doc/user/public_access.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Project and group visibility
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Projects and groups in GitLab can be private, internal, or public.
@@ -28,17 +31,23 @@ Users with the Guest role cannot clone the project.
Private groups can have only private subgroups and projects.
-NOTE:
+{{< alert type="note" >}}
+
When you [share a private group with another group](project/members/sharing_projects_groups.md#invite-a-group-to-a-group),
users who don't have access to the private group can view a list of users who have access to the inviting group
through the endpoint `https://gitlab.com/groups/<inviting-group-name>/-/autocomplete_sources/members`.
However, the name and path of the private group are masked, and the users' membership source is not displayed.
+{{< /alert >}}
+
## Internal projects and groups
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
For internal projects, any authenticated user, including users with the Guest role, can:
@@ -60,11 +69,14 @@ For public projects, any user, including unauthenticated users, can:
Public groups can have public, internal, or private subgroups and projects.
-NOTE:
+{{< alert type="note" >}}
+
If an administrator restricts the
[**Public** visibility level](../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels),
then the public access directory (`/public`) is visible only to authenticated users.
+{{< /alert >}}
+
## Change project visibility
You can change the visibility of a project.
@@ -116,9 +128,12 @@ Prerequisites:
## Restrict use of public or internal projects
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Administrators can restrict which visibility levels users can choose when they create a project or a snippet.
This setting can help prevent users from publicly exposing their repositories by accident.
diff --git a/doc/user/read_only_namespaces.md b/doc/user/read_only_namespaces.md
index ef392e5866a7199ca1e9b92ced64fef4f9f52911..7e8e552598f9401c6c85ba662b5440d199a1c983 100644
--- a/doc/user/read_only_namespaces.md
+++ b/doc/user/read_only_namespaces.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Read-only namespaces
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
On GitLab.com, a top-level namespace is placed in a read-only state when it either:
diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md
index eec74563b6ecf8b8bc0adb0a8d8e289fcf84af24..00e2e33b60627040ba32a17a7a14c8c12404b5c2 100644
--- a/doc/user/report_abuse.md
+++ b/doc/user/report_abuse.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Report abuse
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can report abuse from other GitLab users to GitLab administrators.
@@ -30,37 +33,48 @@ You can report a user through their:
## Report abuse from the user's profile page
-> - Report abuse from overflow menu [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414773) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `user_profile_overflow_menu_vue`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/414773) in GitLab 16.4.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/414773) in GitLab 16.6. Feature flag `user_profile_overflow_menu_vue` removed.
+{{< history >}}
+
+- Report abuse from overflow menu [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414773) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `user_profile_overflow_menu_vue`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/414773) in GitLab 16.4.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/414773) in GitLab 16.6. Feature flag `user_profile_overflow_menu_vue` removed.
+
+{{< /history >}}
To report abuse from a user's profile page:
1. Anywhere in GitLab, select the name of the user.
-1. In the upper-right corner of the user's profile select the vertical ellipsis (**{ellipsis_v}**), then **Report abuse**.
+1. In the upper-right corner of the user's profile select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then **Report abuse**.
1. Select a reason for reporting the user.
1. Complete an abuse report.
1. Select **Send report**.
## Report abuse from a user's comment
-> - Reporting abuse from comments in epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389992) in GitLab 15.10.
+{{< history >}}
+
+- Reporting abuse from comments in epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389992) in GitLab 15.10.
+
+{{< /history >}}
To report abuse from a user's comment:
-1. In the comment, in the upper-right corner, select **More actions** (**{ellipsis_v}**).
+1. In the comment, in the upper-right corner, select **More actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Report abuse**.
1. Select a reason for reporting the user.
1. Complete an abuse report.
1. Select **Send report**.
-NOTE:
+{{< alert type="note" >}}
+
A URL to the reported user's comment is pre-filled in the abuse report's
**Message** field.
+{{< /alert >}}
+
## Report abuse from an issue
-1. On the issue, in the upper-right corner, select **Issue actions** (**{ellipsis_v}**).
+1. On the issue, in the upper-right corner, select **Issue actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Report abuse**.
1. Select a reason for reporting the user.
1. Complete an abuse report.
@@ -68,9 +82,13 @@ A URL to the reported user's comment is pre-filled in the abuse report's
## Report abuse from a task
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461848) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461848) in GitLab 17.3.
-1. On the task, in the upper-right corner, select **More actions** (**{ellipsis_v}**).
+{{< /history >}}
+
+1. On the task, in the upper-right corner, select **More actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Report abuse**.
1. Select a reason for reporting the user.
1. Complete an abuse report.
@@ -78,9 +96,13 @@ A URL to the reported user's comment is pre-filled in the abuse report's
## Report abuse from an objective
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461848) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461848) in GitLab 17.3.
-1. On the objective, in the upper-right corner, select **More actions** (**{ellipsis_v}**).
+{{< /history >}}
+
+1. On the objective, in the upper-right corner, select **More actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Report abuse**.
1. Select a reason for reporting the user.
1. Complete an abuse report.
@@ -88,9 +110,13 @@ A URL to the reported user's comment is pre-filled in the abuse report's
## Report abuse from a key result
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461848) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/461848) in GitLab 17.3.
+
+{{< /history >}}
-1. On the key result, in the upper-right corner, select **More actions** (**{ellipsis_v}**).
+1. On the key result, in the upper-right corner, select **More actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Report abuse**.
1. Select a reason for reporting the user.
1. Complete an abuse report.
@@ -98,7 +124,7 @@ A URL to the reported user's comment is pre-filled in the abuse report's
## Report abuse from a merge request
-1. On the merge request, in the upper-right corner, select **Merge request actions** (**{ellipsis_v}**).
+1. On the merge request, in the upper-right corner, select **Merge request actions** ({{< icon name="ellipsis_v" >}}).
1. Select **Report abuse**.
1. Select a reason for reporting this user.
1. Complete an abuse report.
diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md
index 8a55fe34071f732c04973dceca0a2aeca2e191ce..729acad8ac3e278d9dbe282f7114c056ebfcfaca 100644
--- a/doc/user/reserved_names.md
+++ b/doc/user/reserved_names.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Reserved project and group names
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
To not conflict with existing routes used by GitLab, some words cannot be used as project or group names.
These words are listed in the
diff --git a/doc/user/rich_text_editor.md b/doc/user/rich_text_editor.md
index f147e4e1b5da1fb7cc1b3a29ae1523b4a689cd3b..84b37fd14cc878b5e753972acb14b86a612a0726 100644
--- a/doc/user/rich_text_editor.md
+++ b/doc/user/rich_text_editor.md
@@ -5,15 +5,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Rich text editor
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371931) for editing issue descriptions in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382636) for [discussions](discussions/_index.md), and creating and editing issues and merge requests in GitLab 15.11 with the same flag.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407507) for epics in GitLab 16.1 with the same flag.
-> - Feature flag `content_editor_on_issues` enabled by default in GitLab 16.2.
-> - Feature flag `content_editor_on_issues` removed in GitLab 16.5.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371931) for editing issue descriptions in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382636) for [discussions](discussions/_index.md), and creating and editing issues and merge requests in GitLab 15.11 with the same flag.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407507) for epics in GitLab 16.1 with the same flag.
+- Feature flag `content_editor_on_issues` enabled by default in GitLab 16.2.
+- Feature flag `content_editor_on_issues` removed in GitLab 16.5.
+
+{{< /history >}}
Rich text editor is available in:
@@ -85,7 +92,7 @@ list items, diagrams (or even another table!) in table cells.
To insert a table:
-1. Select **Insert table** **{table}**.
+1. Select **Insert table** {{< icon name="table" >}}.
1. From the dropdown list, select the dimensions of the new table.
@@ -94,7 +101,7 @@ To insert a table:
Inside a table cell, you can use a menu to insert or delete rows or columns.
-To open the menu: In the upper-right corner of a cell, select the chevron **{chevron-down}**.
+To open the menu: In the upper-right corner of a cell, select the chevron {{< icon name="chevron-down" >}}.
@@ -105,9 +112,9 @@ Select multiple cells and merge or split them.
To merge selected cells into one:
1. Select multiple cells - select one and drag your cursor.
-1. In the upper-right corner of a cell, select the chevron **{chevron-down}** **> Merge N cells**.
+1. In the upper-right corner of a cell, select the chevron {{< icon name="chevron-down" >}} **> Merge N cells**.
-To split merged cells: In the upper-right corner of a cell, select the chevron **{chevron-down}** **> Split cell**.
+To split merged cells: In the upper-right corner of a cell, select the chevron {{< icon name="chevron-down" >}} **> Split cell**.
## Insert diagrams
@@ -116,7 +123,7 @@ preview them live as you type the diagram code.
To insert a diagram:
-1. On the top bar of a text box, select **{plus}** **More options** and then **Mermaid diagram** or **PlantUML diagram**.
+1. On the top bar of a text box, select {{< icon name="plus" >}} **More options** and then **Mermaid diagram** or **PlantUML diagram**.
1. Enter the code for your diagram. The diagram preview appears in the text box.
diff --git a/doc/user/search/_index.md b/doc/user/search/_index.md
index eafecd9823d07571876df7ec9cc5e3cebb8d44af..e766033d082cd282ba8acf42c5f387cabc710f51 100644
--- a/doc/user/search/_index.md
+++ b/doc/user/search/_index.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Searching in GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab has three types of search: **basic search**, [**advanced search**](advanced_search.md),
and [**exact code search**](exact_code_search.md).
@@ -22,7 +25,11 @@ For code search, GitLab uses these types in this order:
## Specify a search type
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161999) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/161999) in GitLab 17.4.
+
+{{< /history >}}
To specify a search type, set the `search_type` URL parameter as follows:
@@ -35,8 +42,11 @@ For more information, see [issue 477333](https://gitlab.com/gitlab-org/gitlab/-/
## Restrict search access
-DETAILS:
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
Prerequisites:
@@ -56,11 +66,18 @@ enable the `ops` feature flag `block_anonymous_global_searches`.
## Disable global search scopes
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/179688) in GitLab 17.9.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/179688) in GitLab 17.9.
+{{< /history >}}
Prerequisites:
@@ -80,8 +97,12 @@ To disable one or more global search scopes:
## Global search validation
-> - Support for partial matches in issue search [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71913) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `issues_full_text_search`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124703) in GitLab 16.2. Feature flag `issues_full_text_search` removed.
+{{< history >}}
+
+- Support for partial matches in issue search [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71913) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `issues_full_text_search`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124703) in GitLab 16.2. Feature flag `issues_full_text_search` removed.
+
+{{< /history >}}
Global search ignores and logs as abusive any search that includes:
@@ -136,8 +157,12 @@ The results are displayed. To filter the results, on the left sidebar, select a
## Search for a project by full path
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed.
+
+{{< /history >}}
You can search for a project by entering its full path (including the namespace it belongs to) in the search box.
As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed.
@@ -149,8 +174,12 @@ For example:
## Include archived projects in search results
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121981) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `search_projects_hide_archived` for project search. Disabled by default.
-> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/10957) in GitLab 16.6 for all search scopes.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121981) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `search_projects_hide_archived` for project search. Disabled by default.
+- [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/10957) in GitLab 16.6 for all search scopes.
+
+{{< /history >}}
By default, archived projects are excluded from search results.
To include archived projects in search results:
@@ -171,7 +200,11 @@ To search for code in all GitLab, ask your administrator to enable [advanced sea
### View Git blame from code search
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327052) in GitLab 14.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327052) in GitLab 14.7.
+
+{{< /history >}}
After you find search results, you can view who made the last change to the line
where the results were found.
@@ -181,7 +214,11 @@ where the results were found.
### Filter code search results by language
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342651) in GitLab 15.10.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342651) in GitLab 15.10.
+
+{{< /history >}}
To filter code search results by one or more languages:
diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md
index f16f3643933b2def9b6f8938719b9264863ec005..982187a74e344b953cee96161706824dc03a1a70 100644
--- a/doc/user/search/advanced_search.md
+++ b/doc/user/search/advanced_search.md
@@ -1,15 +1,22 @@
---
stage: Foundations
group: Global Search
-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"
+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
title: Advanced search
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Moved to GitLab Premium in 13.9.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Moved to GitLab Premium in 13.9.
+
+{{< /history >}}
You can use advanced search for faster, more efficient search across the entire GitLab
instance. Advanced search is based on Elasticsearch, a purpose-built full-text search
@@ -42,7 +49,11 @@ You can use advanced search in:
<!-- Remember to also update the tables in `doc/drawers/advanced_search_syntax.md` -->
-> - Refining user search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388409) in GitLab 15.10.
+{{< history >}}
+
+- Refining user search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388409) in GitLab 15.10.
+
+{{< /history >}}
Advanced search uses [`simple_query_string`](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html),
which supports both exact and fuzzy queries.
diff --git a/doc/user/search/command_palette.md b/doc/user/search/command_palette.md
index 1d5afe73d11b539e00ff7d54e1a2b57d1a31387d..c4591d2d7d9f9e679a5f816d135f947b6e4e461e 100644
--- a/doc/user/search/command_palette.md
+++ b/doc/user/search/command_palette.md
@@ -1,16 +1,23 @@
---
stage: Foundations
group: Personal Productivity
-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"
+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
title: Command palette
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - Introduced in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `command_palette`. Enabled by default.
-> - Feature flag `command_palette` removed in GitLab 16.4.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- Introduced in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `command_palette`. Enabled by default.
+- Feature flag `command_palette` removed in GitLab 16.4.
+
+{{< /history >}}
You can use command palette to narrow down the scope of your search or to
find an object more quickly.
diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md
index 02fe40df738b6e9180b9361f1dca22f8e016708f..dc5674b85860faf701a00587228de0a78aec2344 100644
--- a/doc/user/search/exact_code_search.md
+++ b/doc/user/search/exact_code_search.md
@@ -1,23 +1,33 @@
---
stage: Foundations
group: Global Search
-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"
+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
title: Exact code search
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
-**Status:** Beta
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 15.9 [with flags](../../administration/feature_flags.md) named `index_code_with_zoekt` and `search_code_with_zoekt`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/388519) in GitLab 16.6.
-> - Feature flags `index_code_with_zoekt` and `search_code_with_zoekt` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148378) in GitLab 17.1.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 15.9 [with flags](../../administration/feature_flags.md) named `index_code_with_zoekt` and `search_code_with_zoekt`. Disabled by default.
+- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/388519) in GitLab 16.6.
+- Feature flags `index_code_with_zoekt` and `search_code_with_zoekt` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148378) in GitLab 17.1.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
This feature is in [beta](../../policy/development_stages_support.md#beta) and subject to change without notice.
For more information, see [epic 9404](https://gitlab.com/groups/gitlab-org/-/epics/9404).
+{{< /alert >}}
+
With exact code search, you can use exact match and regular expression modes
to search for code in all GitLab or in a specific project.
@@ -37,13 +47,20 @@ to use [advanced search](advanced_search.md) instead.
## Zoekt search API
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143666) in GitLab 16.9 [with a flag](../../administration/feature_flags.md) named `zoekt_search_api`. Enabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143666) in GitLab 16.9 [with a flag](../../administration/feature_flags.md) named `zoekt_search_api`. Enabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
With the Zoekt search API, you can use the [search API](../../api/search.md) for exact code search.
If you want to use [advanced search](advanced_search.md) or basic search instead, see
[specify a search type](_index.md#specify-a-search-type).
@@ -53,13 +70,20 @@ To request access to this feature, contact GitLab.
## Global code search
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147077) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `zoekt_cross_namespace_search`. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/147077) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `zoekt_cross_namespace_search`. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
Use this feature to search code across the entire GitLab instance.
Global code search does not perform well on large GitLab instances.
@@ -67,8 +91,12 @@ When this feature is enabled for instances with more than 20,000 projects, your
## Search modes
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434417) in GitLab 16.8 [with a flag](../../administration/feature_flags.md) named `zoekt_exact_search`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/436457) in GitLab 17.3. Feature flag `zoekt_exact_search` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/434417) in GitLab 16.8 [with a flag](../../administration/feature_flags.md) named `zoekt_exact_search`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/436457) in GitLab 17.3. Feature flag `zoekt_exact_search` removed.
+
+{{< /history >}}
GitLab has two search modes:
@@ -77,7 +105,7 @@ GitLab has two search modes:
The exact match mode is used by default.
To switch to the regular expression mode, to the right of the search box,
-select **Use regular expression** (**{regular-expression}**).
+select **Use regular expression** ({{< icon name="regular-expression" >}}).
### Syntax
diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md
index a600f2af2e09a6f4785ea210be01e5bf0eb94d7b..bf9da9179899bedd4243490fc61f206f0901deba 100644
--- a/doc/user/shortcuts.md
+++ b/doc/user/shortcuts.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: GitLab keyboard shortcuts
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
GitLab has several keyboard shortcuts you can use to access its different
features.
@@ -224,9 +227,12 @@ These shortcuts are available when editing a file with the
## Epics
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
These shortcuts are available when viewing [epics](group/epics/_index.md):
@@ -238,7 +244,11 @@ These shortcuts are available when viewing [epics](group/epics/_index.md):
## Disable keyboard shortcuts
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/202494) from the shortcuts page to user preferences in GitLab 16.4.
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/202494) from the shortcuts page to user preferences in GitLab 16.4.
+
+{{< /history >}}
To disable keyboard shortcuts:
@@ -249,7 +259,11 @@ To disable keyboard shortcuts:
## Enable keyboard shortcuts
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/202494) from the shortcuts page to user preferences in GitLab 16.4.
+{{< history >}}
+
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/202494) from the shortcuts page to user preferences in GitLab 16.4.
+
+{{< /history >}}
To enable keyboard shortcuts:
diff --git a/doc/user/snippets.md b/doc/user/snippets.md
index 7479f90051ff3400b775265d515602751e1cb020..0a8cdb3a13847d05c739450a984e6c16ea884c08 100644
--- a/doc/user/snippets.md
+++ b/doc/user/snippets.md
@@ -1,14 +1,17 @@
---
stage: Create
group: Source Code
-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"
-description: "Use snippets to store and share code, text, and files from your browser. Snippets support version control, commenting, and embedding."
+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
+description: Use snippets to store and share code, text, and files from your browser. Snippets support version control, commenting, and embedding.
title: Snippets
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
With GitLab snippets, you can store and share bits of code and text with other users.
You can [comment on](#comment-on-snippets), [clone](#clone-snippets), and
@@ -33,12 +36,15 @@ GitLab provides two types of snippets:
- **Project snippets**: Always related to a specific project.
Project snippets can be visible publicly, or to only project members.
-NOTE:
+{{< alert type="note" >}}
+
From July 2019, the `Internal` visibility setting is disabled for new projects, groups,
and snippets on GitLab.com. Existing snippets using the `Internal`
visibility setting keep this setting. You can read more about the change in the
[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/12388).
+{{< /alert >}}
+
## Create snippets
You can create snippets in multiple ways, depending on whether you want to create a personal or project snippet:
@@ -47,15 +53,15 @@ You can create snippets in multiple ways, depending on whether you want to creat
- **To create a personal snippet**, do one of the following:
- On the [Snippets dashboard](https://gitlab.com/dashboard/snippets), select
**New snippet**.
- - From a project: On the left sidebar, select **Create new** (**{plus}**). Below **In GitLab**, select **New snippet**.
- - From any other page: On the left sidebar, select **Create new** (**{plus}**) and then **New snippet**.
+ - From a project: On the left sidebar, select **Create new** ({{< icon name="plus" >}}). Below **In GitLab**, select **New snippet**.
+ - From any other page: On the left sidebar, select **Create new** ({{< icon name="plus" >}}) and then **New snippet**.
- From the `glab` CLI, using the
[`glab snippet create`](https://gitlab.com/gitlab-org/cli/-/blob/main/docs/source/snippet/create.md) command.
For full instructions, see the command's documentation.
- If you installed the [GitLab Workflow extension for VS Code](../editor_extensions/visual_studio_code/_index.md),
use the [`Gitlab: Create snippet` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet).
- **To create a project snippet**: Go to your project's page. Select
- **Create new** (**{plus}**). Below **In this project**, select **New snippet**.
+ **Create new** ({{< icon name="plus" >}}). Below **In this project**, select **New snippet**.
1. In **Title**, add a title.
1. Optional. In **Description**, describe the snippet.
1. In **Files**, give your file an appropriate name and extension, such as `example.rb` or `index.html`.
@@ -224,9 +230,12 @@ which can encourage user collaboration.
## Mark snippet as spam
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Administrators on GitLab Self-Managed can mark snippets as spam.
diff --git a/doc/user/ssh.md b/doc/user/ssh.md
index 2d71d6f876d5175391c38ff8aa7f4b74201384a2..1ef85bc505c427d6c204dc2483e6f4c28c188da1 100644
--- a/doc/user/ssh.md
+++ b/doc/user/ssh.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Use SSH keys to communicate with GitLab
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Git is a distributed version control system, which means you can work locally,
then share or *push* your changes to a server. In this case, the server you push to is GitLab.
@@ -72,7 +75,11 @@ must have [OpenSSH 8.2](https://www.openssh.com/releasenotes.html#8.2) or later
### RSA SSH keys
-> - Maximum RSA key length [changed](https://gitlab.com/groups/gitlab-org/-/epics/11186) in GitLab 16.3.
+{{< history >}}
+
+- Maximum RSA key length [changed](https://gitlab.com/groups/gitlab-org/-/epics/11186) in GitLab 16.3.
+
+{{< /history >}}
Available documentation suggests ED25519 is more secure than RSA.
@@ -297,8 +304,12 @@ For more information about using 1Password with SSH keys, see the [1Password doc
## Add an SSH key to your GitLab account
-> - Suggested default expiration date for keys [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271239) in GitLab 15.4.
-> - Usage types for SSH keys [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383046) in GitLab 15.7.
+{{< history >}}
+
+- Suggested default expiration date for keys [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271239) in GitLab 15.4.
+- Usage types for SSH keys [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383046) in GitLab 15.7.
+
+{{< /history >}}
To use SSH with GitLab, copy your public key to your GitLab account:
@@ -421,7 +432,11 @@ Removing your SSH key has additional implications if you sign your commits with
### Revoke an SSH key
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108344) in GitLab 15.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108344) in GitLab 15.9.
+
+{{< /history >}}
If your SSH key becomes compromised, revoke the key.
@@ -444,7 +459,7 @@ To delete an SSH key:
1. On the left sidebar, select your avatar.
1. Select **Edit profile**.
1. On the left sidebar, select **SSH Keys**.
-1. Next to the key you want to delete, select **Remove** (**{remove}**).
+1. Next to the key you want to delete, select **Remove** ({{< icon name="remove" >}}).
1. Select **Delete**.
## Use different accounts on a single GitLab instance
@@ -488,10 +503,13 @@ To update a previously-cloned repository that is aliased as `origin`:
git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
```
-NOTE:
+{{< alert type="note" >}}
+
Private and public keys contain sensitive data. Ensure the permissions
on the files make them readable to you but not accessible to others.
+{{< /alert >}}
+
## Configure two-factor authentication (2FA)
You can set up two-factor authentication (2FA) for
diff --git a/doc/user/storage_management_automation.md b/doc/user/storage_management_automation.md
index 1f39ff37bc0c27cb1966dcccefc896a8a63ea3d2..0edc65f110a531eb84d6a212e2e6c682a3cc7efa 100644
--- a/doc/user/storage_management_automation.md
+++ b/doc/user/storage_management_automation.md
@@ -5,9 +5,12 @@ info: This page is maintained by Developer Relations, author @dnsmichi, see http
title: Automate storage management
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
This page describes how to automate storage analysis and cleanup to manage your storage usage
with the GitLab REST API.
@@ -16,10 +19,13 @@ You can also manage your storage usage by improving [pipeline efficiency](../ci/
For more help with API automation, you can also use the [GitLab community forum and Discord](https://about.gitlab.com/community/).
-WARNING:
+{{< alert type="warning" >}}
+
The script examples in this page are for demonstration purposes only and should not
be used in production. You can use the examples to design and test your own scripts for storage automation.
+{{< /alert >}}
+
## API requirements
To automate storage management, your GitLab.com SaaS or self-managed instance must have access to the [GitLab REST API](../api/api_resources.md).
@@ -48,9 +54,9 @@ To format JSON responses, install `jq`. For more information, see [Tips for prod
To use these tools with the REST API:
-::Tabs
+{{< tabs >}}
-:::TabTitle curl
+{{< tab title="curl" >}}
```shell
export GITLAB_TOKEN=xxx
@@ -58,7 +64,9 @@ export GITLAB_TOKEN=xxx
curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/user" | jq
```
-:::TabTitle GitLab CLI
+{{< /tab >}}
+
+{{< tab title="GitLab CLI" >}}
```shell
glab auth login
@@ -66,7 +74,9 @@ glab auth login
glab api groups/YOURGROUPNAME/projects
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
#### Using the GitLab CLI
@@ -89,9 +99,12 @@ see [Efficient DevSecOps workflows: Hands-on `python-gitlab` API automation](htt
For more information about other API client libraries, see [Third-party clients](../api/rest/third_party_clients.md).
-NOTE:
+{{< alert type="note" >}}
+
Use [GitLab Duo Code Suggestions](project/repository/code_suggestions/_index.md) to write code more efficiently.
+{{< /alert >}}
+
## Storage analysis
### Identify storage types
@@ -111,9 +124,9 @@ This data provides insight into storage consumption of the project by the follow
To identify storage types:
-::Tabs
+{{< tabs >}}
-:::TabTitle curl
+{{< tab title="curl" >}}
```shell
curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$GL_PROJECT_ID?statistics=true" | jq --compact-output '.id,.statistics' | jq
@@ -132,7 +145,9 @@ curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com
}
```
-:::TabTitle GitLab CLI
+{{< /tab >}}
+
+{{< tab title="GitLab CLI" >}}
```shell
export GL_PROJECT_ID=48349590
@@ -152,7 +167,9 @@ glab api --method GET projects/$GL_PROJECT_ID --field 'statistics=true' | jq --c
}
```
-:::TabTitle Python
+{{< /tab >}}
+
+{{< tab title="Python" >}}
```python
project_obj = gl.projects.get(project.id, statistics=True)
@@ -160,7 +177,9 @@ project_obj = gl.projects.get(project.id, statistics=True)
print("Project {n} statistics: {s}".format(n=project_obj.name_with_namespace, s=json.dump(project_obj.statistics, indent=4)))
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
To print statistics for the project to the terminal, export the `GL_GROUP_ID` environment variable and run the script:
@@ -206,9 +225,9 @@ example code is not optimized for parallel API requests.
To implement this algorithm:
-::Tabs
+{{< tabs >}}
-:::TabTitle GitLab CLI
+{{< tab title="GitLab CLI" >}}
```shell
export GROUP_NAME="gitlab-da"
@@ -254,7 +273,9 @@ glab api projects/48349590/jobs | jq --compact-output '.[]' | jq --compact-outpu
[{"file_type":"archive","size":1049089,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":157,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3140,"filename":"job.log","file_format":null}]
```
-:::TabTitle Python
+{{< /tab >}}
+
+{{< tab title="Python" >}}
```python
#!/usr/bin/env python
@@ -296,7 +317,9 @@ if __name__ == "__main__":
print("DEBUG: ID {i}: {a}".format(i=job.id, a=job.attributes['artifacts']))
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
The script outputs the project job artifacts in a JSON formatted list:
@@ -328,9 +351,12 @@ The script outputs the project job artifacts in a JSON formatted list:
Job artifacts consume most of the pipeline storage, and job logs can also generate several hundreds of kilobytes.
You should delete the unnecessary job artifacts first and then clean up job logs after analysis.
-WARNING:
+{{< alert type="warning" >}}
+
Deleting job log and artifacts is a destructive action that cannot be reverted. Use with caution. Deleting certain files, including report artifacts, job logs, and metadata files, affects GitLab features that use these files as data sources.
+{{< /alert >}}
+
### List job artifacts
To analyze pipeline storage, you can use the [Job API endpoint](../api/jobs.md#list-project-jobs) to retrieve a list of
@@ -510,9 +536,9 @@ The [artifacts for the most recent successful jobs](../ci/jobs/job_artifacts.md#
To delete all job artifacts for a project:
-::Tabs
+{{< tabs >}}
-:::TabTitle curl
+{{< tab title="curl" >}}
```shell
export GL_PROJECT_ID=48349590
@@ -520,7 +546,9 @@ export GL_PROJECT_ID=48349590
curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" --request DELETE "https://gitlab.com/api/v4/projects/$GL_PROJECT_ID/artifacts"
```
-:::TabTitle GitLab CLI
+{{< /tab >}}
+
+{{< tab title="GitLab CLI" >}}
```shell
glab api --method GET projects/$GL_PROJECT_ID/jobs | jq --compact-output '.[]' | jq --compact-output '.id, .artifacts'
@@ -528,13 +556,17 @@ glab api --method GET projects/$GL_PROJECT_ID/jobs | jq --compact-output '.[]' |
glab api --method DELETE projects/$GL_PROJECT_ID/artifacts
```
-:::TabTitle Python
+{{< /tab >}}
+
+{{< tab title="Python" >}}
```python
project.artifacts.delete()
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Delete job logs
@@ -579,10 +611,13 @@ To delete pipelines based on a specific date, specify the `created_at` key.
You can use the date to calculate the difference between the current date and
when the pipeline was created. If the age is larger than the threshold, the pipeline is deleted.
-NOTE:
+{{< alert type="note" >}}
+
The `created_at` key must be converted from a timestamp to Unix epoch time,
for example with `date -d '2023-08-08T18:59:47.581Z' +%s`.
+{{< /alert >}}
+
Example with GitLab CLI:
```shell
@@ -607,9 +642,9 @@ In the following example that uses a Bash script:
- The exported environment variable `GL_PROJECT_ID`. Defaults to the GitLab predefined variable `CI_PROJECT_ID`.
- The exported environment variable `CI_SERVER_HOST` that points to the GitLab instance URL.
-::Tabs
+{{< tabs >}}
-:::TabTitle Using the API with glab
+{{< tab title="Using the API with glab" >}}
The full script `get_cicd_pipelines_compare_age_threshold_example.sh` is located in the [GitLab API with Linux Shell](https://gitlab.com/gitlab-da/use-cases/gitlab-api/gitlab-api-linux-shell) project.
@@ -688,7 +723,9 @@ main() {
main
```
-:::TabTitle Using the glab CLI
+{{< /tab >}}
+
+{{< tab title="Using the glab CLI" >}}
The full script `cleanup-old-pipelines.sh` is located in the [GitLab API with Linux Shell](https://gitlab.com/gitlab-da/use-cases/gitlab-api/gitlab-api-linux-shell) project.
@@ -736,7 +773,9 @@ $delete_cmd || error_exit "Pipeline deletion failed"
echo "Pipeline cleanup completed."
```
-:::TabTitle Using the API with Python
+{{< /tab >}}
+
+{{< tab title="Using the API with Python" >}}
You can also use the [`python-gitlab` API library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/pipelines_and_jobs.html#project-pipelines) and
the `created_at` attribute to implement a similar algorithm that compares the job artifact age:
@@ -759,7 +798,9 @@ the `created_at` attribute to implement a similar algorithm that compares the jo
pipeline_obj.delete()
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
Automatic deletion of old pipelines is proposed in [issue 338480](https://gitlab.com/gitlab-org/gitlab/-/issues/338480).
@@ -894,9 +935,9 @@ Container registries are available [for projects](../api/container_registry.md#w
To list Container Registries in a project:
-::Tabs
+{{< tabs >}}
-:::TabTitle curl
+{{< tab title="curl" >}}
```shell
export GL_PROJECT_ID=48057080
@@ -911,7 +952,9 @@ curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com
3401613
```
-:::TabTitle GitLab CLI
+{{< /tab >}}
+
+{{< tab title="GitLab CLI" >}}
```shell
export GL_PROJECT_ID=48057080
@@ -934,7 +977,9 @@ glab api --method GET projects/$GL_PROJECT_ID/registry/repositories/4435617/tags
3401613
```
-::EndTabs
+{{< /tab >}}
+
+{{< /tabs >}}
### Delete container images in bulk
@@ -945,11 +990,14 @@ you can configure:
- The number of image tags to keep matching the tag name (`keep_n`)
- The number of days before an image tag can be deleted (`older_than`)
-WARNING:
+{{< alert type="warning" >}}
+
On GitLab.com, due to the scale of the container registry, the number of tags deleted by this API is limited.
If your container registry has a large number of tags to delete, only some of them are deleted. You might need
to call the API multiple times. To schedule tags for automatic deletion, use a [cleanup policy](#create-a-cleanup-policy-for-containers) instead.
+{{< /alert >}}
+
The following example uses the [`python-gitlab` API library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/repository_tags.html) to fetch a list of tags, and calls the `delete_in_bulk()` method with filter parameters.
```python
diff --git a/doc/user/storage_usage_quotas.md b/doc/user/storage_usage_quotas.md
index 98549563ddfe1320522cf0c6bdfd523264ad1a40..104abab08eed5a14015e46ef59c7537b7597f828 100644
--- a/doc/user/storage_usage_quotas.md
+++ b/doc/user/storage_usage_quotas.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Storage
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com
+
+{{< /details >}}
All projects on GitLab.com have 10 GiB of free storage for their Git repository and Large File Storage (LFS).
@@ -19,9 +22,12 @@ Only the project's repository and LFS are included in the storage limit. The con
## View storage
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
You can view the following statistics for storage usage in projects and namespaces:
@@ -48,10 +54,13 @@ Storage usage is displayed in kibibytes (KiB), mebibytes (MiB),
or gibibytes (GiB). 1 KiB is 2^10 bytes (1024 bytes),
1 MiB is 2^20 bytes (1024 kibibytes), and 1 GiB is 2^30 bytes (1024 mebibytes).
-NOTE:
+{{< alert type="note" >}}
+
Storage usage labels are being transitioned from `KB` to `KiB`, `MB` to `MiB`, and `GB` to `GiB`. During this transition,
you might see references to `KB`, `MB`, and `GB` in the UI and documentation.
+{{< /alert >}}
+
## View project fork storage usage
A cost factor is applied to the storage consumed by project forks so that forks consume less namespace storage than their actual size. The cost factors for forks storage reduction applies only to namespace storage. It does not apply to project repository storage limits.
@@ -81,7 +90,7 @@ The **Storage** tab of the **Usage Quotas** page displays the following:
- Purchased storage available is running low.
- Projects that are at risk of becoming read-only if purchased storage available is zero.
- Projects that are read-only because purchased storage available is zero. Read-only projects are
- marked with an information icon (**{information-o}**) beside their name.
+ marked with an information icon ({{< icon name="information-o" >}}) beside their name.
The total storage includes the free and excess storage purchased.
The remaining excess storage is expressed as a percentage and calculated as:
@@ -93,9 +102,9 @@ The following example describes an excess storage scenario for projects in a nam
| Repository | Storage used | Excess storage | Quota | Status |
|------------|--------------|----------------|--------|----------------------|
-| Red | 10 GiB | 0 GiB | 10 GiB | Read-only **{lock}** |
+| Red | 10 GiB | 0 GiB | 10 GiB | Read-only {{< icon name="lock" >}} |
| Blue | 8 GiB | 0 GiB | 10 GiB | Not read-only |
-| Green | 10 GiB | 0 GiB | 10 GiB | Read-only **{lock}** |
+| Green | 10 GiB | 0 GiB | 10 GiB | Read-only {{< icon name="lock" >}} |
| Yellow | 2 GiB | 0 GiB | 10 GiB | Not read-only |
| **Totals** | **30 GiB** | **0 GiB** | - | - |
diff --git a/doc/user/tasks.md b/doc/user/tasks.md
index 4b2f84db0f59ea20a4f60cae870cc5b129703066..64a496e3c3fee04de99333bbc49692786b4d4936 100644
--- a/doc/user/tasks.md
+++ b/doc/user/tasks.md
@@ -5,18 +5,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: Tasks
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `work_items`. Disabled by default.
-> - Creating, editing, and deleting tasks [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7169) in GitLab 15.0.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.3.
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `work_items`. Disabled by default.
+- Creating, editing, and deleting tasks [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7169) in GitLab 15.0.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.3.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
A task in GitLab is a planning item that can be created in an issue.
Use tasks to break down user stories captured in [issues](project/issues/_index.md) into
smaller, trackable items.
@@ -47,8 +57,12 @@ the task opens in a full-page view.
## Create a task
-> - Option to select the project where tasks are created [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436255) in GitLab 17.1.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Option to select the project where tasks are created [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436255) in GitLab 17.1.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -66,8 +80,12 @@ To create a task:
### From a task list item
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -75,7 +93,7 @@ Prerequisites:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
-1. In the issue description, hover over a task list item and select the options menu (**{ellipsis_v}**).
+1. In the issue description, hover over a task list item and select the options menu ({{< icon name="ellipsis_v" >}}).
1. Select **Convert to task**.
The task list item is removed from the issue description and a task is created in the tasks widget from its contents.
@@ -83,7 +101,11 @@ Any nested task list items are moved up a nested level.
## Add existing tasks to an issue
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381868) in GitLab 15.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381868) in GitLab 15.6.
+
+{{< /history >}}
Prerequisites:
@@ -101,7 +123,11 @@ To add a task:
## Edit a task
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -114,16 +140,20 @@ To edit a task:
1. In the issue description, in the **Child items** section, select the task you want to edit.
The task window opens.
1. Optional. To edit the title, select it and make your changes.
-1. Optional. To edit the description, select the edit icon (**{pencil}**), make your changes, and
+1. Optional. To edit the description, select the edit icon ({{< icon name="pencil" >}}), make your changes, and
select **Save**.
-1. Select the close icon (**{close}**).
+1. Select the close icon ({{< icon name="close" >}}).
### Using the rich text editor
-> - Rich text editing in the dialog view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363007) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `work_items_mvc`. Disabled by default.
-> - Rich text editing in the full page view [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104533) in GitLab 15.7.
-> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/10378) in GitLab 16.2. Feature flag `work_items_mvc` removed.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- Rich text editing in the dialog view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363007) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `work_items_mvc`. Disabled by default.
+- Rich text editing in the full page view [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104533) in GitLab 15.7.
+- [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/10378) in GitLab 16.2. Feature flag `work_items_mvc` removed.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Use a rich text editor to edit a task's description.
@@ -137,14 +167,18 @@ To edit the description of a task:
1. Select **Plan > Issues**, then select your issue to view it.
1. In the issue description, in the **Child items** section, select the title of the task you want to edit.
The task window opens.
-1. Next to **Description**, select the edit icon (**{pencil}**). The description text box appears.
+1. Next to **Description**, select the edit icon ({{< icon name="pencil" >}}). The description text box appears.
1. Above the text box, select **Rich text**.
1. Make your changes, and select **Save**.
## Promote a task to an issue
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -172,10 +206,12 @@ The previous URL with `/work_items/` still works.
## Convert a task into another item type
-DETAILS:
+{{< history >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385131) in GitLab 17.8 [with a flag](../administration/feature_flags.md) named `work_items_beta`. Disabled by default.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/385131) [to the flag](../administration/feature_flags.md) named `okrs_mvc`. For current flag state, see the top of this page.
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385131) in GitLab 17.8 [with a flag](../administration/feature_flags.md) named `work_items_beta`. Disabled by default.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/385131) [to the flag](../administration/feature_flags.md) named `okrs_mvc`. For current flag state, see the top of this page.
+
+{{< /history >}}
Convert a task into another item type, such as:
@@ -183,9 +219,12 @@ Convert a task into another item type, such as:
- Objective
- Key result
-WARNING:
+{{< alert type="warning" >}}
+
Changing the type might result in data loss if the target type does not support all fields from the original type.
+{{< /alert >}}
+
Prerequisites:
- The task you want to convert must not have a parent item assigned.
@@ -197,7 +236,7 @@ To convert a task into another item type:
1. In the issue list, find your task.
1. Optional. If the task has a parent issue assigned, remove it.
Add a comment to the task with the `/remove_parent` quick action.
-1. In the upper-right corner, select **More actions** (**{ellipsis_v}**), then select **Change type**.
+1. In the upper-right corner, select **More actions** ({{< icon name="ellipsis_v" >}}), then select **Change type**.
1. Select the desired item type.
1. If all conditions are met, select **Change type**.
@@ -206,7 +245,11 @@ by `issue`, `objective` or `key result` in a comment.
## Remove a task from an issue
-> - Minimum required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/404799) from Reporter to Guest in GitLab 17.0.
+{{< history >}}
+
+- Minimum required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/404799) from Reporter to Guest in GitLab 17.0.
+
+{{< /history >}}
Prerequisites:
@@ -219,13 +262,17 @@ To remove a task from an issue:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
-1. In the issue description, in the **Child items** section, select the options menu (**{ellipsis_v}**)
+1. In the issue description, in the **Child items** section, select the options menu ({{< icon name="ellipsis_v" >}})
next to the task you want to remove.
1. Select **Remove task**.
## Delete a task
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Owner to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Owner to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -238,13 +285,17 @@ To delete a task:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
1. In the issue description, in the **Child items** section, select the task you want to edit.
-1. In the task window, in the options menu (**{ellipsis_v}**), select **Delete task**.
+1. In the task window, in the options menu ({{< icon name="ellipsis_v" >}}), select **Delete task**.
1. Select **OK**.
## Reorder tasks
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385887) in GitLab 16.0.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385887) in GitLab 16.0.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -255,8 +306,12 @@ To reorder them, drag them around.
## Assign users to a task
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334810) in GitLab 15.4.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334810) in GitLab 15.4.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
To show who is responsible for a task, you can assign users to it.
@@ -280,8 +335,12 @@ To change the assignee on a task:
## Assign labels to a task
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339756) in GitLab 15.5.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339756) in GitLab 15.5.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
Prerequisites:
@@ -298,9 +357,13 @@ To add [labels](project/labels.md) to a task:
## Set a start and due date
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365399) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365399) in GitLab 15.5. Feature flag `work_items_mvc_2` removed.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365399) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365399) in GitLab 15.5. Feature flag `work_items_mvc_2` removed.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can set a [start and due date](project/issues/due_dates.md) on a task.
@@ -331,10 +394,14 @@ To set a start date:
## Add a task to a milestone
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) to feature flag named `work_items_mvc` in GitLab 15.7. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) in GitLab 15.7. Feature flag `work_items_mvc` removed.
-> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) to feature flag named `work_items_mvc` in GitLab 15.7. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) in GitLab 15.7. Feature flag `work_items_mvc` removed.
+- [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/169256) the minimum user role from Reporter to Planner in GitLab 17.7.
+
+{{< /history >}}
You can add a task to a [milestone](project/milestones/_index.md).
You can see the milestone title when you view a task.
@@ -357,12 +424,19 @@ To add a task to a milestone:
## Set task weight
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.3.
-> - Edit button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429137) in GitLab 16.7.
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.3.
+- Edit button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429137) in GitLab 16.7.
+
+{{< /history >}}
Prerequisites:
@@ -383,12 +457,19 @@ To set issue weight of a task:
## Add a task to an iteration
-DETAILS:
-**Tier:** Premium, Ultimate
+{{< details >}}
+
+- Tier: Premium, Ultimate
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) to feature flag named `work_items_mvc` in GitLab 15.7. Disabled by default.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) in GitLab 15.7. Feature flag `work_items_mvc` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) to feature flag named `work_items_mvc` in GitLab 15.7. Disabled by default.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) in GitLab 15.7. Feature flag `work_items_mvc` removed.
+
+{{< /history >}}
You can add a task to an [iteration](group/iterations/_index.md).
You can see the iteration title and period only when you view a task.
@@ -408,7 +489,11 @@ To add a task to an iteration:
## Estimate and track spent time
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438577) in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438577) in GitLab 17.0.
+
+{{< /history >}}
You can estimate and track the time you spend on a task.
@@ -416,11 +501,15 @@ For more information, see [Time tracking](project/time_tracking.md).
## View task system notes
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) to feature flag named `work_items_mvc` in GitLab 15.8. Disabled by default.
-> - Changing activity sort order [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.8.
-> - Filtering activity [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389971) in GitLab 15.10.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.10. Feature flag `work_items_mvc` removed.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default.
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) to feature flag named `work_items_mvc` in GitLab 15.8. Disabled by default.
+- Changing activity sort order [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378949) in GitLab 15.8.
+- Filtering activity [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/389971) in GitLab 15.10.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.10. Feature flag `work_items_mvc` removed.
+
+{{< /history >}}
You can view all the system notes related to the task. By default they are sorted by **Oldest first**.
You can always change the sorting order to **Newest first**, which is remembered across sessions.
@@ -432,7 +521,11 @@ You can add [comments](discussions/_index.md) and reply to threads in tasks.
## Copy task reference
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1.
+
+{{< /history >}}
To refer to a task elsewhere in GitLab, you can use its full URL or a short reference, which looks like
`namespace/project-name#123`, where `namespace` is either a group or a username.
@@ -442,7 +535,7 @@ To copy the task reference to your clipboard:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
1. In the issue description, in the **Child items** section, select your task.
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**.
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then select **Copy Reference**.
You can now paste the reference into another description or comment.
@@ -450,7 +543,11 @@ For more information about task references, see [GitLab-Flavored Markdown](markd
## Copy task email address
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1.
+
+{{< /history >}}
You can create a comment in a task by sending an email.
Sending an email to this address creates a comment that contains the email body.
@@ -462,11 +559,15 @@ To copy the task's email address:
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Plan > Issues**, then select your issue to view it.
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy task email address**.
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then select **Copy task email address**.
## Set an issue as a parent
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 16.5.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 16.5.
+
+{{< /history >}}
Prerequisites:
@@ -487,7 +588,11 @@ next to **Parent**, select the dropdown list and then select **Unassign**.
## Confidential tasks
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8410) in GitLab 15.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8410) in GitLab 15.3.
+
+{{< /history >}}
Confidential tasks are tasks visible only to members of a project with
[sufficient permissions](#who-can-see-confidential-tasks).
@@ -518,7 +623,7 @@ Check that box and select **Create task**.
To change the confidentiality of an existing task:
1. [Open the task](#view-tasks).
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**).
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. Select **Turn on confidentiality**.
### Who can see confidential tasks
@@ -539,33 +644,43 @@ Confidential tasks are hidden in search results for users without the necessary
### Confidential task indicators
Confidential tasks are visually different from regular tasks in a few ways.
-Wherever tasks are listed, you can see the confidential (**{eye-slash}**) icon
+Wherever tasks are listed, you can see the confidential ({{< icon name="eye-slash" >}}) icon
next to the tasks that are marked as confidential.
If you don't have [enough permissions](#who-can-see-confidential-tasks),
you cannot see confidential tasks at all.
-Likewise, while inside the task, you can see the confidential (**{eye-slash}**) icon right next to
+Likewise, while inside the task, you can see the confidential ({{< icon name="eye-slash" >}}) icon right next to
the breadcrumbs.
Every change from regular to confidential and vice versa, is indicated by a
system note in the task's comments, for example:
-> - **{eye-slash}** Jo Garcia made the issue confidential 5 minutes ago
-> - **{eye}** Jo Garcia made the issue visible to everyone just now
+> - {{< icon name="eye-slash" >}} Jo Garcia made the issue confidential 5 minutes ago
+> - {{< icon name="eye" >}} Jo Garcia made the issue visible to everyone just now
## Lock discussion
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398649) in GitLab 16.9 [with a flag](../administration/feature_flags.md) named `work_items_beta`. Disabled by default.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398649) in GitLab 16.9 [with a flag](../administration/feature_flags.md) named `work_items_beta`. Disabled by default.
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
You can prevent public comments in a task.
When you do, only project members can add and edit comments.
@@ -575,7 +690,7 @@ Prerequisites:
To lock a task:
-1. In the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**).
+1. In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
1. Select **Lock discussion**.
A system note is added to the page details.
@@ -584,17 +699,27 @@ If a task is closed with a locked discussion, then you cannot reopen it until th
## Two-column layout
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. This feature is in [beta](../policy/development_stages_support.md).
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/446064) to feature flag named `work_items_beta` in GitLab 16.10. Disabled by default.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. This feature is in [beta](../policy/development_stages_support.md).
+- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/446064) to feature flag named `work_items_beta` in GitLab 16.10. Disabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.
+{{< /alert >}}
+
When enabled, tasks use a two-column layout, similar to issues.
The description and threads are on the left, and attributes, such as labels
or assignees, on the right.
@@ -606,11 +731,15 @@ If you find a bug, [comment on the feedback issue](https://gitlab.com/gitlab-org
## Linked items in tasks
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7.
-> - Adding related items by entering their URLs and IDs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427594) in GitLab 16.8.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150148) in GitLab 17.0. Feature flag `linked_work_items` removed.
-> - [Changed](https://gitlab.com/groups/gitlab-org/-/epics/10267) minimum required role from Reporter (if true) to Guest in GitLab 17.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7.
+- Adding related items by entering their URLs and IDs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/427594) in GitLab 16.8.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/150148) in GitLab 17.0. Feature flag `linked_work_items` removed.
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/10267) minimum required role from Reporter (if true) to Guest in GitLab 17.0.
+
+{{< /history >}}
Linked items are a bi-directional relationship and appear in a block below
the emoji reactions section. You can link an objective, key result, or a task in the same project with each other.
@@ -652,13 +781,17 @@ Prerequisites:
1. Select **Plan > Issues**, then select your issue to view it.
1. In the issue description, in the **Child items** section, select your task.
1. In the **Linked items** section of a task, next to each item, select the vertical
- ellipsis (**{ellipsis_v}**) and then select **Remove**.
+ ellipsis ({{< icon name="ellipsis_v" >}}) and then select **Remove**.
Due to the bi-directional relationship, the relationship no longer appears in either item.
### Add a merge request and automatically close tasks
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440851) in GitLab 17.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/440851) in GitLab 17.3.
+
+{{< /history >}}
You can set a task to close when a merge request merges.
@@ -672,7 +805,7 @@ Prerequisites:
- Use the [closing pattern](project/issues/managing_issues.md#closing-issues-automatically) that you would for adding a merge request to an issue.
- If your task is in the same project as your merge request, you can search for your task by typing <kbd>#</kbd> followed by the task's ID or title.
- If your task is in a different project, with a task open, copy the URL from the browser or
- copy the task's reference by selecting the vertical ellipsis (**{ellipsis_v}**) in the upper-right corner, then **Copy Reference**.
+ copy the task's reference by selecting the vertical ellipsis ({{< icon name="ellipsis_v" >}}) in the upper-right corner, then **Copy Reference**.
The merge requests are now visible in the main body, in the **Development** section.
diff --git a/doc/user/todos.md b/doc/user/todos.md
index 46532f9d766c0030e82a3fd58a67377e0bbd9af3..ce0cf04f3e71bd1c7eca7544adb5370ab633a909 100644
--- a/doc/user/todos.md
+++ b/doc/user/todos.md
@@ -5,9 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
title: To-Do List
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Your *To-Do List* is a chronological list of items waiting for your input.
The items are known as *to-do items*.
@@ -20,7 +23,7 @@ needed, a to-do item appears in your To-Do List.
To access your To-Do List:
-On the left sidebar, at the top, select **To-Do List** (**{task-done}**).
+On the left sidebar, at the top, select **To-Do List** ({{< icon name="task-done" >}}).
### Search the To-Do List
@@ -32,15 +35,22 @@ Also, you can sort them by [**Label priority**](project/labels.md#set-label-prio
## Actions that create to-do items
-> - Multiple to-do items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28355) in GitLab 13.8 [with a flag](../administration/feature_flags.md) named `multiple_todos`. Disabled by default.
-> - Member access request notifications [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374725) in GitLab 15.8.
-> - Multiple to-do items [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/28355) in GitLab 16.2.
-> - Multiple to-do items [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/28355) in GitLab 17.8. Feature flag `multiple_todos` enabled by default.
+{{< history >}}
+
+- Multiple to-do items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28355) in GitLab 13.8 [with a flag](../administration/feature_flags.md) named `multiple_todos`. Disabled by default.
+- Member access request notifications [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374725) in GitLab 15.8.
+- Multiple to-do items [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/28355) in GitLab 16.2.
+- Multiple to-do items [enabled on GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/28355) in GitLab 17.8. Feature flag `multiple_todos` enabled by default.
+
+{{< /history >}}
+
+{{< alert type="flag" >}}
-FLAG:
The availability of this feature is controlled by a feature flag.
For more information, see the history.
+{{< /alert >}}
+
Many to-do items are created automatically.
Some of the actions that add a to-do item to your To-Do List:
@@ -69,7 +79,11 @@ selected, you get a to-do item when you are eligible to approve a merge request.
## Create a to-do item
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390549) in objectives, key results, and tasks in GitLab 16.0.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390549) in objectives, key results, and tasks in GitLab 16.0.
+
+{{< /history >}}
You can manually add an item to your To-Do List.
@@ -83,7 +97,7 @@ You can manually add an item to your To-Do List.
- [Objective or key result](okrs.md)
- [Task](tasks.md)
-1. In the upper-right corner, select **Add a to-do item** (**{todo-add}**).
+1. In the upper-right corner, select **Add a to-do item** ({{< icon name="todo-add" >}}).
### Create a to-do item by mentioning someone
@@ -109,10 +123,10 @@ Hi, please message @frank :incoming_envelope:
If you marked a to-do item as done by mistake, you can re-add it from the **Done** tab:
-1. On the left sidebar, at the top, select **To-Do List** (**{task-done}**).
+1. On the left sidebar, at the top, select **To-Do List** ({{< icon name="task-done" >}}).
1. At the top, select **Done**.
1. [Find the to-do item](#search-the-to-do-list) you want to re-add.
-1. Next to this to-do item, select **Re-add this to-do item** **{redo}**.
+1. Next to this to-do item, select **Re-add this to-do item** {{< icon name="redo" >}}.
The to-do item is now visible in the **To Do** tab of the To-Do List.
@@ -150,8 +164,8 @@ You can manually mark a to-do item as done.
There are two ways to do this:
-- In the To-Do List, to the right of the to-do item, select **Mark as done** (**{check}**).
-- In the upper-right corner of the resource (for example, issue or merge request), select **Mark as done** (**{todo-done}**).
+- In the To-Do List, to the right of the to-do item, select **Mark as done** ({{< icon name="check" >}}).
+- In the upper-right corner of the resource (for example, issue or merge request), select **Mark as done** ({{< icon name="todo-done" >}}).
### Mark all to-do items as done
@@ -165,7 +179,7 @@ You can snooze to-do items to temporarily hide them from your main To-Do List. T
To snooze a to-do item:
-1. In your To-Do List, next to the to-do item you want to snooze, select Snooze (**{clock}**).
+1. In your To-Do List, next to the to-do item you want to snooze, select Snooze ({{< icon name="clock" >}}).
1. If you wish to snooze the to-do item until a specific time and date, select the
`Until a specific time and date` option. Otherwise, choose one of the preset snooze durations:
- For one hour
diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md
index 7ee895b371563c33e493f2ecede6377e728b7ac3..d1c95da3037f03033d26e25769da977b90e6a80c 100644
--- a/doc/user/usage_quotas.md
+++ b/doc/user/usage_quotas.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'storage_usage_quotas.md'
-remove_date: '2025-01-11'
+redirect_to: storage_usage_quotas.md
+remove_date: "2025-01-11"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/version.md b/doc/user/version.md
index 64d6626e085f80676c4505d4c3d7cc3233b00ce3..72bd4b263a652505b5d14d9f9cff77f02ec21fc8 100644
--- a/doc/user/version.md
+++ b/doc/user/version.md
@@ -1,14 +1,17 @@
---
stage: none
group: none
-description: Version information.
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
+description: Version information.
title: Find the GitLab version
---
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
+
+- Tier: Free, Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
Find the version of GitLab you're running.
diff --git a/doc/user/workspace/_index.md b/doc/user/workspace/_index.md
index 205ec7cc806437b3c1efb8f6db4c7fb4d724d484..ffa29998b169145b8e8f89cb0946d525c83f782a 100644
--- a/doc/user/workspace/_index.md
+++ b/doc/user/workspace/_index.md
@@ -2,17 +2,24 @@
stage: Create
group: Remote Development
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
-description: "Workspaces are virtual sandbox environments for creating and managing your GitLab development environments."
+description: Workspaces are virtual sandbox environments for creating and managing your GitLab development environments.
title: Workspaces
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed.
+
+{{< /history >}}
A workspace is a virtual sandbox environment for your code in GitLab.
You can use workspaces to create and manage isolated development environments for your GitLab projects.
@@ -38,7 +45,11 @@ A running workspace remains accessible to the user even if user permissions are
### Manage workspaces from a project
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125331) in GitLab 16.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125331) in GitLab 16.2.
+
+{{< /history >}}
To manage workspaces from a project:
@@ -48,10 +59,13 @@ To manage workspaces from a project:
- Restart, stop, or terminate an existing workspace.
- Create a new workspace.
-WARNING:
+{{< alert type="warning" >}}
+
When you terminate a workspace, GitLab deletes any unsaved or uncommitted data
in that workspace. The data cannot be recovered.
+{{< /alert >}}
+
### Deleting resources associated with a workspace
When you terminate a workspace, you delete all resources associated with the workspace.
@@ -66,7 +80,11 @@ To clean up orphaned resources, an administrator must manually delete the worksp
## Manage workspaces at the agent level
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419281) in GitLab 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419281) in GitLab 16.8.
+
+{{< /history >}}
To manage all workspaces associated with an agent:
@@ -76,10 +94,13 @@ To manage all workspaces associated with an agent:
1. Select the **Workspaces** tab.
1. From the list, you can restart, stop, or terminate an existing workspace.
-WARNING:
+{{< alert type="warning" >}}
+
When you terminate a workspace, GitLab deletes any unsaved or uncommitted data
in that workspace. The data cannot be recovered.
+{{< /alert >}}
+
### Identify an agent from a running workspace
In deployments that contain multiple agents, you might want to identify an agent from a running workspace.
@@ -102,7 +123,11 @@ Workspaces support both GitLab default devfile and custom devfiles.
### GitLab default devfile
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171230) in GitLab 17.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171230) in GitLab 17.8.
+
+{{< /history >}}
A GitLab default devfile is available for all projects when you create a workspace.
This devfile contains:
@@ -212,7 +237,11 @@ For more information, see the [VS Code documentation](https://code.visualstudio.
## Workspace add-ons
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385157) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385157) in GitLab 17.2.
+
+{{< /history >}}
The GitLab Workflow extension for VS Code is configured by default in workspaces.
@@ -224,11 +253,18 @@ For more information, see [GitLab Workflow extension for VS Code](https://gitlab
## Extension marketplace
-DETAILS:
-**Status:** Beta
+{{< details >}}
+
+- Status: Beta
+
+{{< /details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438491) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 16.9 [with a flag](../../administration/feature_flags.md) named `allow_extensions_marketplace_in_workspace`. Disabled by default.
-> - Feature flag `allow_extensions_marketplace_in_workspace` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454669) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438491) as a [beta](../../policy/development_stages_support.md#beta) in GitLab 16.9 [with a flag](../../administration/feature_flags.md) named `allow_extensions_marketplace_in_workspace`. Disabled by default.
+- Feature flag `allow_extensions_marketplace_in_workspace` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/454669) in GitLab 17.6.
+
+{{< /history >}}
You can use the
[extension marketplace](../project/web_ide/_index.md#extension-marketplace) in workspaces
@@ -238,8 +274,12 @@ The extension marketplace connects to the [Open VSX Registry](https://open-vsx.o
## Personal access token
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129715) in GitLab 16.4.
-> - `api` permission [added](https://gitlab.com/gitlab-org/gitlab/-/issues/385157) in GitLab 17.2.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129715) in GitLab 16.4.
+- `api` permission [added](https://gitlab.com/gitlab-org/gitlab/-/issues/385157) in GitLab 17.2.
+
+{{< /history >}}
When you [create a workspace](configuration.md#create-a-workspace), you get a personal access token
with `write_repository` and `api` permissions.
@@ -278,7 +318,11 @@ To delete the provisioned volume, you must terminate the workspace.
## Automatic workspace stop and termination
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14910) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14910) in GitLab 17.6.
+
+{{< /history >}}
By default, a workspace automatically:
diff --git a/doc/user/workspace/configuration.md b/doc/user/workspace/configuration.md
index ab08e3b9d95550f276e58dca9cc071cd7931ced4..2eee57e9673110e2826c482a082c1ebe10599680 100644
--- a/doc/user/workspace/configuration.md
+++ b/doc/user/workspace/configuration.md
@@ -2,17 +2,24 @@
stage: Create
group: Remote Development
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
-description: "Configure your GitLab workspaces to manage your GitLab development environments."
+description: Configure your GitLab workspaces to manage your GitLab development environments.
title: Configure workspaces
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed.
+
+{{< /history >}}
You can use [workspaces](_index.md) to create and manage isolated development environments for your GitLab projects.
Each workspace includes its own set of dependencies, libraries, and tools,
@@ -41,15 +48,22 @@ To set up infrastructure for workspaces:
## Create a workspace
-> - Support for private projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124273) in GitLab 16.4.
-> - **Git reference** and **Devfile location** [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392382) in GitLab 16.10.
-> - **Time before automatic termination** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/392382) to **Workspace automatically terminates after** in GitLab 16.10.
-> - **Variables** [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463514) in GitLab 17.1.
-> - **Workspace automatically terminates after** [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166065) in GitLab 17.6.
+{{< history >}}
+
+- Support for private projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124273) in GitLab 16.4.
+- **Git reference** and **Devfile location** [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392382) in GitLab 16.10.
+- **Time before automatic termination** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/392382) to **Workspace automatically terminates after** in GitLab 16.10.
+- **Variables** [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/463514) in GitLab 17.1.
+- **Workspace automatically terminates after** [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/166065) in GitLab 17.6.
+
+{{< /history >}}
+
+{{< alert type="warning" >}}
-WARNING:
Create a workspace only from trusted projects.
+{{< /alert >}}
+
Prerequisites:
- You must [set up workspace infrastructure](#set-up-workspace-infrastructure).
@@ -77,7 +91,11 @@ You also have access to the terminal and can install any necessary dependencies.
## Configure support for private container registries
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14664) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14664) in GitLab 17.6.
+
+{{< /history >}}
To use images from private container registries:
@@ -88,7 +106,11 @@ For more information, see [`image_pull_secrets`](settings.md#image_pull_secrets)
## Configure sudo access for a workspace
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+
+{{< /history >}}
Prerequisites:
@@ -143,7 +165,11 @@ To configure sudo access for a workspace with user namespaces:
## Build and run containers in a workspace
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+
+{{< /history >}}
Development environments often require building and running containers to manage and use dependencies
during runtime.
@@ -151,7 +177,11 @@ To build and run containers in a workspace, see [configure sudo access for a wor
## Connect to a workspace with SSH
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10478) in GitLab 16.3.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10478) in GitLab 16.3.
+
+{{< /history >}}
Prerequisites:
diff --git a/doc/user/workspace/create_image.md b/doc/user/workspace/create_image.md
index 28ba68e15eb9e977a7ef6c2d5dee31a75d77d666..a5ae6a7c9ead260adb4aaf4a0f99da30e49412ad 100644
--- a/doc/user/workspace/create_image.md
+++ b/doc/user/workspace/create_image.md
@@ -2,7 +2,7 @@
stage: Create
group: Remote Development
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
-description: "Create a custom workspace image to support any workspace you create in GitLab."
+description: Create a custom workspace image to support any workspace you create in GitLab.
title: 'Tutorial: Create a custom workspace image that supports arbitrary user IDs'
---
diff --git a/doc/user/workspace/gitlab_agent_configuration.md b/doc/user/workspace/gitlab_agent_configuration.md
index e6905a865dc3d071e004ef1c4fd1a71098d7a0f2..74117bdc26bc0ac8d970b893de5c7069377a6245 100644
--- a/doc/user/workspace/gitlab_agent_configuration.md
+++ b/doc/user/workspace/gitlab_agent_configuration.md
@@ -2,17 +2,24 @@
stage: Create
group: Remote Development
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
-description: "Configure the GitLab agent for workspaces."
+description: Configure the GitLab agent for workspaces.
title: GitLab agent configuration
---
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
+{{< details >}}
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default.
-> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0.
-> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed.
+- Tier: Premium, Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default.
+- [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0.
+- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed.
+
+{{< /history >}}
When you [set up workspace infrastructure](configuration.md#set-up-workspace-infrastructure), you must configure a GitLab agent to support workspaces. This guide assumes that a GitLab agent is already installed in the Kubernetes cluster.
@@ -25,7 +32,11 @@ Prerequisites:
## Agent authorization in a group for creating workspaces
-> - New authorization strategy [introduced](https://gitlab.com/groups/gitlab-org/-/epics/14025) in GitLab 17.2.
+{{< history >}}
+
+- New authorization strategy [introduced](https://gitlab.com/groups/gitlab-org/-/epics/14025) in GitLab 17.2.
+
+{{< /history >}}
With the new authorization strategy that replaces the [legacy authorization strategy](#legacy-agent-authorization-strategy), group owners and administrators can control which cluster agents can be used for hosting workspaces in a group.
diff --git a/doc/user/workspace/set_up_gitlab_agent.md b/doc/user/workspace/set_up_gitlab_agent.md
index 3bde243b18196ac748e268a9f76a1b7d31d25dec..a9aed9dc91f7ae447299b0794e09665a324874f1 100644
--- a/doc/user/workspace/set_up_gitlab_agent.md
+++ b/doc/user/workspace/set_up_gitlab_agent.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'set_up_gitlab_agent_and_proxies.md'
-remove_date: '2025-04-20'
+redirect_to: set_up_gitlab_agent_and_proxies.md
+remove_date: "2025-04-20"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/workspace/set_up_gitlab_agent_and_proxies.md b/doc/user/workspace/set_up_gitlab_agent_and_proxies.md
index bccee21ed55725e73f5ac5a89f80ebbd18052517..99ffd25b4fb33d9db3248f097e63609c60c4c9ee 100644
--- a/doc/user/workspace/set_up_gitlab_agent_and_proxies.md
+++ b/doc/user/workspace/set_up_gitlab_agent_and_proxies.md
@@ -2,7 +2,7 @@
stage: Create
group: Remote Development
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
-description: "Create a GitLab workspaces proxy to authenticate and authorize workspaces in your cluster."
+description: Create a GitLab workspaces proxy to authenticate and authorize workspaces in your cluster.
title: 'Tutorial: Set up GitLab agent and proxies'
---
@@ -12,11 +12,14 @@ This tutorial shows you how to:
- Set up the GitLab workspaces proxy to authenticate and authorize [workspaces](_index.md)
in your cluster.
-NOTE:
+{{< alert type="note" >}}
+
You must complete the setup steps in this tutorial before you can configure a GitLab agent to support workspaces.
After completing the tutorial, use [GitLab agent configuration](gitlab_agent_configuration.md) to configure
your GitLab agent.
+{{< /alert >}}
+
## Before you begin
Before starting this tutorial, you must have:
@@ -157,11 +160,14 @@ To generate certificates manually:
--work-dir ~/.certbot/work
```
-NOTE:
+{{< alert type="note" >}}
+
You must renew your certificates when they expire.
For example, Let's Encrypt certificates expire after three months.
To automatically renew certificates, see [`cert-manager`](https://cert-manager.io/docs/).
+{{< /alert >}}
+
## Register a GitLab OAuth application
To register an application on your GitLab instance:
diff --git a/doc/user/workspace/set_up_workspaces_proxy.md b/doc/user/workspace/set_up_workspaces_proxy.md
index 3bde243b18196ac748e268a9f76a1b7d31d25dec..a9aed9dc91f7ae447299b0794e09665a324874f1 100644
--- a/doc/user/workspace/set_up_workspaces_proxy.md
+++ b/doc/user/workspace/set_up_workspaces_proxy.md
@@ -1,6 +1,6 @@
---
-redirect_to: 'set_up_gitlab_agent_and_proxies.md'
-remove_date: '2025-04-20'
+redirect_to: set_up_gitlab_agent_and_proxies.md
+remove_date: "2025-04-20"
---
<!-- markdownlint-disable -->
diff --git a/doc/user/workspace/settings.md b/doc/user/workspace/settings.md
index 37d51f85d7767976261402ed34702b83e2f0e398..985b36a496ea558d5dc30b6fbd8bae428871dd53 100644
--- a/doc/user/workspace/settings.md
+++ b/doc/user/workspace/settings.md
@@ -2,7 +2,7 @@
stage: Create
group: Remote Development
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
-description: "Configure the GitLab agent for workspaces."
+description: Configure the GitLab agent for workspaces.
title: Workspace settings
---
@@ -33,10 +33,13 @@ your Kubernetes cluster. These settings control:
| [`max_active_hours_before_stop`](#max_active_hours_before_stop) | No | `36` | Maximum number of hours a workspace can be active before it is stopped. |
| [`max_stopped_hours_before_termination`](#max_stopped_hours_before_termination) | No | `744` | Maximum number of hours a workspace can be stopped before it is terminated. |
-NOTE:
+{{< alert type="note" >}}
+
If a setting has an invalid value, it's not possible to update any setting until you fix that value.
Updating any of these settings, except `enabled`, does not affect existing workspaces.
+{{< /alert >}}
+
## `enabled`
Use this setting to define whether:
@@ -116,7 +119,11 @@ The default value for `network_policy.enabled` is `true`.
### `network_policy.egress`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11629) in GitLab 16.7.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11629) in GitLab 16.7.
+
+{{< /history >}}
Use this setting to define a list of IP CIDR ranges to allow as egress destinations from a workspace.
@@ -150,7 +157,11 @@ In this example, traffic from the workspace is allowed if:
## `default_resources_per_workspace_container`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11625) in GitLab 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11625) in GitLab 16.8.
+
+{{< /history >}}
Use this setting to define the default [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits)
for CPU and memory per workspace container.
@@ -174,7 +185,11 @@ remote_development:
## `max_resources_per_workspace`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11625) in GitLab 16.8.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11625) in GitLab 16.8.
+
+{{< /history >}}
Use this setting to define the maximum [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits)
for CPU and memory per workspace.
@@ -205,7 +220,11 @@ to perform bootstrapping operations such as cloning the project repository.
## `workspaces_quota`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11586) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11586) in GitLab 16.9.
+
+{{< /history >}}
Use this setting to set the maximum number of workspaces for the GitLab agent.
@@ -229,7 +248,11 @@ remote_development:
## `workspaces_per_user_quota`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11586) in GitLab 16.9.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11586) in GitLab 16.9.
+
+{{< /history >}}
Use this setting to set the maximum number of workspaces per user.
@@ -253,7 +276,11 @@ remote_development:
## `use_kubernetes_user_namespaces`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+
+{{< /history >}}
Use this setting to specify whether to use the user namespaces feature in Kubernetes.
@@ -274,7 +301,11 @@ For more information about `use_kubernetes_user_namespaces`, see
## `default_runtime_class`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+
+{{< /history >}}
Use this setting to select the container runtime configuration used to run the containers in the workspace.
@@ -299,7 +330,11 @@ For more information about `default_runtime_class`, see
## `allow_privilege_escalation`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+
+{{< /history >}}
Use this setting to control whether a process can gain more privileges than its parent process.
@@ -324,7 +359,11 @@ For more information about `allow_privilege_escalation`, see
## `image_pull_secrets`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14664) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14664) in GitLab 17.6.
+
+{{< /history >}}
Use this setting to specify existing Kubernetes secrets of the type `kubernetes.io/dockercfg`
or `kubernetes.io/dockerconfigjson` required by workspaces to pull private images.
@@ -352,7 +391,11 @@ in all the namespaces of the workspaces where the secret is referenced.
## `annotations`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+
+{{< /history >}}
Use this setting to attach arbitrary non-identifying metadata to the Kubernetes objects.
@@ -381,7 +424,11 @@ For more information about `annotations`, see
## `labels`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/13983) in GitLab 17.4.
+
+{{< /history >}}
Use this setting to attach arbitrary identifying metadata to the Kubernetes objects.
@@ -414,7 +461,11 @@ For more information about `labels`, see
## `max_active_hours_before_stop`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14910) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14910) in GitLab 17.6.
+
+{{< /history >}}
Use this setting to automatically stop the agent's workspaces after the specified number of hours
have passed, because the workspace last transitioned to an active state.
@@ -446,7 +497,11 @@ This means that the workspace might be active for up to one hour longer than the
## `max_stopped_hours_before_termination`
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14910) in GitLab 17.6.
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14910) in GitLab 17.6.
+
+{{< /history >}}
Use this setting to automatically terminate the agent's workspaces after they have been in the stopped
state for the specified number of hours.
diff --git a/doc/user/workspace/workspaces_troubleshooting.md b/doc/user/workspace/workspaces_troubleshooting.md
index 5fe2bb5a7b4939575f7f05316fa3ca1cde68bda7..ae3241b24084ebfa589952f95ad3dc9114979d33 100644
--- a/doc/user/workspace/workspaces_troubleshooting.md
+++ b/doc/user/workspace/workspaces_troubleshooting.md
@@ -2,7 +2,7 @@
stage: Create
group: Remote Development
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
-description: "Create a GitLab workspaces proxy to authenticate and authorize workspaces in your cluster."
+description: Create a GitLab workspaces proxy to authenticate and authorize workspaces in your cluster.
title: Troubleshooting workspaces
---