root
/
gitlab-ce
mirror of https://gitlab.com/free-releases/gitlab-ce.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

Add latest changes from gitlab-org/gitlab@master

This commit is contained in:
GitLab Bot 2025-02-17 03:18:02 +00:00
parent 1b05f494ea
commit 874101a82f
2124 changed files with 36532 additions and 15713 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
GITLAB_KAS_VERSION
View File

@ -1 +1 @@
737917b4ec3db719fbed640d2c9cbd9be6e38b05
cc01f56459190de381f72938ed458d37e9708110

14
data/deprecations/templates/_deprecation_template.md.erb
View File

@ -3,10 +3,9 @@ stage: none
group: none
info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines"
toc: false
title: Deprecations and removals by version
---
# Deprecations and removals by version
The following GitLab features are deprecated and no longer recommended for use.
- Each deprecated feature will be removed in a future release.
@ -20,7 +19,7 @@ For advanced searching and filtering of this deprecation information, try
[REST API deprecations](https://docs.gitlab.com/ee/api/rest/deprecations.html) are documented separately.
**{rss}** **To be notified of upcoming breaking changes**,
{{< icon name="rss" >}} **To be notified of upcoming breaking changes**,
add this URL to your RSS feed reader: `https://about.gitlab.com/breaking-changes.xml`
<!-- vale off -->
@ -47,8 +46,6 @@ For deprecation reviewers (Technical Writers only):
https://handbook.gitlab.com/handbook/marketing/blog/release-posts/#update-the-deprecations-doc
-->
{::options parse_block_html="true" /}
<% if milestones.any? -%><div class="js-deprecation-filters"></div><%- end -%>
<%- milestones.each do |milestone| %>
<div class="milestone-wrapper" data-milestone="<%= milestone %>">
@ -81,9 +78,4 @@ For deprecation reviewers (Technical Writers only):
</div>
<%- end -%>
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" />}}

1
db/docs/batched_background_migrations/backfill_issues_dates_with_work_item_dates_sources.yml
View File

@ -5,3 +5,4 @@ feature_category: product_planning
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/157993
milestone: '17.2'
queued_migration_version: 20240702212015
finalized_by: '20250212025212'

21
db/post_migrate/20250212025212_finalize_hk_backfill_issues_dates_with_work_item_dates_sources.rb Normal file
View File

@ -0,0 +1,21 @@
# frozen_string_literal: true
class FinalizeHkBackfillIssuesDatesWithWorkItemDatesSources < Gitlab::Database::Migration[2.2]
milestone '17.10'
disable_ddl_transaction!
restrict_gitlab_migration gitlab_schema: :gitlab_main
def up
ensure_batched_background_migration_is_finished(
job_class_name: 'BackfillIssuesDatesWithWorkItemDatesSources',
table_name: :work_item_dates_sources,
column_name: :issue_id,
job_arguments: [],
finalize: true
)
end
def down; end
end

1
db/schema_migrations/20250212025212 Normal file
View File

@ -0,0 +1 @@
5aa8e630d9732985868486568a0e8fb7d3d6d80c6a952110de16b6de3da73f31

4
doc/administration/_index.md
View File

@ -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
---

99
doc/administration/admin_area.md
View File

@ -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 >}}

11
doc/administration/administer_users.md
View File

@ -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.

17
doc/administration/analytics.md
View File

@ -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.

16
doc/administration/analytics/dev_ops_reports.md
View File

@ -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" >}}).

9
doc/administration/analytics/usage_trends.md
View File

@ -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.

36
doc/administration/appearance.md
View File

@ -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).

21
doc/administration/application_settings_cache.md
View File

@ -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 >}}

33
doc/administration/audit_event_reports.md
View File

@ -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 >}}
> - Entity type `Gitlab::Audit::InstanceScope` for instance audit events [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418185) in GitLab 16.2.
- Tier: Premium, Ultimate
- Offering: GitLab Self-Managed
{{< /details >}}
{{< 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:

70
doc/administration/audit_event_streaming/_index.md
View File

@ -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
{{< details >}}
> - [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.
- 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.

20
doc/administration/auditor_users.md
View File

@ -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.

16
doc/administration/auth/_index.md
View File

@ -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.

9
doc/administration/auth/atlassian.md
View File

@ -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.

9
doc/administration/auth/cognito.md
View File

@ -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.

9
doc/administration/auth/crowd.md
View File

@ -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.

21
doc/administration/auth/jwt.md
View File

@ -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:

211
doc/administration/auth/ldap/_index.md
View File

@ -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

16
doc/administration/auth/ldap/google_secure_ldap.md
View File

@ -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 >}}
![Google Workspace window with access permissions for adding LDAP client.](img/google_secure_ldap_add_step_2_v11_9.png)
1. Download the generated certificate. This is required for GitLab to

76
doc/administration/auth/ldap/ldap-troubleshooting.md
View File

@ -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.

190
doc/administration/auth/ldap/ldap_synchronization.md
View File

@ -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 >}}
:::TabTitle Linux package (Omnibus)
{{< tabs >}}
{{< 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

161
doc/administration/auth/oidc.md
View File

@ -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 >}}
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209898) in GitLab 15.10.
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
{{< /details >}}
{{< 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 >}}
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377654) in GitLab 17.8.
- Tier: Free, Premium, Ultimate
- Offering: GitLab Self-Managed
{{< /details >}}
{{< 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

61
doc/administration/auth/smartcard.md
View File

@ -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.

9
doc/administration/auth/test_oidc_oauth.md
View File

@ -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:

14
doc/administration/backup_restore/_index.md
View File

@ -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

5
doc/administration/backup_restore/backup_archive_process.md
View File

@ -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

30
doc/administration/backup_restore/backup_cli.md
View File

@ -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:

362
doc/administration/backup_restore/backup_gitlab.md
View File

@ -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 >}}
:::TabTitle Linux package (Omnibus)
{{< tabs >}}
{{< 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 >}}
:::TabTitle Linux package (Omnibus)
{{< tabs >}}
{{< 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:

81
doc/administration/backup_restore/backup_large_reference_architectures.md
View File

@ -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.

5
doc/administration/backup_restore/migrate_to_new_server.md
View File

@ -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

46
doc/administration/backup_restore/restore_gitlab.md
View File

@ -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`):

30
doc/administration/backup_restore/troubleshooting_backup_gitlab.md
View File

@ -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

9
doc/administration/broadcast_messages.md
View File

@ -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:

26
doc/administration/cells.md
View File

@ -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

18
doc/administration/cicd/_index.md
View File

@ -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.

17
doc/administration/cicd/compute_minutes.md
View File

@ -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 >}}
> - [Renamed](https://gitlab.com/groups/gitlab-com/-/epics/2150) from "CI/CD minutes" to "compute quota" or "compute minutes" in GitLab 16.1.
- 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.
{{< /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

15
doc/administration/cicd/external_pipeline_validation.md
View File

@ -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
{

119
doc/administration/cicd/job_artifacts.md
View File

@ -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

30
doc/administration/cicd/job_artifacts_troubleshooting.md
View File

@ -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

52
doc/administration/cicd/job_logs.md
View File

@ -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 >}}
:::TabTitle Linux package (Omnibus)
{{< tabs >}}
{{< 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

26
doc/administration/cicd/maintenance.md
View File

@ -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 -->
<!--- end_remove -->

60
doc/administration/cicd/secure_files.md
View File

@ -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:

50
doc/administration/clusters/kas.md
View File

@ -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 >}}
> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/12180) in GitLab 17.4.
- Tier: Ultimate
- Offering: GitLab Self-Managed
{{< /details >}}
{{< history >}}
- [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.

55
doc/administration/compliance.md
View File

@ -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. |

11
doc/administration/configure.md
View File

@ -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.

45
doc/administration/consul.md
View File

@ -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

9
doc/administration/credentials_inventory.md
View File

@ -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

27
doc/administration/custom_html_header_tags.md
View File

@ -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 >}}

11
doc/administration/custom_project_templates.md
View File

@ -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

11
doc/administration/dedicated/_index.md
View File

@ -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.

11
doc/administration/dedicated/architecture.md
View File

@ -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.

26
doc/administration/dedicated/configure_instance/_index.md
View File

@ -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 >}}

22
doc/administration/dedicated/configure_instance/network_security.md
View File

@ -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

21
doc/administration/dedicated/configure_instance/saml.md
View File

@ -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.

11
doc/administration/dedicated/configure_instance/users_notifications.md
View File

@ -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

33
doc/administration/dedicated/create_instance.md
View File

@ -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 >}}

33
doc/administration/dedicated/hosted_runners.md
View File

@ -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.

26
doc/administration/dedicated/maintenance.md
View File

@ -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,

9
doc/administration/dedicated/monitor.md
View File

@ -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/).

16
doc/administration/dedicated/tenant_overview.md
View File

@ -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.

16
doc/administration/diff_limits.md
View File

@ -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:

19
doc/administration/docs_self_host.md
View File

@ -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.

15
doc/administration/duo_add_on_seat_management_with_ldap.md
View File

@ -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.

11
doc/administration/email_from_gitlab.md
View File

@ -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**.

11
doc/administration/encrypted_configuration.md
View File

@ -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:

9
doc/administration/environment_variables.md
View File

@ -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.

14
doc/administration/external_users.md
View File

@ -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).

16
doc/administration/feature_flags.md
View File

@ -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

16
doc/administration/file_hooks.md
View File

@ -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.

32
doc/administration/geo/_index.md
View File

@ -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

43
doc/administration/geo/disaster_recovery/_index.md
View File

@ -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:

9
doc/administration/geo/disaster_recovery/background_verification.md
View File

@ -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

35
doc/administration/geo/disaster_recovery/bring_primary_back.md
View File

@ -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:

9
doc/administration/geo/disaster_recovery/failover_troubleshooting.md
View File

@ -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

9
doc/administration/geo/disaster_recovery/planned_failover.md
View File

@ -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

47
doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md
View File

@ -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:

47
doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md
View File

@ -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:

14
doc/administration/geo/glossary.md
View File

@ -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)

26
doc/administration/geo/replication/configuration.md
View File

@ -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:

22
doc/administration/geo/replication/container_registry.md
View File

@ -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:

28
doc/administration/geo/replication/datatypes.md
View File

@ -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 | |

9
doc/administration/geo/replication/disable_geo.md
View File

@ -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

9
doc/administration/geo/replication/faq.md
View File

@ -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?

9
doc/administration/geo/replication/geo_validation_tests.md
View File

@ -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.

14
doc/administration/geo/replication/location_aware_git_url.md
View File

@ -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.

48
doc/administration/geo/replication/multiple_servers.md
View File

@ -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.

15
doc/administration/geo/replication/object_storage.md
View File

@ -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.

14
doc/administration/geo/replication/pause_resume_replication.md
View File

@ -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.

23
doc/administration/geo/replication/remove_geo_site.md
View File

@ -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`.

9
doc/administration/geo/replication/security_review.md
View File

@ -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

14
doc/administration/geo/replication/selective_synchronization.md
View File

@ -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.

19
doc/administration/geo/replication/single_sign_on.md
View File

@ -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).

9
doc/administration/geo/replication/troubleshooting/_index.md
View File

@ -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:

9
doc/administration/geo/replication/troubleshooting/client_http.md
View File

@ -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

27
doc/administration/geo/replication/troubleshooting/common.md
View File

@ -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 >}}

4
doc/administration/geo/replication/troubleshooting/failover.md
View File

@ -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 -->

Some files were not shown because too many files have changed in this diff Show More