diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 13:18:24 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 13:18:24 +0000 |
| commit | 0653e08efd039a5905f3fa4f6e9cef9f5d2f799c (patch) | |
| tree | 4dcc884cf6d81db44adae4aa99f8ec1233a41f55 /doc/user | |
| parent | 744144d28e3e7fddc117924fef88de5d9674fe4c (diff) | |
| download | gitlab-ce-47839f859fe0a95188a31acdfbc5c09d2b983af8.tar.gz | |
Add latest changes from gitlab-org/gitlab@14-3-stable-eev14.3.0-rc42
Diffstat (limited to 'doc/user')
238 files changed, 3822 insertions, 2531 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index f07ccc11c60..7ddddfc5e53 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -14,13 +14,13 @@ from planning to monitoring. To see DevOps Report: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Analytics > DevOps Report**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Analytics > DevOps Report**. ## DevOps Score NOTE: -To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). +To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). This is because DevOps Score is a comparative tool, so your score data must be centrally processed by GitLab Inc. first. You can use the DevOps score to compare your DevOps status to other organizations. @@ -45,6 +45,7 @@ feature is available. > - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. > - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. > - Multi-select [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. +> - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. DevOps Adoption shows you which groups in your organization are using the most essential features of GitLab: diff --git a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png Binary files differindex d4b3436f3ee..666e03f1d9d 100644 --- a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png +++ b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 465b26d516c..dd1efc913fa 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w Administrators have access to instance-wide analytics: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Analytics**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Analytics**. There are several kinds of statistics: diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index 9c09b62f8af..06995069215 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -19,7 +19,7 @@ Usage Trends gives you an overview of how much data your instance contains, and To see Usage Trends: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Analytics > Usage Trends**. ## Total counts diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index d7f0b7e3854..0ffa8289d37 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -11,8 +11,8 @@ disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page. There are several options for customizing the appearance of a self-managed instance of GitLab. To access these settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Appearance**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Appearance**. ## Navigation bar diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 93e6aa9bb16..987d7444ae0 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -54,7 +54,7 @@ To display messages to users on your GitLab instance, add a broadcast message. To add a broadcast message: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Messages**. 1. Add the text for the message to the **Message** field. You can style a message's content using Markdown, emoji, and the `a` and `br` HTML tags. The `br` tag inserts a line break. The `a` HTML tag accepts `class` and `style` attributes with the following CSS properties: @@ -84,7 +84,7 @@ If you need to make changes to a broadcast message, you can edit it. To edit a broadcast message: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Messages**. 1. From the list of broadcast messages, select the edit button for the message. 1. After making the required changes, select **Update broadcast message**. @@ -98,7 +98,7 @@ You can delete a broadcast message while it's active. To delete a broadcast message: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Messages**. 1. From the list of broadcast messages, select the delete button for the message. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 8c5ae2dfb47..d79508e5b68 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -25,7 +25,7 @@ and [delete](#delete-a-users-ssh-key) and see: To access the Credentials inventory: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Credentials**. The following is an example of the Credentials inventory page: diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index 4be1ace10aa..b50748ca97e 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -33,8 +33,8 @@ set values are presented as **Too large** are cannot be expanded in the UI. To configure these values: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for the diff limit. 1. Select **Save changes**. diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index 861d3644ab3..a2354e68d72 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -12,7 +12,7 @@ You can configure various settings for GitLab Geo sites. For more information, s On either the primary or secondary site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. ## Common settings @@ -65,7 +65,7 @@ which is used by users. Internal URL does not need to be a private address. Internal URL defaults to external URL, but you can also customize it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Edit** on the site you want to customize. 1. Edit the internal URL. diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 35afb9f376b..a5c3a2a7aeb 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -12,7 +12,7 @@ self-managed instances. If you are an Admin user, you can access the Admin Area by visiting `/admin` on your self-managed instance. You can also access it through the UI: -- GitLab versions 14.0 and later: on the top bar, select **Menu >** **{admin}** **Admin**. +- GitLab versions 14.0 and later: on the top bar, select **Menu > Admin**. - GitLab versions 13.12 and earlier: on the top bar, select the Admin Area icon (**{admin}**). NOTE: @@ -47,7 +47,7 @@ The Dashboard provides statistics and system information about the GitLab instan To access the Dashboard, either: -- On the top bar, select **Menu >** **{admin}** **Admin**. +- On the top bar, select **Menu > Admin**. - Visit `/admin` on your self-managed instance. The Dashboard is the default view of the Admin Area, and is made up of the following sections: @@ -71,8 +71,8 @@ You can administer all projects in the GitLab instance from the Admin Area's Pro To access the Projects page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Projects**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Projects**. 1. Select the **All**, **Private**, **Internal**, or **Public** tab to list only projects of that criteria. @@ -111,8 +111,8 @@ You can combine the filter options. For example, to list only public projects wi You can administer all users in the GitLab instance from the Admin Area's Users page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Users**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. To list users matching a specific criteria, click on one of the following tabs on the **Users** page: @@ -156,8 +156,8 @@ This allows the administrator to "see what the user sees," and take actions on b You can impersonate a user in the following ways: - Through the UI: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. - 1. In the left sidebar, select **Overview > Users**. + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Impersonate**. - With the API, using [impersonation tokens](../../api/index.md#impersonation-tokens). @@ -199,6 +199,18 @@ The following totals are also included: GitLab billing is based on the number of [**Billable users**](../../subscriptions/self_managed/index.md#billable-users). +#### Add email to user + +You must be an administrator to manually add emails to users: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users** (`/admin/users`). +1. Locate the user and select them. +1. Select **Edit**. +1. In **Email**, enter the new email address. This adds the new email address to the + user and sets the previous email address to be a secondary. +1. Select **Save changes**. + ### User cohorts The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and their activities over time. @@ -209,8 +221,8 @@ You can administer all groups in the GitLab instance from the Admin Area's Group To access the Groups page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Groups**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Groups**. For each group, the page displays their name, description, size, number of projects in the group, number of members, and whether the group is private, internal, or public. To edit a group, click @@ -231,8 +243,8 @@ You can administer all jobs in the GitLab instance from the Admin Area's Jobs pa To access the Jobs page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Jobs**. All jobs are listed, in descending order of job ID. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Jobs**. All jobs are listed, in descending order of job ID. 1. Click the **All** tab to list all jobs. Click the **Pending**, **Running**, or **Finished** tab to list only jobs of that status. @@ -257,8 +269,8 @@ You can administer all runners in the GitLab instance from the Admin Area's **Ru To access the **Runners** page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Runners**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Runners**. The **Runners** page features: @@ -307,8 +319,8 @@ page. For more details, see [Gitaly](../../administration/gitaly/index.md). To access the **Gitaly Servers** page: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Gitaly Servers**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Gitaly Servers**. For each Gitaly server, the following details are listed: diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 0431b0d1628..4e97cb8e49c 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -116,7 +116,7 @@ before this occurs. To remove a license file from a self-managed instance: 1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription** +1. From the left sidebar, select **Subscription**. 1. Select **Remove license**. These steps may need to be repeated to completely remove all licenses, including those applied in the past. @@ -124,8 +124,10 @@ These steps may need to be repeated to completely remove all licenses, including ## License history You can upload and view more than one license, but only the latest license in the current date -range is used as the active license. When you upload a future-dated license, it -doesn't take effect until its applicable date. +range is used as the active license. + +When you upload a future-dated license, it doesn't take effect until its applicable date. +You can view all of your active subscriptions in the **Subscription history** table. NOTE: In GitLab 13.6 and earlier, a notification banner about an expiring license may continue to be displayed even after a new license has been uploaded. @@ -165,7 +167,7 @@ your license. However, if you have 111, you must purchase more users before you ### There is a connectivity issue -In GitLab 14.1 and later, to activate your subscription, your GitLab instance must be connected to the internet. +In GitLab 14.1 and later, to activate your subscription, your GitLab instance must be connected to the internet. If you have an offline or airgapped environment, you can [upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 4f6419cdeb7..ffa08dee10d 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -15,8 +15,8 @@ project level. To enable merge request approval rules for an instance: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request (MR) approvals**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request (MR) approvals**. 1. Set the required rule. 1. Click **Save changes**. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 8211167895c..2655d927b87 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -13,11 +13,12 @@ users. ## Users pending approval A user in _pending approval_ state requires action by an administrator. A user sign up can be in a -pending approval state because an administrator has enabled either, or both, of the following -options: +pending approval state because an administrator has enabled any of the following options: - [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting. - [User cap](settings/sign_up_restrictions.md#user-cap). +- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#initial-omniauth-configuration) +- [Block auto-created users (LDAP)](../../administration/auth/ldap/index.md#basic-configuration-settings) When a user registers for an account while this setting is enabled: @@ -39,7 +40,7 @@ sign in. To view user sign ups pending approval: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. @@ -49,7 +50,7 @@ A user sign up pending approval can be approved or rejected from the Admin Area. To approve or reject a user sign up: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. 1. (Optional) Select a user. @@ -74,7 +75,7 @@ administrators can choose to block the user. Users can be blocked [via an abuse report](review_abuse_reports.md#blocking-users), or directly from the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. (Optional) Select a user. 1. Select the **{settings}** **User administration** dropdown. @@ -97,7 +98,7 @@ Users can also be blocked using the [GitLab API](../../api/users.md#block-user). A blocked user can be unblocked from the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select on the **Blocked** tab. 1. (Optional) Select a user. @@ -136,15 +137,19 @@ A deactivated user: Personal projects, and group and user history of the deactivated user are left intact. +NOTE: +Users are notified about account deactivation if +[user deactivation emails](settings/email.md#user-deactivation-emails) are enabled. + A user can be deactivated from the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. (Optional) Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Deactivate**. -For the deactivation option to be visible to an admin, the user: +For the deactivation option to be visible to an administrator, the user: - Must be currently active. - Must not have signed in, or have any activity, in the last 90 days. @@ -159,7 +164,7 @@ Users can also be deactivated using the [GitLab API](../../api/users.md#deactiva Administrators can enable automatic deactivation of users who have not signed in, or have no activity in the last 90 days. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Under **Dormant users**, check **Deactivate dormant users after 90 days of inactivity**. @@ -177,7 +182,7 @@ A deactivated user can be activated from the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Deactivated** tab. 1. (Optional) Select a user. @@ -193,9 +198,9 @@ Users can also be activated using the [GitLab API](../../api/users.md#activate-u ## Ban and unban users -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.2. -GitLab administrators can ban and unban users. Banned users are blocked, and their issues are hidden. +GitLab administrators can ban and unban users. Banned users are blocked, and their issues are hidden. The banned user's comments are still displayed. Hiding a banned user's comments is [tracked in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327356). ### Ban a user @@ -204,7 +209,7 @@ To block a user and hide their contributions, administrators can ban the user. Users can be banned using the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. (Optional) Select a user. 1. Select the **{settings}** **User administration** dropdown. @@ -216,7 +221,7 @@ The banned user does not consume a [seat](../../subscriptions/self_managed/index A banned user can be unbanned using the Admin Area. To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Banned** tab. 1. (Optional) Select a user. diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index a3e46ea6225..c5ffb032afd 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -146,8 +146,8 @@ Access token has been deprecated in GitLab 9.4 in favor of [IP whitelist](#ip-wh An access token needs to be provided while accessing the probe endpoints. You can find the current accepted token in the user interface: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Monitoring > Health Check**. (`admin/health_check`) +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Monitoring > Health Check**. (`admin/health_check`)  diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 7816d0648b2..6494934c34d 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -16,7 +16,7 @@ reports in the Admin Area. To receive notifications of new abuse reports by email, follow these steps: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Reporting**. 1. Expand the **Abuse reports** section. 1. Provide an email address. @@ -33,7 +33,7 @@ documentation](../report_abuse.md). To access abuse reports: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Abuse Reports**. There are 3 ways to resolve an abuse report, with a button for each method: diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 71e05f44ef0..3549aa5323b 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -11,8 +11,8 @@ type: reference You can change the default maximum number of projects that users can create in their personal namespace: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease that **Default projects limit** value. If you set **Default projects limit** to 0, users are not allowed to create projects @@ -22,8 +22,8 @@ in their users personal namespace. However, projects can still be created in a g You can change the maximum file size for attachments in comments and replies in GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum attachment size (MB)**. NOTE: @@ -35,8 +35,8 @@ details. You can change the maximum push size for your repository: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum push size (MB)**. NOTE: @@ -50,8 +50,8 @@ Use [Git LFS](../../../topics/git/lfs/index.md) to add large files to a reposito You can change the maximum file size for imports in GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum import size (MB)**. NOTE: @@ -70,8 +70,8 @@ A prefix can help you identify PATs visually, as well as with automation tools. Only a GitLab administrator can set the prefix, which is a global setting applied to any PAT generated in the system by any user: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Personal Access Token prefix** field. 1. Click **Save changes**. @@ -113,8 +113,8 @@ These settings can be found in: 1. Fill in the **Repository size limit (MB)** field in the **Naming, visibility** section. 1. Click **Save changes**. - GitLab global settings: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. - 1. In the left sidebar, select **Settings > General**. + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Size limit per repository (MB)** field. 1. Click **Save changes**. @@ -154,19 +154,19 @@ nginx['client_max_body_size'] = "200m" > - It's deployed behind a feature flag, disabled by default. > - It's disabled on GitLab.com. > - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-two-factor-authentication-2fa-for-git-operations). +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-2fa-for-git-operations). NOTE: This feature is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. To use it in GitLab -self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-two-factor-authentication-2fa-for-git-operations). +self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-2fa-for-git-operations). GitLab administrators can choose to customize the session duration (in minutes) for Git operations when 2FA is enabled. The default is 15 and this can be set to a value between 1 and 10080. To set a limit on how long these sessions are valid: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. 1. Click **Save changes**. @@ -190,8 +190,8 @@ there are no restrictions. To set a lifetime on how long personal access tokens are valid: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. @@ -213,8 +213,8 @@ By default, expired SSH keys **are not usable**. To allow the use of expired SSH keys: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Uncheck the **Enforce SSH key expiration** checkbox. @@ -229,8 +229,8 @@ By default, expired personal access tokens (PATs) **are not usable**. To allow the use of expired PATs: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Uncheck the **Enforce personal access token expiration** checkbox. @@ -242,8 +242,8 @@ To maintain integrity of user details in [Audit Events](../../../administration/ To do this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Select the **Prevent users from changing their profile name** checkbox. NOTE: diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 3b56318e711..178b117d06c 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -15,7 +15,7 @@ job artifacts. To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) for all projects: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Check (or uncheck to disable) the box that says **Default to Auto DevOps pipeline for all projects**. 1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/requirements.md#auto-devops-base-domain) @@ -33,7 +33,7 @@ If you want to disable it for a specific project, you can do so in To display details about the instance's shared runners in all projects' runner settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Enter your shared runner details in the **Shared runner details** field. @@ -64,7 +64,7 @@ To change it at the: - Instance level: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Change the value of maximum artifacts size (in MB). 1. Click **Save changes** for the changes to take effect. @@ -91,7 +91,7 @@ can be set in the Admin Area of your GitLab instance. The syntax of duration is described in [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) and the default value is `30 days`. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Change the value of default expiration time. 1. Click **Save changes** for the changes to take effect. @@ -122,7 +122,7 @@ If disabled at the instance level, you cannot enable this per-project. To disable the setting: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Clear the **Keep the latest artifacts for all jobs in the latest successful pipelines** checkbox. @@ -148,7 +148,7 @@ On GitLab.com, the quota is calculated based on your To change the pipelines minutes quota: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. In the **Pipeline minutes quota** box, enter the maximum number of minutes. @@ -181,7 +181,7 @@ but persisting the traces and artifacts for auditing purposes. To set the duration for which the jobs are considered as old and expired: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. Set the value of **Archive jobs**. @@ -198,7 +198,7 @@ As of June 22, 2020 the [value is set](../../gitlab_com/index.md#gitlab-cicd) to To set all new [CI/CD variables](../../../ci/variables/index.md) as [protected](../../../ci/variables/index.md#protect-a-cicd-variable) by default: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Select **Protect CI/CD variables by default**. @@ -209,7 +209,7 @@ To set all new [CI/CD variables](../../../ci/variables/index.md) as The default CI/CD configuration file and path for new projects can be set in the Admin Area of your GitLab instance (`.gitlab-ci.yml` if not set): -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Input the new file and path in the **Default CI/CD configuration file** field. 1. Hit **Save changes** for the changes to take effect. @@ -245,7 +245,7 @@ in the pipeline editor. To select a CI/CD template for the required pipeline configuration: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Required pipeline configuration** section. 1. Select a CI/CD template from the dropdown. @@ -259,7 +259,7 @@ GitLab administrators can disable the forwarding of npm requests to [npmjs.com]( To disable it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward npm package requests to the npm Registry if the packages are not found in the GitLab Package Registry**. @@ -271,7 +271,7 @@ GitLab administrators can disable the forwarding of PyPI requests to [pypi.org]( To disable it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward PyPI package requests to the PyPI Registry if the packages are not found in the GitLab Package Registry**. @@ -283,7 +283,7 @@ GitLab administrators can adjust the maximum allowed file size for each package To set the maximum file size: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Find the package type you would like to adjust. @@ -304,7 +304,7 @@ By default, all members of a project and group are able to register runners. To change this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. Go to **Settings > CI/CD**. 1. Expand the **Runner registration** section. 1. Select the desired options. diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 236b75797a2..c04a9a12912 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -21,7 +21,7 @@ address in the body of the email instead. To include the author's email address in the email body: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand **Email**. 1. Select the **Include author name in email notification email body** checkbox. @@ -33,7 +33,7 @@ GitLab can send email in multipart format (HTML and plain text) or plain text on To enable multipart email: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand **Email**. 1. Select **Enable multipart email**. @@ -48,7 +48,7 @@ This configuration option sets the email hostname for [private commit emails](.. To change the hostname used in private commit emails: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand **Email**. 1. Enter the desired hostname in the **Custom hostname (for private commit emails)** field. @@ -66,12 +66,24 @@ can be used for legal, auditing, or compliance reasons, for example. To add additional text to emails: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand **Email**. 1. Enter your text in the **Additional text** field. 1. Select **Save changes**. +## User deactivation emails **(FREE SELF)** + +GitLab sends email notifications to users when their account has been deactivated. + +To disable these notifications: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. Expand **Email**. +1. Clear the **Enable user deactivation emails** checkbox. +1. Select **Save changes**. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 205dd77c1bf..985f3c133d5 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -41,8 +41,8 @@ the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/logs The external authorization service can be enabled by an administrator: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**: +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**:  The available required properties are: diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index 0e9d4e5d0c1..17c390aef0e 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -22,8 +22,8 @@ Permissions-Policy: interest-cohort=() To enable it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand **Federated Learning of Cohorts**. 1. Check the box. 1. Click **Save changes**. diff --git a/doc/user/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md new file mode 100644 index 00000000000..8a0754374e2 --- /dev/null +++ b/doc/user/admin_area/settings/git_lfs_rate_limits.md @@ -0,0 +1,35 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference +--- + +# Git LFS Rate Limits **(FREE SELF)** + +[Git LFS (Large File Storage)](../../../topics/git/lfs/index.md) is a Git extension +for handling large files. If you use Git LFS in your repository, common Git operations +can generate many Git LFS requests. You can enforce +[general user and IP rate limits](user_and_ip_rate_limits.md), but you can also +override the general setting to enforce additional limits on Git LFS requests. This +override can improve the security and durability of your web application. Aside from +precedence, this configuration provides the same features as the general user and IP +rate limits. + +## Configure Git LFS rate limits + +Git LFS rate limits are disabled by default. If enabled and configured, these limits +supersede the [general user and IP rate limits](user_and_ip_rate_limits.md): + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Network**. +1. Expand **Git LFS Rate Limits**. +1. Select **Enable authenticated Git LFS request rate limit**. +1. Enter a value for **Max authenticated Git LFS requests per period per user**. +1. Enter a value for **Authenticated Git LFS rate limit period in seconds**. +1. Select **Save changes**. + +## Resources + +- [Rate limiting](../../../security/rate_limits.md) +- [User and IP rate limits](user_and_ip_rate_limits.md) diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index 04887906c91..1d4f45d1f04 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -12,7 +12,7 @@ configured to make sure that long-running Gitaly calls don't needlessly take up To access Gitaly timeout settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand the **Gitaly timeouts** section. diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index 01516430f4f..cf08b9b71db 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -16,7 +16,7 @@ the GitLab sign-in page. You can add a help message, which is shown at the top of the GitLab `/help` page (for example, <https://gitlab.com/help>): -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the Help page**, enter the information you want to display on `/help`. @@ -34,7 +34,7 @@ is restricted, `/help` is visible only to signed-in users. You can add a help message, which is shown on the GitLab sign-in page. The message appears in a new section titled **Need Help?**, located below the sign-in page message: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the sign-in page**, enter the information you want to @@ -47,7 +47,7 @@ You can now see the message on the sign-in page. GitLab marketing-related entries are occasionally shown on the Help page. To hide these entries: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. Select the **Hide marketing-related entries from the Help page** checkbox. @@ -60,7 +60,7 @@ You can specify a custom URL to which users are directed when they: - Select **Support** from the Help dropdown. - Select **See our website for help** on the Help page. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Support page URL** field, enter the URL. @@ -68,8 +68,7 @@ You can specify a custom URL to which users are directed when they: ## Redirect `/help` pages -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43157) in GitLab 13.5. -> - Enabled on GitLab.com and is ready for production use. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43157) in GitLab 13.5. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to @@ -85,8 +84,8 @@ You can redirect these `/help` links to either: - The more navigable and searchable version published at [`docs.gitlab.com`](https://docs.gitlab.com). - A destination that meets [necessary requirements](#destination-requirements). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Preferences**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Documentation pages URL** field, enter the URL. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/img/domain_denylist_v14_1.png b/doc/user/admin_area/settings/img/domain_denylist_v14_1.png Binary files differindex c988afd75f6..e27997fc2c2 100644 --- a/doc/user/admin_area/settings/img/domain_denylist_v14_1.png +++ b/doc/user/admin_area/settings/img/domain_denylist_v14_1.png diff --git a/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png b/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png Binary files differdeleted file mode 100644 index 76015ce0ee3..00000000000 --- a/doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png Binary files differindex 63f4d5a4a1a..1a0a7548a91 100644 --- a/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png +++ b/doc/user/admin_area/settings/img/rate_limit_on_issues_creation_v14_2.png diff --git a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png Binary files differdeleted file mode 100644 index 5056e8354a9..00000000000 --- a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png +++ /dev/null diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md index 12235bdb5ef..7d5a928eedf 100644 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ b/doc/user/admin_area/settings/import_export_rate_limits.md @@ -5,28 +5,26 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project/group import/export rate limits **(FREE SELF)** +# Rate limits for imports and exports of project and groups **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35728) in GitLab 13.2. -The following table includes configurable rate limits. The following table includes limits on a -per minute per user basis: +You can configure the rate limits for imports and exports of projects and groups: -| Limit | Default (per minute per user) | -|--------------------------|-------------------------------| -| Project Import | 6 | -| Project Export | 6 | -| Project Export Download | 1 | -| Group Import | 6 | -| Group Export | 6 | -| Group Export Download | 1 | +To change a rate limit: -All rate limits are: +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, then expand **Import and export rate limits**. +1. Change the value of any rate limit. The rate limits are per minute per user, not per IP address. + Set to `0` to disable a rate limit. -- Configurable through the top bar at **Menu > Admin > Settings > Network > Import/Export Rate Limits** -- Applied per minute per user -- Not applied per IP address -- Active by default. To disable, set the option to `0` -- Logged to `auth.log` file if exceed rate limit +| Limit | Default | +|-------------------------|---------| +| Project Import | 6 | +| Project Export | 6 | +| Project Export Download | 1 | +| Group Import | 6 | +| Group Export | 6 | +| Group Export Download | 1 | - +When a user exceeds a rate limit, it is logged in `auth.log`. diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 21ca1c573fe..ec5f3ca812f 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -17,8 +17,8 @@ documentation for all current settings and limits on the GitLab.com instance. To access the default page for Admin Area settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. | Option | Description | | ------ | ----------- | @@ -37,8 +37,9 @@ To access the default page for Admin Area settings: | Option | Description | | ------ | ----------- | -| [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | +| [Elasticsearch](../../../integration/elasticsearch.md#enable-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | | [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). | +| [Mailgun](../../../administration/integration/mailgun.md) | Enable your GitLab instance to receive invite email bounce events from Mailgun, if it is your email provider. | | [PlantUML](../../../administration/integration/plantuml.md) | Allow rendering of PlantUML diagrams in documents. | | [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE SAAS)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | @@ -96,9 +97,10 @@ To access the default page for Admin Area settings: | Performance optimization | [Write to "authorized_keys" file](../../../administration/operations/fast_ssh_key_lookup.md#setting-up-fast-lookup-via-gitlab-shell) and [Push event activities limit and bulk push events](push_event_activities_limit.md). Various settings that affect GitLab performance. | | [User and IP rate limits](user_and_ip_rate_limits.md) | Configure limits for web and API requests. | | [Package Registry Rate Limits](package_registry_rate_limits.md) | Configure specific limits for Packages API requests that supersede the user and IP rate limits. | +| [Git LFS Rate Limits](git_lfs_rate_limits.md) | Configure specific limits for Git LFS requests that supersede the user and IP rate limits. | | [Outbound requests](../../../security/webhooks.md) | Allow requests to the local network from hooks and services. | | [Protected Paths](protected_paths.md) | Configure paths to be protected by Rack Attack. | -| [Incident Management](../../../operations/incident_management/index.md) Limits | Configure limits on the number of inbound alerts able to be sent to a project. | +| [Incident Management](../../../operations/incident_management/index.md) Limits | Limit the number of inbound alerts that can be sent to a project. | | [Notes creation limit](rate_limit_on_notes_creation.md)| Set a rate limit on the note creation requests. | ## Geo @@ -118,12 +120,13 @@ To access the default page for Admin Area settings: | [Polling interval multiplier](../../../administration/polling.md) | Configure how frequently the GitLab UI polls for updates. | | [Gitaly timeouts](gitaly_timeouts.md) | Configure Gitaly timeouts. | | Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). | +| [Sidekiq Job Limits](sidekiq_job_limits.md) | Limit the size of Sidekiq jobs stored in Redis. | ### Default first day of the week You can change the [Default first day of the week](../../profile/preferences.md) for the entire GitLab instance: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Preferences**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Preferences**. 1. Scroll to the **Localization** section, and select your desired first day of the week. diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 8a796435ef8..862bf3b1652 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -7,7 +7,7 @@ type: reference # Instance template repository **(PREMIUM SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in GitLab Premium 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in GitLab Premium 11.3. In hosted systems, enterprises often have a need to share their own templates across teams. This feature allows an administrator to pick a project to be the @@ -19,8 +19,8 @@ while the project remains secure. To select a project to serve as the custom template repository: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Templates**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Templates**. 1. Select the project:  diff --git a/doc/user/admin_area/settings/package_registry_rate_limits.md b/doc/user/admin_area/settings/package_registry_rate_limits.md index 6e7b9b0da30..1aeb011d880 100644 --- a/doc/user/admin_area/settings/package_registry_rate_limits.md +++ b/doc/user/admin_area/settings/package_registry_rate_limits.md @@ -7,28 +7,47 @@ type: reference # Package Registry Rate Limits **(FREE SELF)** -Rate limiting is a common technique used to improve the security and durability of a web -application. For more details, see [Rate limits](../../../security/rate_limits.md). General user and -IP rate limits can be enforced from the top bar at -**Menu > Admin > Settings > Network > User and IP rate limits**. -For more details, see [User and IP rate limits](user_and_ip_rate_limits.md). - With the [GitLab Package Registry](../../packages/package_registry/index.md), you can use GitLab as a private or public registry for a variety of common package managers. You can publish and share packages, which others can consume as a dependency in downstream projects through the [Packages API](../../../api/packages.md). -When downloading such dependencies in downstream projects, many requests are made through the -Packages API. You may therefore reach enforced user and IP rate limits. To address this issue, you -can define specific rate limits for the Packages API in -**Menu > Admin > Settings > Network > Package Registry Rate Limits**: +If downstream projects frequently download such dependencies, many requests are made through the +Packages API. You may therefore reach enforced [user and IP rate limits](user_and_ip_rate_limits.md). +To address this issue, you can define specific rate limits for the Packages API: + +- [Unauthenticated requests (per IP)](#enable-unauthenticated-request-rate-limit-for-packages-api). +- [Authenticated API requests (per user)](#enable-authenticated-api-request-rate-limit-for-packages-api). + +These limits are disabled by default. + +When enabled, they supersede the general user and IP rate limits for requests to +the Packages API. You can therefore keep the general user and IP rate limits, and +increase the rate limits for the Packages API. Besides this precedence, there is +no difference in functionality compared to the general user and IP rate limits. + +## Enable unauthenticated request rate limit for packages API + +To enable the unauthenticated request rate limit: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **Package registry rate limits**. +1. Select **Enable unauthenticated request rate limit**. + + - Optional. Update the **Maximum unauthenticated requests per rate limit period per IP** value. + Defaults to `800`. + - Optional. Update the **Unauthenticated rate limit period in seconds** value. + Defaults to `15`. + +## Enable authenticated API request rate limit for packages API -- Unauthenticated Packages API requests -- Authenticated Packages API requests +To enable the authenticated API request rate limit: -These limits are disabled by default. When enabled, they supersede the general user and IP rate -limits for requests to the Packages API. You can therefore keep the general user and IP rate limits, -and increase (if necessary) the rate limits for the Packages API. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **Package registry rate limits**. +1. Select **Enable authenticated API request rate limit**. -Besides this precedence, there are no differences in functionality compared to the general user and -IP rate limits. For more details, see [User and IP rate limits](user_and_ip_rate_limits.md). + - Optional. Update the **Maximum authenticated API requests per rate limit period per user** value. + Defaults to `1000`. + - Optional. Update the **Authenticated API rate limit period in seconds** value. + Defaults to `15`. diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 3b949b638d8..aadabe4d6ad 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -22,8 +22,8 @@ Only the complete settings for an integration can be inherited. Per-field inheri > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2137) in GitLab 13.3 for project-level integrations. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level integrations. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Integrations**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Enter configuration details and click **Save changes**. @@ -54,8 +54,8 @@ integration on all non-configured groups and projects by default. ### Remove an instance-level default setting -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Integrations**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Click **Reset** and confirm. @@ -68,8 +68,8 @@ Resetting an instance-level default setting removes the integration from all pro You can view which projects in your instance use custom settings that [override the instance-level default settings](#use-custom-settings-for-a-group-or-project-integration) for an integration. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Integrations**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Select the **Projects using custom settings** tab. diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index 21e4f32ff8d..760ce96d987 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -26,8 +26,8 @@ the activity feed. To modify this setting: - In the Admin Area: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. - 1. In the left sidebar, select **Settings > Network**, then expand **Performance optimization**. + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Settings > Network**, then expand **Performance optimization**. - Through the [Application settings API](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) as `push_event_activities_limit`. diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md index bba61a7b913..a2e8a875ebb 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This setting allows you to rate limit the requests to the issue and epic creation endpoints. To can change its value: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Issues Rate Limits**. 1. Under **Max requests per minute per user**, enter the new value. diff --git a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md index 7615ad6f81d..0a07cf095ee 100644 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -9,15 +9,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53637) in GitLab 13.9. -This setting allows you to rate limit the requests to the note creation endpoint. +You can configure the per-user rate limit for requests to the note creation endpoint. To change the note creation rate limit: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Network**. -1. Expand **Notes Rate Limits**. -1. Under **Max requests per minute per user**, enter the new value. -1. Optional. Under **List of users to be excluded from the limit**, list users to be excluded from the limit. +1. Expand **Notes rate limit**. +1. In the **Maximum requests per minute** box, enter the new value. +1. Optional. In the **Users to exclude from the rate limit** box, list users allowed to exceed the limit. 1. Select **Save changes**. This limit is: diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md index 24b69ba74c7..020d02b1635 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -11,8 +11,8 @@ type: reference This setting defaults to `300` requests per minute, and allows you to rate limit the requests to raw endpoints: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Network**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**. 1. Expand **Performance optimization**. For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` are blocked. Access to the raw file is released after 1 minute. diff --git a/doc/user/admin_area/settings/sidekiq_job_limits.md b/doc/user/admin_area/settings/sidekiq_job_limits.md new file mode 100644 index 00000000000..c6a783beb3f --- /dev/null +++ b/doc/user/admin_area/settings/sidekiq_job_limits.md @@ -0,0 +1,36 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference +--- + +# Sidekiq job size limits **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68982) in GitLab 14.3. + +[Sidekiq](../../../administration/sidekiq.md) jobs get stored in +Redis. To avoid excessive memory for Redis, we: + +- Compress job arguments before storing them in Redis. +arguments before storing them in Redis, and rejecting jobs that exceed +- Reject jobs that exceed the specified threshold limit after compression. + +To access Sidekiq job size limits: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Preferences**. +1. Expand **Sidekiq job size limits**. +1. Adjust the compression threshold or size limit. The compression can + be disabled by selecting the **Track** mode. + +## Available settings + +| Setting | Default | Description | +|-------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Limiting mode | Compress | This mode compresses the jobs at the specified threshold and rejects them if they exceed the specified limit after compression. | +| Sidekiq job compression threshold (bytes) | 100 000 (100 KB) | When the size of arguments exceeds this threshold, they are compressed before being stored in Redis. | +| Sidekiq job size limit (bytes) | 0 | The jobs exceeding this size after compression are rejected. This avoids excessive memory usage in Redis leading to instability. Setting it to 0 prevents rejecting jobs. | + +After changing these values, [restart +Sidekiq](../../../administration/restart_gitlab.md). diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 333e9465c31..223ffeebd44 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -13,8 +13,8 @@ You can use **Sign-in restrictions** to customize authentication restrictions fo To access sign-in restriction settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Sign-in restrictions** section. ## Password authentication enabled @@ -26,7 +26,7 @@ You can restrict the password authentication for web interface and Git over HTTP ## Admin Mode -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10. When this feature is enabled, instance administrators are limited as regular users. During that period, they do not have access to all projects, groups, or the **Admin Area** menu. @@ -118,7 +118,7 @@ For example, if you include the following information in the noted text box: To access this text box: 1. On the top bar, select **Menu > Admin**. -1. In the left sidebar, select **Settings > General**, and expand the **Sign-in restrictions** section. +1. On the left sidebar, select **Settings > General**, and expand the **Sign-in restrictions** section. ``` Your users see the **Custom sign-in text** when they navigate to the sign-in screen for your diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index c774ae2eecc..dc09d6a5132 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -22,8 +22,8 @@ you do not expect public users to sign up for an account. To disable sign ups: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Clear the **Sign-up enabled** checkbox, then select **Save changes**. ## Require administrator approval for new sign ups @@ -38,8 +38,8 @@ enabled by default for new GitLab instances. It is only applicable if sign ups a To require administrator approval for new sign ups: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Select the **Require admin approval for new sign-ups** checkbox, then select **Save changes**. In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273258), if an administrator disables this setting, the users in pending approval state are @@ -52,8 +52,8 @@ their email address before they are allowed to sign in. To enforce confirmation of the email address used for new sign ups: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Select the **Enable email restrictions for sign ups** checkbox, then select **Save changes**. ## User cap **(FREE SELF)** @@ -70,8 +70,8 @@ user cap, the users in pending approval state are automatically approved in a ba ### Set the user cap number -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Enter a number in **User cap**. 1. Select **Save changes**. @@ -80,8 +80,8 @@ New user sign ups are subject to the user cap restriction. ## Remove the user cap -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Remove the number from **User cap**. 1. Select **Save changes**. @@ -122,15 +122,11 @@ email addresses to disallowed domains after sign up. ### Allowlist email domains -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/598) in GitLab 7.11.0 - You can restrict users only to sign up using email addresses matching the given domains list. ### Denylist email domains -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5259) in GitLab 8.10. - You can block users from signing up when using an email addresses of specific domains. This can reduce the risk of malicious users creating spam accounts with disposable email addresses. @@ -138,8 +134,8 @@ reduce the risk of malicious users creating spam accounts with disposable email To create an email domain allowlist or denylist: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. For the allowlist, you must enter the list manually. For the denylist, you can enter the list manually or upload a `.txt` file that contains list entries. diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 21805ef771f..c7c41e665ec 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -17,8 +17,8 @@ for example `https://gitlab.example.com/-/users/terms`. To enforce acceptance of a Terms of Service and Privacy Policy: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Terms of Service and Privacy Policy** section. 1. Check the **All users must accept the Terms of Service and Privacy Policy to access GitLab** checkbox. 1. Input the text of the **Terms of Service and Privacy Policy**. You can use [Markdown](../../markdown.md) diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 6f7cb081315..a9c8c5d2a76 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -15,7 +15,7 @@ for using [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/ To toggle the display of third-party offers: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings**, and expand **Third-party offers**. 1. Select **Do not display offers from third parties**. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 89c6be9608b..330a25087ef 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -73,9 +73,10 @@ If your GitLab instance is behind a proxy, set the appropriate To enable or disable Service Ping and version check: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Metrics and profiling**, and expand **Usage statistics**. -1. Select or clear the **Version check** and **Service ping** checkboxes. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Metrics and profiling**. +1. Expand **Usage statistics**. +1. Select or clear the **Enable version check** and **Enable service ping** checkboxes. 1. Select **Save changes**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index fdeda0cf451..32f08801c76 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -13,30 +13,78 @@ of a web application. For more details, see The following limits are disabled by default: -- Unauthenticated requests -- Authenticated API requests -- Authenticated web requests +- [Unauthenticated API requests (per IP)](#enable-unauthenticated-api-request-rate-limit). +- [Unauthenticated web requests (per IP)](#enable-unauthenticated-web-request-rate-limit). +- [Authenticated API requests (per user)](#enable-authenticated-api-request-rate-limit). +- [Authenticated web requests (per user)](#enable-authenticated-web-request-rate-limit). -To enforce any or all of them: +NOTE: +By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations +may trigger the rate limits configured for unauthenticated requests. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**: -  +## Enable unauthenticated API request rate limit - NOTE: - By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations - may trigger the rate limits configured for unauthenticated requests. +To enable the unauthenticated request rate limit: -## Response text +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. Select **Enable unauthenticated API request rate limit**. + + - Optional. Update the **Maximum unauthenticated API requests per rate limit period per IP** value. + Defaults to `3600`. + - Optional. Update the **Unauthenticated rate limit period in seconds** value. + Defaults to `3600`. + +## Enable unauthenticated web request rate limit + +To enable the unauthenticated request rate limit: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. Select **Enable unauthenticated web request rate limit**. + + - Optional. Update the **Maximum unauthenticated web requests per rate limit period per IP** value. + Defaults to `3600`. + - Optional. Update the **Unauthenticated rate limit period in seconds** value. + Defaults to `3600`. + +## Enable authenticated API request rate limit + +To enable the authenticated API request rate limit: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. Select **Enable authenticated API request rate limit**. + + - Optional. Update the **Maximum authenticated API requests per rate limit period per user** value. + Defaults to `7200`. + - Optional. Update the **Authenticated API rate limit period in seconds** value. + Defaults to `3600`. + +## Enable authenticated web request rate limit + +To enable the unauthenticated request rate limit: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. Select **Enable authenticated web request rate limit**. + + - Optional. Update the **Maximum authenticated web requests per rate limit period per user** value. + Defaults to `7200`. + - Optional. Update the **Authenticated web rate limit period in seconds** value. + Defaults to `3600`. + +## Use a custom rate limit response A request that exceeds a rate limit returns a 429 response code and a -plain-text body, which by default is: +plain-text body, which by default is `Retry later`. -```plaintext -Retry later -``` +To use a custom response: -It is possible to customize this response text in the Admin Area. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. In the **Plain-text response to send to clients that hit a rate limit** text box, + add the plain-text response message. ## Response headers @@ -129,6 +177,10 @@ a comma-separated list of throttle names. The possible names are: - `throttle_unauthenticated` + - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_api` or `throttle_unauthenticated_web` instead. + `throttle_unauthenticated` is still supported and selects both of them. +- `throttle_unauthenticated_api` +- `throttle_unauthenticated_web` - `throttle_authenticated_api` - `throttle_authenticated_web` - `throttle_unauthenticated_protected_paths` @@ -136,6 +188,7 @@ The possible names are: - `throttle_authenticated_protected_paths_web` - `throttle_unauthenticated_packages_api` - `throttle_authenticated_packages_api` +- `throttle_authenticated_git_lfs` For example, to try out throttles for all authenticated requests to non-protected paths can be done by setting diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index c46aec76e57..7f3f4b32802 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -13,8 +13,8 @@ specific controls on branches, projects, snippets, groups, and more. To access the visibility and access control options: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. ## Protect default branches @@ -33,8 +33,8 @@ or configure [branch protection for groups](../../group/index.md#change-the-defa To change the default branch protection for the entire instance: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select a **Default branch protection**: - **Not protected** - Both developers and maintainers can push new commits, @@ -59,8 +59,8 @@ can be overridden on a per-group basis by the group's owner. In disable this privilege for group owners, enforcing the instance-level protection rule: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Deselect the **Allow owners to manage default branch protection per group** checkbox. 1. Select **Save changes**. @@ -75,8 +75,8 @@ Instance-level protections for project creation define which roles can on the instance. To alter which roles have permission to create projects: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. For **Default project creation protection**, select the desired roles: - No one. @@ -90,23 +90,23 @@ Anyone with the **Owner** role, either at the project or group level, can delete a project. To allow only users with the Administrator role to delete projects: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to **Default project deletion protection**, and select **Only admins can delete project**. 1. Select **Save changes**. ## Default delayed project deletion **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2 for groups created after August 12, 2021. -Projects in a group (but not a personal namespace) can be deleted after a delayed period, by -[configuring in Group Settings](../../group/index.md#enable-delayed-project-removal). +Projects in a group (but not a personal namespace) can be deleted after a delayed period. +You can [configure it in group settings](../../group/index.md#enable-delayed-project-removal). To enable delayed project deletion by default in new groups: 1. Check the **Default delayed project deletion** checkbox. -1. Click **Save changes**. +1. Select **Save changes**. ## Default deletion delay **(PREMIUM SELF)** @@ -142,8 +142,8 @@ Alternatively, projects that are marked for removal can be deleted immediately. To set the default [visibility levels for new projects](../../../public_access/public_access.md): 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default project visibility: - **Private** - Project access must be granted explicitly to each user. If this @@ -157,8 +157,8 @@ To set the default [visibility levels for new projects](../../../public_access/p To set the default visibility levels for new [snippets](../../snippets.md): 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default snippet visibility. 1. Select **Save changes**. @@ -171,8 +171,8 @@ For more details on snippet visibility, read To set the default visibility levels for new groups: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default group visibility: - **Private** - The group and its projects can only be viewed by members. @@ -188,8 +188,8 @@ For more details on group visibility, see To restrict visibility levels for projects, snippets, and selected pages: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. 1. Select **Save changes**. @@ -202,8 +202,8 @@ For more details on project visibility, see You can specify from which hosting sites users can [import their projects](../../project/import/index.md): 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select each of **Import sources** to allow. 1. Select **Save changes**. @@ -214,8 +214,8 @@ To enable the export of [projects and their data](../../../user/project/settings/import_export.md#export-a-project-and-its-data): 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select **Project export enabled**. 1. Select **Save changes**. @@ -230,8 +230,8 @@ The GitLab restrictions apply at the application level. To specify the enabled Git access protocols: 1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired Git access protocols: - Both SSH and HTTP(S) diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index e96ce969b3a..89026e56a27 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -10,8 +10,8 @@ You can analyze your users' GitLab activities over time. To view user cohorts: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Overview > Users**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select the **Cohorts** tab. ## Overview diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 7cb5db4379a..5b7e6e39187 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -75,12 +75,12 @@ in one place. [Learn more about instance-level analytics](../admin_area/analytics/index.md). -## Group-level analytics **(PREMIUM)** +## Group-level analytics > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195979) in GitLab 12.8. > - Moved to GitLab Premium in 13.9. -The following analytics features are available at the group level: +GitLab provides several analytics features at the group level. Some of these features require you to use a higher tier than GitLab Free. - [Application Security](../application_security/security_dashboard/#group-security-dashboard) - [Contribution](../group/contribution_analytics/index.md) @@ -93,7 +93,7 @@ The following analytics features are available at the group level: ## Project-level analytics -The following analytics features are available at the project level: +You can use GitLab to review analytics at the project level. Some of these features require you to use a higher tier than GitLab Free. - [Application Security](../application_security/security_dashboard/#project-security-dashboard) - [CI/CD](ci_cd_analytics.md) @@ -105,8 +105,10 @@ The following analytics features are available at the project level: - [Repository](repository_analytics.md) - [Value Stream](value_stream_analytics.md) -## User-configurable analytics **(ULTIMATE)** +## User-configurable analytics The following analytics features are available for users to create personalized views: - [Application Security](../application_security/security_dashboard/#security-center) + +Be sure to review the documentation page for this feature for GitLab tier requirements. diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index b77a25a9d62..44b8c87ee27 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -7,13 +7,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue Analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. Issue Analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your project sidebar and select **Analytics > Issue**. +To access the chart: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Issue**. Hover over each bar to see the total number of issues. diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 321e2f0fc24..44e4cd8b371 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -20,7 +20,10 @@ The Throughput chart shows the number of merge requests merged, by month. Merge a common measure of productivity in software engineering. Although imperfect, the average throughput can be a meaningful benchmark of your team's overall productivity. -To access Merge Request Analytics, from your project's menu, go to **Analytics > Merge Request**. +To access Merge Request Analytics: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Merge request**. ## Use cases @@ -93,10 +96,10 @@ You can filter the data that is presented on the page based on the following par To filter results: -1. Click on the filter bar. +1. Select the filter bar. 1. Select a parameter to filter by. 1. Select a value from the autocompleted results, or enter search text to refine the results. -1. Hit the "Return" key. +1. Press Enter. ## Date range diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index a06d94caf69..391ec5c04d9 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -50,11 +50,11 @@ The following metrics and visualizations are available on a project or group lev > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13188) in GitLab 12.4. -GitLab has the ability to filter analytics based on a date range. To filter results: +You can filter analytics based on a date range. To filter results: 1. Select a group. -1. Optionally select a project. -1. Select a date range using the available date pickers. +1. Optional. Select a project. +1. Select a date range by using the available date pickers. ## Permissions diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 9a1aed9c39f..7057d069e95 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -64,7 +64,7 @@ Items aren't included in the stage time calculation if they have not reached the | Stage | Description | |---------|---------------| -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already includes an [Issue Board list](../project/issue_board.md) created for it. | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already includes an [issue board list](../project/issue_board.md) created for it. | | Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. That first branch commit triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is *not* included in a commit, that data is not included in the measurement time of the stage. | | Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR). The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, it's assumed that `xxx` is issue number for the merge request). If there is no closing pattern, the start time is set to the create time of the first commit. | | Test | Essentially the start to finish time for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | @@ -85,7 +85,7 @@ How this works: In short, the Value Stream Analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include data for: - Merge requests that do not close an issue. -- Issues that do not include labels present in the Issue Board +- Issues that do not include labels present in the issue board. - Issues without a milestone. - Staging stages, in projects without a [production environment](#how-the-production-environment-is-identified). diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 7ed36572be4..e32989c2915 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -85,7 +85,7 @@ In GitLab 14.0 and later, API fuzzing configuration files must be in your reposi ### Web API fuzzing configuration form -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -98,17 +98,16 @@ a YAML snippet that you can paste in your GitLab CI/CD configuration. To generate an API Fuzzing configuration snippet: -1. From your project's home page, go to **Security & Compliance > Configuration** in the left - sidebar. -1. Select **Configure** in the **API Fuzzing** row. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **API Fuzzing** row, select **Configure**. 1. Complete the form as needed. Read below for more information on available configuration options. 1. Select **Generate code snippet**. A modal opens with the YAML snippet corresponding to the options you've selected in the form. 1. Choose one of the following actions: - 1. Select **Copy code and open `.gitlab-ci.yml` file** to copy the snippet to your clipboard and - be redirected to your project's `.gitlab-ci.yml` file where you can paste the YAML - configuration. - 1. Select **Copy code only** to copy the snippet to your clipboard and close the modal. + 1. To copy the snippet to your clipboard and be redirected to your project's `.gitlab-ci.yml` file, + where you can paste the YAML configuration, select **Copy code and open `.gitlab-ci.yml` file**. + 1. To copy the snippet to your clipboard and close the modal, select **Copy code only**. ### OpenAPI Specification @@ -995,7 +994,7 @@ Follow these steps to view details of a fuzzing fault: **API Fuzzing detected N potential vulnerabilities**. Click the title to display the fault details. -1. Click the fault's title to display the fault's details. The table below describes these details. +1. Select the fault's title to display the fault's details. The table below describes these details. | Field | Description | |:--------------------|:----------------------------------------------------------------------------------------| diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 664fcd9b72f..98e241ba3bd 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -13,61 +13,56 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.10. > - [Redesigned](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in 14.2. -The Security Configuration page displays what security scans are available, links to documentation and also simple enablement tools for the current project. +The Security Configuration page lists the following for the security testing and compliance tools: -To view a project's security configuration, go to the project's home page, -then in the left sidebar go to **Security & Compliance > Configuration**. - -For each security control the page displays: - -- Its name, description and a documentation link. +- Name, description, and a documentation link. - Whether or not it is available. - A configuration button or a link to its configuration guide. +The status of each security control is determined by the project's latest default branch +[CI pipeline](../../../ci/pipelines/index.md). +If a job with the expected security report artifact exists in the pipeline, the feature's status is +_enabled_. + +If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), +all security features are configured by default. + +To view a project's security configuration: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. + +Select **Configuration history** to see the `.gitlab-ci.yml` file's history. + ## Security testing You can configure the following security controls: -- Auto DevOps - - Click **Enable Auto DevOps** on the alert to enable it for the current project. For more details, see [Auto DevOps](../../../topics/autodevops/index.md). -- SAST - - Click **Enable SAST** to use SAST for the current project. For more details, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). -- DAST **(ULTIMATE)** - - Click **Enable DAST** to use DAST for the current Project. To manage the available DAST profiles used for on-demand scans Click **Manage Scans**. For more details, see [DAST on-demand scans](../dast/index.md#on-demand-scans). +- Static Application Security Testing (SAST) + - Select **Enable SAST** to configure SAST for the current project. + For more details, read [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). +- Dynamic Application Security Testing (DAST) **(ULTIMATE)** + - Select **Enable DAST** to configure DAST for the current project. + - Select **Manage scans** to manage the saved DAST scans, site profiles, and scanner profiles. + For more details, read [DAST on-demand scans](../dast/index.md#on-demand-scans). - Dependency Scanning **(ULTIMATE)** - Select **Configure via Merge Request** to create a merge request with the changes required to enable Dependency Scanning. For more details, see [Enable Dependency Scanning via an automatic merge request](../dependency_scanning/index.md#enable-dependency-scanning-via-an-automatic-merge-request). - - Container Scanning **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). - Cluster Image Scanning **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). - Secret Detection - Select **Configure via Merge Request** to create a merge request with the changes required to - enable Secret Detection. For more details, see [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). - + enable Secret Detection. For more details, read [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). - API Fuzzing **(ULTIMATE)** - - Click **Enable API Fuzzing** to use API Fuzzing for the current Project. For more details, see [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). + - Select **Enable API Fuzzing** to use API Fuzzing for the current project. For more details, read [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). - Coverage Fuzzing **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#configuration). - -## Status **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. - -The status of each security control is determined by the project's latest default branch -[CI pipeline](../../../ci/pipelines/index.md). -If a job with the expected security report artifact exists in the pipeline, the feature's status is -_enabled_. - -If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), -all security features are configured by default. - -Click **View history** to see the `.gitlab-ci.yml` file's history. + - Can be configured with `.gitlab-ci.yml`. For more details, read [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#configuration). ## Compliance **(ULTIMATE)** You can configure the following security controls: - License Compliance **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [License Compliance](../../../user/compliance/license_compliance/index.md#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#configuration). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 5791351a067..2b3d4dbfc0a 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,14 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -WARNING: -Versions of GitLab prior to 14.0 used Clair as the default container scanning engine. GitLab 14.0 -removes Clair from the product and replaces it with two new scanners. If you -run container scanning with the default settings, GitLab switches you seamlessly and automatically -to Trivy in GitLab 14.0. However, if you customized the variables in your container scanning job, -you should review the [migration guide](#change-scanners) -and make any necessary updates. - Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based apps. @@ -57,37 +49,9 @@ To enable container scanning in your pipeline, you need the following: ## Configuration -How you enable container scanning depends on your GitLab version: - -- GitLab 11.9 and later: [Include](../../../ci/yaml/index.md#includetemplate) the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) - that comes with your GitLab installation. -- GitLab versions earlier than 11.9: Copy and use the job from the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). - -Other changes: - -- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for - [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the - `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses - [`centos:centos8`](https://hub.docker.com/_/centos) - as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) - script and instead executes the analyzer by default. Any customizations made to the - `container_scanning` job's [`before_script`](../../../ci/yaml/index.md#before_script) - and [`after_script`](../../../ci/yaml/index.md#after_script) - blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based - Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables) - variable. -- GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with - [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. -- GitLab 14.0 [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) - an integration with [Trivy](https://github.com/aquasecurity/trivy) - as the default for container scanning, and also [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326279) - an integration with [Grype](https://github.com/anchore/grype) - as an alternative scanner. - -To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the -following to your `.gitlab-ci.yml` file: +To enable container scanning, add the +[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) +to your `.gitlab-ci.yml` file: ```yaml include: @@ -157,7 +121,7 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | All | | `CS_ANALYZER_IMAGE` | `registry.gitlab.com/security-products/container-scanning:4` | Docker image of the analyzer. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | -| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | Trivy. The registry must listen on port `80/tcp`. | +| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | | `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | | `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$DOCKER_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). | All | @@ -625,3 +589,29 @@ To prevent the error, ensure the Docker version that the runner is using is ### Getting warning message `gl-container-scanning-report.json: no matching files` For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +## Changes + +- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for + [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the + `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses + [`centos:centos8`](https://hub.docker.com/_/centos) + as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) + script and instead executes the analyzer by default. Any customizations made to the + `container_scanning` job's [`before_script`](../../../ci/yaml/index.md#before_script) + and [`after_script`](../../../ci/yaml/index.md#after_script) + blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based + Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables) + variable. +- GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with + [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. +- GitLab 13.9 [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/321451) the integration with + [Clair](https://github.com/quay/clair/). +- GitLab 14.0 [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) + an integration with [Trivy](https://github.com/aquasecurity/trivy) + as the default for container scanning, and also [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326279) + an integration with [Grype](https://github.com/anchore/grype) + as an alternative scanner. + +Other changes to the container scanning analyzer can be found in the project's +[changelog](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/blob/master/CHANGELOG.md). diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 679d20a6394..0d5eb2b6d50 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Coverage Guided Fuzz Testing **(ULTIMATE)** +# Coverage-guided fuzz testing **(ULTIMATE)** GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. Coverage-guided fuzzing sends @@ -82,7 +82,7 @@ The `my_fuzz_target` job (the separate job for your fuzz target) does the follow - Runs on a fuzz stage that usually comes after a test stage. The `gitlab-cov-fuzz` is a command-line tool that runs the instrumented application. It parses and -analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](#glossary) +analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](../terminology/index.md#corpus) and crash events from previous pipelines automatically. This helps your fuzz targets build on the progress of previous fuzzing jobs. The parsed crash events and data are written to `gl-coverage-fuzzing-report.json`. @@ -97,7 +97,7 @@ Each fuzzing step outputs these artifacts: - `crashes`: Holds all crash events the current job encountered as well as those not fixed in previous jobs. -### Types of Fuzzing Jobs +### Types of fuzzing jobs There are two types of jobs: @@ -127,7 +127,7 @@ any option available in the underlying fuzzing engine. | `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | | `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | -The files in the seed corpus (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new +The files in the [seed corpus](../terminology/index.md#seed-corpus) (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new files to your Git repository. There's usually no need to frequently update the seed corpus. As part of the GitLab artifacts system, GitLab saves in a corpus directory the new test cases that every run generates. In any subsequent runs, GitLab also reuses the generated corpus together with the seed @@ -172,13 +172,13 @@ Here's an example coverage fuzzing report: } ``` -### Additional Configuration +### Additional configuration The `gitlab-cov-fuzz` command passes all arguments it receives to the underlying fuzzing engine. You can therefore use all the options available in that fuzzing engine. For more information on these options, see the underlying fuzzing engine's documentation. -### Offline Environment +### Offline environment To use coverage fuzzing in an offline environment, follow these steps: @@ -262,12 +262,3 @@ vulnerability: - Scanner: The scanner that detected the vulnerability (for example, Coverage Fuzzing). - Scanner Provider: The engine that did the scan. For Coverage Fuzzing, this can be any of the engines listed in [Supported fuzzing engines and languages](#supported-fuzzing-engines-and-languages). - -### Glossary - -- Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds - up the fuzz target substantially. This can be either manually created test cases or auto-generated - with the fuzz target itself from previous runs. -- Corpus: The set of meaningful test cases that are generated while the fuzzer is running. Each - meaningful test case produces new coverage in the tested program. It's advised to re-use the - corpus and pass it to subsequent runs. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index e8fbc17327c..5094ccd2196 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -19,7 +19,7 @@ The browser-based crawler works by loading the target application into a special such as clicking on a link or filling in a form. For each action found, the crawler will execute it, take a new snapshot and determine what in the page changed from the previous snapshot. Crawling continues by taking more snapshots and finding subsequent actions. -The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don’t understand. This results in better coverage of the website. +The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don't understand. This results in better coverage of the website. Using the browser-based crawler should provide greater coverage for most web applications, compared with the current DAST AJAX crawler. The new crawler replaces the AJAX crawler and is specifically designed to maximize crawl coverage in modern web applications. While both crawlers are currently used in conjunction with the existing DAST scanner, the combination of the browser-based crawler with the current DAST scanner is much more effective at finding and testing every page in an application. diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 725fab85789..f771bc82d58 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -88,3 +88,7 @@ stages: include: - template: DAST.latest.gitlab-ci.yml ``` + +## Lack of IPv6 support + +Due to the underlying [ZAProxy engine not supporting IPv6](https://github.com/zaproxy/zaproxy/issues/3705), DAST is unable to scan or crawl IPv6-based applications. diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 7455915761c..0d60701b030 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -74,7 +74,7 @@ If your application utilizes Docker containers you have another option for deplo After your Docker build job completes and your image is added to your container registry, you can use the image as a [service](../../../ci/services/index.md). -By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. +By using service definitions in your `.gitlab-ci.yml`, you can scan services with the DAST analyzer. ```yaml stages: @@ -328,6 +328,8 @@ Vulnerability rules in an API scan are different than those in a normal website A new DAST API scanning engine is available in GitLab 13.12 and later. For more details, see [DAST API scanning engine](../dast_api). The new scanning engine supports REST, SOAP, GraphQL, and generic APIs using forms, XML, and JSON. Testing can be performed using OpenAPI, Postman Collections, and HTTP Archive (HAR) documents. +The target API instance’s base URL is provided by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. + #### Specification format API scans support OpenAPI V2 and OpenAPI V3 specifications. You can define these specifications using `JSON` or `YAML`. @@ -339,7 +341,7 @@ The specification does not have to be hosted on the same host as the API being t ```yaml include: - - template: DAST.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml variables: DAST_API_OPENAPI: http://my.api/api-specification.yml @@ -390,7 +392,7 @@ the following DAST configuration can be used: ```yaml include: - - template: DAST.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml variables: DAST_API_OPENAPI: http://api-test.host.com/api-specification.yml @@ -405,7 +407,7 @@ Headers are applied to every request DAST makes. ```yaml include: - - template: DAST.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml variables: DAST_API_OPENAPI: http://api-test.api.com/api-specification.yml @@ -554,6 +556,9 @@ By default, several rules are disabled because they either take a long time to run or frequently generate false positives. The complete list of disabled rules can be found in [exclude_rules.yml](https://gitlab.com/gitlab-org/security-products/dast/-/blob/main/src/config/exclude_rules.yml). +The lists for `DAST_EXCLUDE_RULES` and `DAST_ONLY_INCLUDE_RULES` **must** be enclosed in double +quotes (`"`), otherwise they are interpreted as numeric values. + ### Hide sensitive information > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. @@ -742,7 +747,7 @@ dast: when: always ``` -### Available CI/CD variables +## Available CI/CD variables These CI/CD variables are specific to DAST. They can be used to customize the behavior of DAST to your requirements. @@ -762,7 +767,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | | `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | | `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | | `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | @@ -772,7 +777,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | | `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | -| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | | `DAST_PASSWORD` <sup>1,2</sup> | string | The password to authenticate to in the website. Example: `P@55w0rd!` | | `DAST_PASSWORD_FIELD` <sup>1,2</sup> | string | The selector of password field at the sign-in HTML form. Example: `id:password` | | `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | @@ -795,7 +800,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be 1. Available to an on-demand DAST scan. 1. Used for authentication. -#### Selectors +### Selectors Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. @@ -808,7 +813,7 @@ Selectors have the format `type`:`search string`. The crawler will search for th | `xpath` | `xpath://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | | None provided | `a.click-me` | Defaults to searching using a CSS selector. | -##### Find selectors with Google Chrome +#### Find selectors with Google Chrome Chrome DevTools element selector tool is an effective way to find a selector. @@ -824,7 +829,7 @@ Chrome DevTools element selector tool is an effective way to find a selector. In this example, the `id="user_login"` appears to be a good candidate. You can use this as a selector as the DAST username field by setting `DAST_USERNAME_FIELD: "id:user_login"`. -##### Choose the right selector +#### Choose the right selector Judicious choice of selector leads to a scan that is resilient to the application changing. @@ -919,7 +924,7 @@ The DAST job does not require the project's repository to be present when runnin > - Auditing for DAST profile management was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger -the scan. You must start it manually. +the scan. You must either start it manually, or schedule it to run. An on-demand DAST scan: @@ -928,8 +933,6 @@ An on-demand DAST scan: - Is associated with your project's default branch. - Is saved on creation so it can be run later. -In GitLab 13.10 and later, you can select to run an on-demand scan against a specific branch. - ### On-demand scan modes An on-demand scan can be run in active or passive mode: @@ -941,23 +944,34 @@ An on-demand scan can be run in active or passive mode: ### Run an on-demand DAST scan -NOTE: -You must have permission to run an on-demand DAST scan against a protected branch. -The default branch is automatically protected. For more information, see -[Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). - Prerequisites: +- You must have permission to run an on-demand DAST scan against a protected branch. The default + branch is automatically protected. For more information, read + [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). - A [scanner profile](#create-a-scanner-profile). - A [site profile](#create-a-site-profile). -- If you are running an active scan the site profile must be [validated](#validate-a-site-profile). +- If you are running an active scan the site profile must have been [validated](#validate-a-site-profile). + +You can run an on-demand scan immediately, once at a scheduled date and time or at a specified +frequency: + +- Every day +- Every week +- Every month +- Every 3 months +- Every 6 months +- Every year -To run an on-demand scan, either: +To run an on-demand scan immediately, either: -- [Create and run an on-demand scan](#create-and-run-an-on-demand-scan). +- [Create and run an on-demand scan immediately](#create-and-run-an-on-demand-scan-immediately). - [Run a previously saved on-demand scan](#run-a-saved-on-demand-scan). -#### Create and run an on-demand scan +To run an on-demand scan either at a scheduled date or frequency, read +[Schedule an on-demand scan](#schedule-an-on-demand-scan). + +#### Create and run an on-demand scan immediately 1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. @@ -965,44 +979,70 @@ To run an on-demand scan, either: 1. In GitLab 13.10 and later, select the desired branch from the **Branch** dropdown. 1. In **Scanner profile**, select a scanner profile from the dropdown. 1. In **Site profile**, select a site profile from the dropdown. -1. To run the on-demand scan now, select **Save and run scan**. Otherwise select **Save scan** to - [run](#run-a-saved-on-demand-scan) it later. +1. To run the on-demand scan immediately, select **Save and run scan**. Otherwise, select + **Save scan** to [run](#run-a-saved-on-demand-scan) it later. The on-demand DAST scan runs and the project's dashboard shows the results. -### List saved on-demand scans +#### Run a saved on-demand scan -To list saved on-demand scans: +To run a saved on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. In the **DAST Profiles** row, select **Manage**. 1. Select the **Saved Scans** tab. +1. In the scan's row, select **Run scan**. + + If the branch saved in the scan no longer exists, you must first + [edit the scan](#edit-an-on-demand-scan), select a new branch, and save the edited scan. -### View details of an on-demand scan +The on-demand DAST scan runs, and the project's dashboard shows the results. -To view details of an on-demand scan: +#### Schedule an on-demand scan + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per user, +ask an administrator to [disable the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md). +The feature is not ready for production use. + +To schedule a scan: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > On-demand Scans**. +1. Complete the **Scan name** and **Description** text boxes. +1. In GitLab 13.10 and later, from the **Branch** dropdown list, select the desired branch. +1. In the **Scanner profile** section, from the dropdown list, select a scanner profile. +1. In the **Site profile** section, from the dropdown list, select a site profile. +1. Select **Schedule scan**. +1. In the **Start time** section, select a time zone, date, and time. +1. From the **Repeats** dropdown list, select your desired frequency: + - To run the scan once, select **Never**. + - For a recurring scan, select any other option. +1. To run the on-demand scan immediately, select **Save and run scan**. To [run](#run-a-saved-on-demand-scan) it according to the schedule you set, select + **Save scan**. + +#### List saved on-demand scans + +To list saved on-demand scans: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. 1. Select the **Saved Scans** tab. -1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. -### Run a saved on-demand scan +#### View details of an on-demand scan -To run a saved on-demand scan: +To view details of an on-demand scan: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Select **Manage DAST scans**. 1. Select **Manage** in the **DAST Profiles** row. 1. Select the **Saved Scans** tab. -1. In the scan's row select **Run scan**. - - If the branch saved in the scan no longer exists, you must first - [edit the scan](#edit-an-on-demand-scan), select a new branch, and save the edited scan. - -The on-demand DAST scan runs and the project's dashboard shows the results. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. -### Edit an on-demand scan +#### Edit an on-demand scan To edit an on-demand scan: @@ -1014,7 +1054,7 @@ To edit an on-demand scan: 1. Edit the form. 1. Select **Save scan**. -### Delete an on-demand scan +#### Delete an on-demand scan To delete an on-demand scan: @@ -1049,11 +1089,7 @@ When an API site type is selected, a [host override](#host-override) is used to #### Site profile validation > - Site profile validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. -> - Meta tag validation [enabled on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2 and is ready for production use. -> - Meta tag validation [enabled with `dast_meta_tag_validation flag` flag](https://gitlab.com/gitlab-org/gitlab/-/issues/337711) for self-managed GitLab in GitLab 14.2 and is ready for production use. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the `dast_meta_tag_validation` flag](../../../administration/feature_flags.md). On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +> - Meta tag validation [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2. Site profile validation reduces the risk of running an active scan against the wrong website. A site must be validated before an active scan can run against it. The site validation methods are as @@ -1096,7 +1132,7 @@ To edit an existing site profile: 1. Edit the fields then select **Save profile**. If a site profile is linked to a security policy, a user cannot edit the profile from this page. See -[Scan Policies](../policies/index.md) +[Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. #### Delete a site profile @@ -1110,7 +1146,7 @@ To delete an existing site profile: 1. Select **Delete** to confirm the deletion. If a site profile is linked to a security policy, a user cannot delete the profile from this page. -See [Scan Policies](../policies/index.md) +See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. #### Validate a site profile @@ -1147,6 +1183,21 @@ The site is validated and an active scan can run against it. If a validated site profile's target URL is edited, the site's validation status is revoked. +#### Retry a failed validation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the `dast_failed_site_validations` flag](../../../administration/feature_flags.md). + +If a site profile's validation fails, you can retry it by selecting the **Retry validation** button +in the profiles list. + +When loading the DAST profiles library, past failed validations are listed above the profiles +list. You can also retry the validation from there by selecting the **Retry validation** link in +the alert. You can also dismiss the alert to revoke failed validations. + #### Revoke a site profile's validation status Note that all site profiles with the same URL have their validation status revoked. @@ -1240,7 +1291,7 @@ To edit a scanner profile: 1. Select **Save profile**. If a scanner profile is linked to a security policy, a user cannot edit the profile from this page. -See [Scan Policies](../policies/index.md) +See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. #### Delete a scanner profile @@ -1254,7 +1305,7 @@ To delete a scanner profile: 1. Select **Delete**. If a scanner profile is linked to a security policy, a user cannot delete the profile from this -page. See [Scan Policies](../policies/index.md) +page. See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. ### Auditing @@ -1311,9 +1362,9 @@ dast: By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If your DAST job does not rely on `environment_url.txt` to define the URL under test or any other files created in previous jobs, we recommend you don't download artifacts. To avoid downloading -artifacts, add the following to your `gitlab-ci.yml` file: +artifacts, add the following to your `.gitlab-ci.yml` file: -```json +```yaml dast: dependencies: [] ``` diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 48a784e0d03..055a2ceb161 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -897,7 +897,7 @@ variables: ### Exclude Paths -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `FUZZAPI_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 1cb21d34853..edfd0333d54 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab Ultimate 12.0. Use the dependency list to review your project's dependencies and key -details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. +details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. To see the dependency list, go to your project and select **Security & Compliance > Dependency List**. @@ -49,7 +49,7 @@ can also be sorted by name or by the packager that installed them. If a dependency has known vulnerabilities, view them by clicking the arrow next to the dependency's name or the badge that indicates how many known vulnerabilities exist. For each vulnerability, its severity and description appears below it. To view more details of a vulnerability, -select the vulnerability’s description. The [vulnerability's details](../vulnerabilities) page is opened. +select the vulnerability's description. The [vulnerability's details](../vulnerabilities) page is opened. ### Dependency paths @@ -78,8 +78,8 @@ You can download your project's full list of dependencies and their details in ### In the UI -You can download your project’s list of dependencies and their details in JSON format by selecting the **Export** button. Note that the dependency list only shows the results of the last successful pipeline to run on the default branch. +You can download your project's list of dependencies and their details in JSON format by selecting the **Export** button. Note that the dependency list only shows the results of the last successful pipeline to run on the default branch. ### Using the API -You can download your project’s list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). +You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 565b9c29934..d903ce58982 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -57,8 +57,8 @@ However, you can override the selection using the variable `DS_EXCLUDED_ANALYZER The language detection relies on CI job [`rules`](../../../ci/yaml/index.md#rules) and searches a maximum of two directory levels from the repository's root. For example, the -`gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or -`api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. +`gemnasium-dependency_scanning` job is enabled if a repository contains either `Gemfile`, +`api/Gemfile`, or `api/client/Gemfile`, but not if the only supported dependency file is `api/v1/client/Gemfile`. The following languages and dependency managers are supported: @@ -147,7 +147,7 @@ table.supported-languages ul { </tr> <tr> <td rowspan="2">Java</td> - <td><a href="https://gradle.org/">Gradle</a></td> + <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">1</a></b></sup></td> <td>Any</td> <td> <ul> @@ -228,7 +228,7 @@ table.supported-languages ul { <td> <ul> <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile</code></a></li> - <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">1</a></b></sup></li> + <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">2</a></b></sup></li> </ul> </td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -236,7 +236,7 @@ table.supported-languages ul { </tr> <tr> <td>Scala</td> - <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">2</a></b></sup></td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">3</a></b></sup></td> <td>Any</td> <td><code>build.sbt</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -247,6 +247,8 @@ table.supported-languages ul { ### Notes regarding supported languages and package managers +1. Although Gradle with Java 8 is supported, there are other issues such that Android project builds are not supported at this time. Please see the backlog issue [Android support for Dependency Scanning (gemnasium-maven)](https://gitlab.com/gitlab-org/gitlab/-/issues/336866) for more details. + 1. The presence of a `Pipfile.lock` file alone will _not_ trigger the analyzer; the presence of a `Pipfile` is still required in order for the analyzer to be executed. However, if a `Pipfile.lock` file is found, it will be used by `Gemnasium` to scan the exact package versions listed in this file. @@ -262,7 +264,7 @@ GitLab relies on [`rules:exists`](../../../ci/yaml/index.md#rulesexists) to star `Supported files` in the repository as shown in the [table above](#supported-languages-and-package-managers). The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if -a repository contains either a `Gemfile.lock` or `api/Gemfile.lock` file, but not if the only supported dependency file is `api/client/Gemfile.lock`. +a repository contains either a `Gemfile.lock`, `api/Gemfile.lock`, or `api/client/Gemfile.lock`, but not if the only supported dependency file is `api/v1/client/Gemfile.lock`. ### How multiple files are processed @@ -287,13 +289,13 @@ We execute both analyzers because they use different sources of vulnerability da #### Python -We only execute one build in the directory where a requirements file has been detected, such as `requirements.txt` or any +We only execute one installation in the directory where a requirements file has been detected, such as `requirements.txt` or any variation of this file (for example, `requirements.pip` or `requires.txt`). #### Java and Scala We only execute one build in the directory where a build file has been detected, such as `build.sbt` or `build.gradle`. -Please note, we support the following types of Java project stuctures: +Please note, we support the following types of Java project structures: - [multi-project sbt builds](https://www.scala-sbt.org/1.x/docs/Multi-Project.html) - [multi-project gradle builds](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) @@ -908,3 +910,19 @@ with a dependency on this version of Python should use `retire.js` version 2.10. ### Error: `dependency_scanning is used for configuration only, and its script should not be executed` For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). + +### Import multiple certificates for Java-based projects + +The `gemnasium-maven` analyzer reads the contents of the `ADDITIONAL_CA_CERT_BUNDLE` variable using `keytool`, which imports either a single certificate or a certificate chain. Multiple unrelated certificates are ignored and only the first one is imported by `keytool`. + +To add multiple unrelated certificates to the analyzer, you can declare a `before_script` such as this in the definition of the `gemnasium-maven-dependency_scanning` job: + +```yaml +gemnasium-maven-dependency_scanning: + before_script: + - . $HOME/.bashrc # make the java tools available to the script + - OIFS="$IFS"; IFS=""; echo $ADDITIONAL_CA_CERT_BUNDLE > multi.pem; IFS="$OIFS" # write ADDITIONAL_CA_CERT_BUNDLE variable to a PEM file + - csplit -z --digits=2 --prefix=cert multi.pem "/-----END CERTIFICATE-----/+1" "{*}" # split the file into individual certificates + - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions) + - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import +``` diff --git a/doc/user/application_security/img/mr_security_scanning_results_v14_3.png b/doc/user/application_security/img/mr_security_scanning_results_v14_3.png Binary files differnew file mode 100644 index 00000000000..3e0113dfb46 --- /dev/null +++ b/doc/user/application_security/img/mr_security_scanning_results_v14_3.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 50fd727b892..7b95769a81f 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -159,7 +159,9 @@ We recommended you run a scan of the `default` branch before enabling feature br The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both NEW and EXISTING findings. -From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View Full Report** to go directly to the **Security** tab in the latest branch pipeline. +From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View full report** to go directly to the **Security** tab in the latest branch pipeline. + + ## View security scan information in the pipeline Security tab @@ -221,7 +223,8 @@ For this approval group, you must set the number of approvals required to greate Follow these steps to enable `Vulnerability-Check`: -1. Go to your project and select **Settings > General**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. 1. Expand **Merge request approvals**. 1. Select **Enable** or **Edit**. 1. Set the **Security scanners** that the rule applies to. @@ -269,7 +272,7 @@ under your project's settings: ## DAST On-Demand Scans -If you don’t want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. +If you don't want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. ## Security report validation @@ -337,6 +340,16 @@ For more details about which findings or vulnerabilities you can view in each of ## Troubleshooting +### Secure job failing with exit code 1 + +If a Secure job is failing and it's unclear why, add `SECURE_LOG_LEVEL: "debug"` as a global CI/CD variable for +more verbose output that is helpful for troubleshooting. + +```yaml +variables: + SECURE_LOG_LEVEL: "debug" +``` + ### Outdated security reports When a security report generated for a merge request becomes outdated, the merge request shows a warning diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 3bf9d85cd0b..cdf54070d69 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -111,7 +111,7 @@ example of such a transfer: GitLab provides a [vendored template](../../../ci/yaml/index.md#includetemplate) to ease this process. -This template should be used in a new, empty project, with a `gitlab-ci.yml` file containing: +This template should be used in a new, empty project, with a `.gitlab-ci.yml` file containing: ```yaml include: diff --git a/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png Binary files differnew file mode 100644 index 00000000000..b21d0330b2f --- /dev/null +++ b/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png diff --git a/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png Binary files differnew file mode 100644 index 00000000000..31d5eb57228 --- /dev/null +++ b/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png diff --git a/doc/user/application_security/policies/img/policies_list_v14_3.png b/doc/user/application_security/policies/img/policies_list_v14_3.png Binary files differnew file mode 100644 index 00000000000..7a24860d4a7 --- /dev/null +++ b/doc/user/application_security/policies/img/policies_list_v14_3.png diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png Binary files differnew file mode 100644 index 00000000000..d04905eda59 --- /dev/null +++ b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png diff --git a/doc/user/application_security/policies/img/security_policy_project_v14_3.png b/doc/user/application_security/policies/img/security_policy_project_v14_3.png Binary files differnew file mode 100644 index 00000000000..5e3aefaeb81 --- /dev/null +++ b/doc/user/application_security/policies/img/security_policy_project_v14_3.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 3d0135678b7..bd143d8608a 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -4,57 +4,189 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Scan Policies **(ULTIMATE)** +# Policies **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. -> - Deployed behind a feature flag, disabled by default. -> - Disabled on GitLab.com. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. Deployed behind a feature flag, disabled by default. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.3. -Scan Policies in GitLab provide security teams a way to require scans of their choice to be run +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the `security_orchestration_policies_configuration` flag](../../../administration/feature_flags.md). +On GitLab.com, this feature is available. + +Policies in GitLab provide security teams a way to require scans of their choice to be run whenever a project pipeline runs according to the configuration specified. Security teams can therefore be confident that the scans they set up have not been changed, altered, or disabled. You -can access these by navigating to your project's **Security & Compliance > Scan Policies** page. +can access these by navigating to your project's **Security & Compliance > Policies** page. GitLab supports the following security policies: +- [Container Network Policy](#container-network-policy) - [Scan Execution Policy](#scan-execution-policy-schema) -WARNING: -Scan Policies is under development and is not ready for production use. It's deployed behind a -feature flag that's disabled by default. +## Policy management -NOTE: -We recommend using the [Security Policies project](#security-policies-project) -exclusively for managing policies for the project. Do not add your application's source code to such -projects. +The Policies page displays deployed +policies for all available environments. You can check a +policy's information (for example description, enforcement +status, etc.), and create and edit deployed policies: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. + + + +Network policies are fetched directly from the selected environment's +deployment platform while other policies are fetched from the project's +security policy project. Changes performed outside of this tab are +reflected upon refresh. + +By default, the policy list contains predefined network policies in a +disabled state. Once enabled, a predefined policy deploys to the +selected environment's deployment platform and you can manage it like +the regular policies. + +Note that if you're using [Auto DevOps](../../../topics/autodevops/index.md) +and change a policy in this section, your `auto-deploy-values.yaml` file doesn't update. Auto DevOps +users must make changes by following the +[Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). + +## Policy editor + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. + +You can use the policy editor to create, edit, and delete policies: + +1. On the top bar, select **Menu > Projects** and find your group. +1. On the left sidebar, select **Security & Compliance > Policies**. + - To create a new policy, select **New policy** which is located in the **Policies** page's header. + - To edit an existing policy, select **Edit policy** in the selected policy drawer. + +The policy editor has two modes: + +- The visual _Rule_ mode allows you to construct and preview policy + rules using rule blocks and related controls. + +  + +- YAML mode allows you to enter a policy definition in `.yaml` format + and is aimed at expert users and cases that the Rule mode doesn't + support. + +  + +You can use both modes interchangeably and switch between them at any +time. If a YAML resource is incorrect or contains data not supported +by the Rule mode, Rule mode is automatically +disabled. If the YAML is incorrect, you must use YAML +mode to fix your policy before Rule mode is available again. -## Enable or disable scan policies +## Container Network Policy -Scan Policies is under development and is not ready for production use. It's deployed behind a -feature flag that's disabled by default. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it for your instance. Scan Policies can be enabled or disabled per-project. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -To enable it: +The **Container Network Policy** section provides packet flow metrics for +your application's Kubernetes namespace. This section has the following +prerequisites: -```ruby -# Instance-wide -Feature.enable(:security_orchestration_policies_configuration) -# or by project -Feature.enable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +- Your project contains at least one [environment](../../../ci/environments/index.md). +- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). +- You've configured the [Prometheus service](../../project/integrations/prometheus.md#enabling-prometheus-integration). + +If you're using custom Helm values for Cilium, you must enable Hubble +with flow metrics for each namespace by adding the following lines to +your [Cilium values](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium): + +```yaml +hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' ``` -To disable it: +The **Container Network Policy** section displays the following information +about your packet flow: + +- The total amount of the inbound and outbound packets +- The proportion of packets dropped according to the configured + policies +- The per-second average rate of the forwarded and dropped packets + accumulated over time window for the requested time interval -```ruby -# Instance-wide -Feature.disable(:security_orchestration_policies_configuration) -# or by project -Feature.disable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +If a significant percentage of packets is dropped, you should +investigate it for potential threats by +examining the Cilium logs: + +```shell +kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor ``` +### Change the enforcement status + +To change a network policy's enforcement status: + +- Select the network policy you want to update. +- Select **Edit policy**. +- Select the **Policy status** toggle to update the selected policy. +- Select **Save changes** to deploy network policy changes. + +Disabled network policies have the `network-policy.gitlab.com/disabled_by: gitlab` selector inside +the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect +any pods. The policy itself is still deployed to the corresponding deployment namespace. + +### Container Network Policy editor + +The policy editor only supports the [CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/) +specification. Regular Kubernetes [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) +resources aren't supported. + +Rule mode supports the following rule types: + +- [Labels](https://docs.cilium.io/en/v1.8/policy/language/#labels-based). +- [Entities](https://docs.cilium.io/en/v1.8/policy/language/#entities-based). +- [IP/CIDR](https://docs.cilium.io/en/v1.8/policy/language/#ip-cidr-based). Only + the `toCIDR` block without `except` is supported. +- [DNS](https://docs.cilium.io/en/v1.8/policy/language/#dns-based). +- [Level 4](https://docs.cilium.io/en/v1.8/policy/language/#layer-4-examples) + can be added to all other rules. + +Once your policy is complete, save it by selecting **Save policy** +at the bottom of the editor. Existing policies can also be +removed from the editor interface by selecting **Delete policy** +at the bottom of the editor. + +### Configure a Network Policy Alert + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. + +You can use policy alerts to track your policy's impact. Alerts are only available if you've +[installed](../../clusters/agent/repository.md) +and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) +a Kubernetes Agent for this project. + +There are two ways to create policy alerts: + +- In the [policy editor UI](#container-network-policy-editor), + by clicking **Add alert**. +- In the policy editor's YAML mode, through the `metadata.annotations` property: + + ```yaml + metadata: + annotations: + app.gitlab.com/alert: 'true' + ``` + +Once added, the UI updates and displays a warning about the dangers of too many alerts. + ## Security Policies project +NOTE: +We recommend using the [Security Policies project](#security-policies-project) +exclusively for managing policies for the project. Do not add your application's source code to such +projects. + The Security Policies feature is a repository to store policies. All security policies are stored as the `.gitlab/security-policies/policy.yml` YAML file with this format: @@ -85,6 +217,40 @@ scan_execution_policy: site_profile: Site Profile D ``` +## Security Policy project selection + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +When the Security Policy project is created and policies are created within that repository, you +must create an association between that project and the project you want to apply policies to: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. +1. Select **Edit Policy Project**, and search for and select the + project you would like to link from the dropdown menu. +1. Select **Save**. + +  + +### Scan Execution Policy editor + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +Once your policy is complete, save it by selecting **Create merge request** +at the bottom of the editor. You will be redirected to the merge request on the project's +configured security policy project. If one does not link to your project, a security +policy project will be automatically created. Existing policies can also be +removed from the editor interface by selecting **Delete policy** +at the bottom of the editor. + + + +The policy editor currently only supports the YAML mode. The Rule mode is tracked in the [Allow Users to Edit Rule-mode Scan Execution Policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363) epic. + ### Scan Execution Policies Schema The YAML file with Scan Execution Policies consists of an array of objects matching Scan Execution Policy Schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 policies under the `scan_execution_policy` key. @@ -121,6 +287,16 @@ This rule enforces the defined actions and schedules a scan on the provided date | `type` | `string` | `schedule` | The rule's type. | | `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | +| `clusters` | `object` | | The cluster where the given policy will enforce running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that will be scanned. | + +#### `cluster` schema + +| Field | Type | Possible values | Description | +|--------------|---------------------|--------------------------|-------------| +| `containers` | `array` of `string` | | The container name that will be scanned (only the first value is currently supported). | +| `resources` | `array` of `string` | | The resource name that will be scanned (only the first value is currently supported). | +| `namespaces` | `array` of `string` | | The namespace that will be scanned (only the first value is currently supported). | +| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | ### `scan` action type @@ -149,6 +325,9 @@ Note the following: - A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in [`historic`](../secret_detection/index.md#full-history-secret-scan) mode when executed as part of a scheduled scan. +- A container scanning and cluster image scanning scans configured for the `pipeline` rule type will ignore the cluster defined in the `clusters` object. + They will use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. + Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). Here's an example: @@ -179,8 +358,8 @@ scan_execution_policy: scanner_profile: Scanner Profile C site_profile: Site Profile D - scan: secret_detection -- name: Enforce Secret Detection in every default branch pipeline - description: This policy enforces pipeline configuration to have a job with Secret Detection scan for the default branch +- name: Enforce Secret Detection and Container Scanning in every default branch pipeline + description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch enabled: true rules: - type: pipeline @@ -188,6 +367,25 @@ scan_execution_policy: - main actions: - scan: secret_detection + - scan: container_scanning +- name: Enforce Cluster Image Scanning on production-cluster every 24h + description: This policy enforces Cluster Image Scanning scan to run every 24 hours + enabled: true + rules: + - type: schedule + cadence: '15 3 * * *' + clusters: + production-cluster: + containers: + - database + resources: + - production-application + namespaces: + - production-namespace + kinds: + - deployment + actions: + - scan: cluster_image_scanning ``` In this example: @@ -196,22 +394,9 @@ In this example: `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. - DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` and `Site Profile D`. -- Secret detection scans run for every pipeline executed on the `main` branch. - -## Security Policy project selection - -When the Security Policy project is created and policies are created within that repository, you -must create an association between that project and the project you want to apply policies to. To do -this, navigate to your project's **Security & Compliance > Policies**, select -**Security policy project** from the dropdown menu, then select the **Create policy** button to save -changes. - -You can always change the **Security policy project** by navigating to your project's -**Security & Compliance > Policies** and modifying the selected project. - -NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select Security Policy Project. +- Secret detection and container scanning scans run for every pipeline executed on the `main` branch. +- Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities + from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. ## Roadmap diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 661a4ee8e82..d399dcaf4a9 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -65,8 +65,8 @@ Any custom change to the official analyzers can be achieved by using a You can switch to a custom Docker registry that provides the official analyzer images under a different prefix. For instance, the following instructs -SAST to pull `my-docker-registry/gl-images/bandit` -instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/bandit`. +SAST to pull `my-docker-registry/gl-images/sast/bandit` +instead of `registry.gitlab.com/security-products/sast/bandit`. In `.gitlab-ci.yml` define: ```yaml diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 6e88f38d900..3caa1771a5b 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -361,6 +361,9 @@ To create a custom ruleset: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292686) in GitLab 14.2. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the `vulnerability_flags` flag](../../../administration/feature_flags.md). On GitLab.com, this feature is available. + Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. ### Using CI/CD variables to pass credentials for private repositories @@ -669,19 +672,19 @@ import the following default SAST analyzer images from `registry.gitlab.com` int [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/bandit:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/brakeman:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/eslint:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/flawfinder:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/gosec:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/kubesec:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2 +registry.gitlab.com/security-products/sast/bandit:2 +registry.gitlab.com/security-products/sast/brakeman:2 +registry.gitlab.com/security-products/sast/eslint:2 +registry.gitlab.com/security-products/sast/flawfinder:2 +registry.gitlab.com/security-products/sast/gosec:3 +registry.gitlab.com/security-products/sast/kubesec:2 +registry.gitlab.com/security-products/sast/nodejs-scan:2 +registry.gitlab.com/security-products/sast/phpcs-security-audit:2 +registry.gitlab.com/security-products/sast/pmd-apex:2 +registry.gitlab.com/security-products/sast/security-code-scan:2 +registry.gitlab.com/security-products/sast/semgrep:2 +registry.gitlab.com/security-products/sast/sobelow:2 +registry.gitlab.com/security-products/sast/spotbugs:2 ``` The process for importing Docker images into a local offline Docker registry depends on diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index b6ff68c861b..cd1014d36a6 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -35,7 +35,7 @@ GitLab displays identified secrets visibly in a few places: Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). -The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes the following key types: +The [default ruleset provided by TruffleHog and Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes the following key types: - Cloud services: - Amazon Web Services (AWS) @@ -89,12 +89,13 @@ However not all features are available on every tier. See the breakdown below fo Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | +| Capability | In Free & Premium | In Ultimate | |:----------------------------------------------------------------|:--------------------|:-------------------| | [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | | Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -330,7 +331,7 @@ Import the following default Secret Detection analyzer images from `registry.git [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3 +registry.gitlab.com/security-products/secret-detection:3 ``` The process for importing Docker images into a local offline Docker registry depends on diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png Binary files differindex 3a195a5ce8d..52249cef343 100644 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index b799177ec5a..c78179e9693 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -46,7 +46,7 @@ The security dashboard and vulnerability report displays information about vulne ## Pipeline Security -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3. At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline ran against. @@ -64,7 +64,7 @@ the analyzer outputs an ### Scan details -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. The **Scan details** section lists the scans run in the pipeline and the total number of vulnerabilities per scan. For the DAST scan, select **Download scanned resources** to download a @@ -104,7 +104,7 @@ To download an SVG image of the chart, select **Save chart to an image** (**{dow ## Group Security Dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in GitLab 11.5. The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** @@ -139,7 +139,7 @@ Navigate to the group's [vulnerability report](../vulnerability_report/index.md) ## Security Center -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in GitLab 13.4. The Security Center is personal space where you manage vulnerabilities across all your projects. It displays the vulnerabilities present in the default branches of all the projects you configure. It includes @@ -166,22 +166,17 @@ To add projects to the Security Center: After you add projects, the security dashboard and vulnerability report display the vulnerabilities found in those projects' default branches. -## Keeping the dashboards up to date +## Keep dashboards up to date -The Security Dashboard displays information from the results of the most recent -security scan on the [default branch](../../project/repository/branches/default.md), -which means that security scans are performed every time the branch is updated. - -If the default branch is updated infrequently, scans are run infrequently and the -information on the Security Dashboard can become outdated as new vulnerabilities -are discovered. +The Security Dashboard displays results of the most recent security scan on the +[default branch](../../project/repository/branches/default.md). By default, security scans are run +only when the default branch is updated. Information on the Security Dashboard may not reflect +newly-discovered vulnerabilities. To ensure the information on the Security Dashboard is regularly updated, -[configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a -daily security scan. This updates the information displayed on the Security -Dashboard regardless of how often the default branch is updated. - -That way, reports are created even if no code change happens. +[configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a daily security scan. +This updates the information displayed on the Security Dashboard regardless of how often the default +branch is updated. WARNING: Running Dependency Scanning from a scheduled pipeline might result in false negatives if your @@ -191,12 +186,6 @@ can occur because the dependency version resolved during the scan might differ f resolved when your project was built and released, in a previous pipeline. Java projects can't have lock files. Python projects can have lock files, but GitLab Secure tools don't support them. -## Security scans using Auto DevOps - -When using [Auto DevOps](../../../topics/autodevops/index.md), use -[special environment variables](../../../topics/autodevops/customize.md#cicd-variables) -to configure daily security scans. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index c96497e9233..8277c30b81f 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -38,6 +38,12 @@ The different places in an application that are vulnerable to attack. Secure pro search the attack surface during scans. Each product defines the attack surface differently. For example, SAST uses files and line numbers, and DAST uses URLs. +### Corpus + +The set of meaningful test cases that are generated while the fuzzer is running. Each meaningful +test case produces new coverage in the tested program. It's advised to re-use the corpus and pass it +to subsequent runs. + ### CVE Common Vulnerabilities and Exposures (CVE®) is a list of common identifiers for publicly known @@ -142,6 +148,12 @@ A standard report format that Secure products comply with when creating JSON rep Provides an overview of all the vulnerabilities for a project, group, or GitLab instance. Vulnerabilities are only created from findings discovered on the project's default branch. +### Seed corpus + +The set of test cases given as initial input to the fuzz target. This usually speeds up the fuzz +target substantially. This can be either manually created test cases or auto-generated with the fuzz +target itself from previous runs. + ### Vendor The party maintaining an analyzer. As such, a vendor is responsible for integrating a scanner into diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png Binary files differdeleted file mode 100644 index e165c7e6ceb..00000000000 --- a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png +++ /dev/null diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png Binary files differnew file mode 100644 index 00000000000..a11a7fafc4a --- /dev/null +++ b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 8cecb9c5929..79f202a6edb 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -The **Threat Monitoring** page provides metrics and policy management +The **Threat Monitoring** page provides alerts and metrics for the GitLab application runtime security features. You can access these by navigating to your project's **Security & Compliance > Threat Monitoring** page. @@ -18,153 +18,7 @@ GitLab supports statistics for the following security features: - [Container Network Policies](../../../topics/autodevops/stages.md#network-policy) -## Container Network Policy - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -The **Container Network Policy** section provides packet flow metrics for -your application's Kubernetes namespace. This section has the following -prerequisites: - -- Your project contains at least one [environment](../../../ci/environments/index.md) -- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium) -- You've configured the [Prometheus service](../../project/integrations/prometheus.md#enabling-prometheus-integration) - -If you're using custom Helm values for Cilium, you must enable Hubble -with flow metrics for each namespace by adding the following lines to -your [Cilium values](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium): - -```yaml -hubble: - enabled: true - metrics: - enabled: - - 'flow:sourceContext=namespace;destinationContext=namespace' -``` - -The **Container Network Policy** section displays the following information -about your packet flow: - -- The total amount of the inbound and outbound packets -- The proportion of packets dropped according to the configured - policies -- The per-second average rate of the forwarded and dropped packets - accumulated over time window for the requested time interval - -If a significant percentage of packets is dropped, you should -investigate it for potential threats by -examining the Cilium logs: - -```shell -kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor -``` - -## Container Network Policy management - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3328) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. - -The **Threat Monitoring** page's **Policy** tab displays deployed -network policies for all available environments. You can check a -network policy's `yaml` manifest, its enforcement -status, and create and edit deployed policies. This section has the -following prerequisites: - -- Your project contains at least one [environment](../../../ci/environments/index.md) -- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium) - -Network policies are fetched directly from the selected environment's -deployment platform. Changes performed outside of this tab are -reflected upon refresh. - -By default, the network policy list contains predefined policies in a -disabled state. Once enabled, a predefined policy deploys to the -selected environment's deployment platform and you can manage it like -the regular policies. - -Note that if you're using [Auto DevOps](../../../topics/autodevops/index.md) -and change a policy in this section, your `auto-deploy-values.yaml` file doesn't update. Auto DevOps -users must make changes by following the -[Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). - -### Changing enforcement status - -To change a network policy's enforcement status: - -- Click the network policy you want to update. -- Click the **Edit policy** button. -- Click the **Policy status** toggle to update the selected policy. -- Click the **Save changes** button to deploy network policy changes. - -Disabled network policies have the `network-policy.gitlab.com/disabled_by: gitlab` selector inside -the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect -any pods. The policy itself is still deployed to the corresponding deployment namespace. - -### Container Network Policy editor - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. - -You can use the policy editor to create, edit, and delete policies. - -- To create a new policy, click the **New policy** button located in the **Policy** tab's header. -- To edit an existing policy, click **Edit policy** in the selected policy drawer. - -The policy editor only supports the [CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/) -specification. Regular Kubernetes [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) -resources aren't supported. - -The policy editor has two modes: - -- The visual _Rule_ mode allows you to construct and preview policy - rules using rule blocks and related controls. -- YAML mode allows you to enter a policy definition in `.yaml` format - and is aimed at expert users and cases that the Rule mode doesn't - support. - -You can use both modes interchangeably and switch between them at any -time. If a YAML resource is incorrect, Rule mode is automatically -disabled. You must use YAML mode to fix your policy before Rule mode -is available again. - -Rule mode supports the following rule types: - -- [Labels](https://docs.cilium.io/en/v1.8/policy/language/#labels-based). -- [Entities](https://docs.cilium.io/en/v1.8/policy/language/#entities-based). -- [IP/CIDR](https://docs.cilium.io/en/v1.8/policy/language/#ip-cidr-based). Only - the `toCIDR` block without `except` is supported. -- [DNS](https://docs.cilium.io/en/v1.8/policy/language/#dns-based). -- [Level 4](https://docs.cilium.io/en/v1.8/policy/language/#layer-4-examples) - can be added to all other rules. - -Once your policy is complete, save it by pressing the **Save policy** -button at the bottom of the editor. Existing policies can also be -removed from the editor interface by clicking the **Delete policy** -button at the bottom of the editor. - -### Configuring Network Policy Alerts - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. -> - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. - -You can use policy alerts to track your policy's impact. Alerts are only available if you've -[installed](../../clusters/agent/repository.md) -and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) -a Kubernetes Agent for this project. - -There are two ways to create policy alerts: - -- In the [policy editor UI](#container-network-policy-editor), - by clicking **Add alert**. -- In the policy editor's YAML mode, through the `metadata.annotations` property: - - ```yaml - metadata: - annotations: - app.gitlab.com/alert: 'true' - ``` - -Once added, the UI updates and displays a warning about the dangers of too many alerts. - -### Container Network Policy Alert list +## Container Network Policy Alert list > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. @@ -184,7 +38,7 @@ the selector menu in the **Status** column to set the status for each alert: By default, the list doesn't display resolved or dismissed alerts. - + Clicking an alert's row opens the alert drawer, which shows more information about the alert. A user can also create an incident from the alert and update the alert status in the alert drawer. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index a727dc88ffc..9ebecc67704 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -37,7 +37,9 @@ A vulnerability's status can be one of the following: | Detected | The default state for a newly discovered vulnerability. | | Confirmed | A user has seen this vulnerability and confirmed it to be accurate. | | Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. | -| Resolved | The vulnerability has been fixed and is no longer valid. | +| Resolved | The vulnerability has been fixed or is no longer present. | + +Dismissed vulnerabilities are ignored if detected in subsequent scans. Resolved vulnerabilities that are reintroduced and detected by subsequent scans have a _new_ vulnerability record created. When an existing vulnerability is no longer detected in a project's `default` branch, you should change its status to Resolved. This ensures that if it is accidentally reintroduced in a future merge, it will be visible again as a new record. You can use the [Activity filter](../vulnerability_report/#activity-filter) to select all vulnerabilities that are no longer detected, and [change their status](../vulnerability_report#change-status-of-multiple-vulnerabilities). ## Change vulnerability status diff --git a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png Binary files differindex 193efe9c386..44c689eda3e 100644 --- a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png +++ b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png Binary files differindex 056e051363d..a43340544ca 100644 --- a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index c2c2e7459ba..8b811c62ec3 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -145,6 +145,17 @@ To change the status of vulnerabilities in the table:  +### Change status of multiple vulnerabilities + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. + +You can change the status of multiple vulnerabilities at once: + +1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to update. + To select all, select the checkbox in the table header. +1. Above the table, select a new status. +1. Click **Change status** to save. + ## Export vulnerability details > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in the Security Center (previously known as the Instance Security Dashboard) and project-level Vulnerability Report (previously known as the Project Security Dashboard) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. @@ -191,14 +202,3 @@ You can dismiss a vulnerability for the entire project: 1. Optional. Add a reason for the dismissal and select **Save comment**. To undo this action, select a different status from the same menu. - -### Dismiss multiple vulnerabilities - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -You can dismiss multiple vulnerabilities at once: - -1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to dismiss. - To select all, select the checkbox in the table header. -1. Above the table, select a dismissal reason. -1. Select **Dismiss Selected**. diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 09123fdd472..1ea5168f30c 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -4,40 +4,52 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# CI/CD Tunnel +# CI/CD Tunnel **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. -> - Pre-configured `KUBECONFIG` [added](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. +> - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. +> - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. Only CI/CD jobs set in the configuration project can access one of the configured agents. -Prerequisites: +## Prerequisites - A running [`kas` instance](index.md#set-up-the-kubernetes-agent-server). - A [configuration repository](index.md#define-a-configuration-repository) with an Agent config file installed (`.gitlab/agents/<agent-name>/config.yaml`). - An [Agent record](index.md#create-an-agent-record-in-gitlab). -- The agent is [installed in the cluster](index.md#install-the-agent-into-the-cluster). +- The Agent [installed in the cluster](index.md#install-the-agent-into-the-cluster). -If your project has one or more Agent records, a `KUBECONFIG` variable that is compatible with `kubectl` is provided to your CI/CD jobs. A separate context (`kubecontext`) is available for each configured Agent. By default, no context is selected. +## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD +If your project has access to one or more Agent records available, its CI/CD +jobs provide a `KUBECONFIG` variable compatible with `kubectl`. + +Also, each Agent has a separate context (`kubecontext`). By default, +there isn't any context selected. Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`. +To get the list of available contexts, run `kubectl config get-contexts`. + +## Example for a `kubectl` command using the CI/CD Tunnel -To access your cluster from a CI/CD job through the tunnel: +The following example shows a CI/CD job that runs a `kubectl` command using the CI/CD Tunnel. +You can run any Kubernetes-specific commands similarly, such as `kubectl`, `helm`, +`kpt`, and so on. To do so: -1. In your `.gitlab-ci.yml` select the context for the agent you wish to use: +1. Set your Agent's context in the first command with the format `<agent-configuration-project-path>:<agent-name>`. +1. Run Kubernetes commands. - ```yaml - deploy: - image: - name: bitnami/kubectl:latest - entrypoint: [""] - script: - - kubectl config use-context path/to/agent-configuration-project:your-agent-name - - kubectl get pods - ``` +For example: -1. Execute `kubectl` commands directly against your cluster with this CI/CD job you just created. +```yaml + deploy: + image: + name: bitnami/kubectl:latest + entrypoint: [""] + script: + - kubectl config use-context path/to/agent-configuration-project:your-agent-name + - kubectl get pods +``` diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index c59d2a1f61c..d2dc57c0849 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -20,7 +20,7 @@ tasks in a secure and cloud-native way. It enables: - Pull-based GitOps deployments. - [Inventory object](../../infrastructure/clusters/deploy/inventory_object.md) to keep track of objects applied to your cluster. - Real-time access to API endpoints in a cluster. -- Alert generation based on [Container network policy](../../application_security/threat_monitoring/index.md#container-network-policy). +- Alert generation based on [Container network policy](../../application_security/policies/index.md#container-network-policy). - [CI/CD Tunnel](ci_cd_tunnel.md) that enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) @@ -77,6 +77,8 @@ The setup process involves a few steps to enable GitOps deployments: 1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). 1. [Create manifest files](#create-manifest-files). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. + ### Upgrades and version compatibility As the GitLab Kubernetes Agent is a new product, we are constantly adding new features @@ -104,7 +106,8 @@ To use the KAS: ### Define a configuration repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. +> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. To configure an Agent, you need: @@ -123,6 +126,7 @@ In your repository, add the Agent configuration file under: Your `config.yaml` file specifies all configurations of the Agent, such as: - The manifest projects to synchronize. +- The groups that can access this Agent via the [CI/CD Tunnel](ci_cd_tunnel.md). - The address of the `hubble-relay` for the Network Security policy integrations. As an example, a minimal Agent configuration that sets up only the manifest @@ -174,17 +178,14 @@ To perform a one-liner installation, run the command below. Make sure to replace - `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). - `gitlab-kubernetes-agent` with the namespace you defined in the previous step. - `wss://kas.gitlab.example.com` with the configured access of the Kubernetes Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. +- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. ```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version stable --namespace gitlab-kubernetes-agent | kubectl apply -f - +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f - ``` -Set `--agent-version` to the latest released patch version matching your -GitLab installation's major and minor versions. For example, if you have -GitLab v13.9.0, set `--agent-version=v13.9.1`. - WARNING: -Version `stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for +`--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for testing purposes but for production please make sure to specify a matching version explicitly. To find out the various options the above Docker container supports, run: @@ -287,7 +288,7 @@ spec: containers: - name: agent # Make sure to specify a matching version for production - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:stable" + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z args: - --token-file=/config/token - --kas-address @@ -383,29 +384,16 @@ Each time you push a change to a monitored manifest repository, the Agent logs t #### Example manifest file -This file creates an NGINX deployment. +This file creates a minimal `ConfigMap`: ```yaml -apiVersion: apps/v1 -kind: Deployment +apiVersion: v1 +kind: ConfigMap metadata: - name: nginx-deployment + name: demo-map namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. -spec: - selector: - matchLabels: - app: nginx - replicas: 2 - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.14.2 - ports: - - containerPort: 80 +data: + key: value ``` ## Example projects @@ -433,8 +421,8 @@ There are several components that work in concert for the Agent to generate the - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an existing installation. - One or more network policies through any of these options: - - Use the [Container Network Policy editor](../../application_security/threat_monitoring/index.md#container-network-policy-editor) to create and manage policies. - - Use an [AutoDevOps](../../application_security/threat_monitoring/index.md#container-network-policy-management) configuration. + - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies. + - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration. - Add the required labels and annotations to existing network policies. - A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index a3a3e4c29b0..ea57ded3320 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -9,6 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. +> - The `ci_access` attribute was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -147,6 +148,40 @@ gitops: - glob: '/**/*.yaml' ``` +## Authorize groups to use an Agent + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. + +If you use the same cluster across multiple projects, you can set up the CI/CD Tunnel +to grant the Agent access to one or more groups. This way, all the projects that belong +to the authorized groups can access the same Agent. This enables you to save resources and +have a scalable setup. + +When you authorize a group, the agent's Kubernetes context is automatically injected +into every project of the authorized group, and users can select the connection as +described in the [CI/CD Tunnel documentation](ci_cd_tunnel.md). +To authorize a group to access the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md), +use the `ci_access` attribute in your `config.yaml` configuration file. + +An Agent can only authorize groups in the same group hierarchy as the Agent's configuration project. At most +100 groups can be authorized per Agent. + +To authorize a group: + +1. Edit your `.config.yaml` file under the `.gitlab/agents/<agent name>` directory. +1. Add the `ci_access` attribute. +1. Add the `groups` attribute into `ci_access`. +1. Add the group `id` into `groups`, identifying the authorized group through its path. + +For example: + +```yaml +ci_access: + # This agent is accessible from CI jobs in projects in these groups + groups: + - id: group/subgroup +``` + ## Surface network security alerts from cluster to GitLab The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts). diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 5d247f04d3b..2da8396cfd7 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -285,10 +285,10 @@ postgresql: ``` Support for installing the Sentry managed application is provided by the -GitLab Health group. If you run into unknown issues, +GitLab Monitor group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Health group](https://about.gitlab.com/handbook/product/categories/#health-group). +[Monitor group](https://about.gitlab.com/handbook/product/categories/#monitor-group). ### Install PostHog using GitLab CI/CD @@ -366,9 +366,9 @@ project. Refer to the of the Prometheus chart's README for the available configuration options. Support for installing the Prometheus managed application is provided by the -GitLab APM group. If you run into unknown issues, +GitLab Monitor group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). +least 2 people from the [Monitor group](https://about.gitlab.com/handbook/product/categories/#monitor-group). ### Install GitLab Runner using GitLab CI/CD @@ -819,9 +819,9 @@ management project. Refer to the available configuration options. Support for installing the Elastic Stack managed application is provided by the -GitLab APM group. If you run into unknown issues, +GitLab Monitor group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). +least 2 people from the [Monitor group](https://about.gitlab.com/handbook/product/categories/#monitor-group). ### Install Crossplane using GitLab CI/CD diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index cb721115e76..cad55f0cf0b 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -36,7 +36,7 @@ In order to: [deploy to a Kubernetes cluster](../project/clusters/index.md#deploying-to-a-kubernetes-cluster) successfully. - Show pod usage correctly, you must - [enable Deploy Boards](../project/deploy_boards.md#enabling-deploy-boards). + [enable deploy boards](../project/deploy_boards.md#enabling-deploy-boards). After you have successful deployments to your group-level or instance-level cluster: diff --git a/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png b/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png Binary files differdeleted file mode 100644 index 5fd1bac5e05..00000000000 --- a/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png +++ /dev/null diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index 5e6843144fc..70f940c775b 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -33,9 +33,6 @@ You can integrate your Kubernetes cluster with [Prometheus](https://prometheus.io/) for monitoring key metrics of your apps directly from the GitLab UI. -[Alerts](../../operations/metrics/alerts.md) can be configured the same way as -for [external Prometheus instances](../../operations/metrics/alerts.md#external-prometheus-instances). - Once enabled, you can see metrics from services available in the [metrics library](../project/integrations/prometheus_library/index.md). diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 204afa9fc89..ca6843f6fde 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -32,28 +32,30 @@ Management projects are restricted to the following: group (or descendants) as the cluster's group. - For instance-level clusters, there are no such restrictions. -## Usage +## How to create and configure a cluster management project -To use a cluster management project for a cluster: +To use a cluster management project to manage your cluster: -1. Select the project. -1. Configure your pipelines. -1. Set an environment scope. +1. Create a new project to serve as the cluster management project +for your cluster. We recommend that you +[create this project based on the Cluster Management project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template). +1. [Associate the cluster with the management project](#associate-the-cluster-management-project-with-the-cluster). +1. [Configure your cluster's pipelines](#configuring-your-pipeline). +1. [Set the environment scope](#setting-the-environment-scope). -### Selecting a cluster management project +### Associate the cluster management project with the cluster -To select a cluster management project to use: +To associate a cluster management project with your cluster: 1. Navigate to the appropriate configuration page. For a: - [Project-level cluster](../project/clusters/index.md), go to your project's **Infrastructure > Kubernetes clusters** page. - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes** page. - - [Instance-level cluster](../instance/clusters/index.md), go to **Menu >** **{admin}** **Admin > Kubernetes** page. -1. Select the project using **Cluster management project field** in the **Advanced settings** - section. - - + - [Instance-level cluster](../instance/clusters/index.md), on the top bar, select **Menu > Admin > Kubernetes**. +1. Expand **Advanced settings**. +1. From the **Cluster management project** dropdown, select the cluster management project +you created in the previous step. ### Configuring your pipeline diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 1de17396bf4..9e2b00a0f54 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -4,35 +4,68 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster Management Project Template **(FREE)** +# Cluster Management project template **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0 with Helmfile support via Helm v3 instead, and a much more flexible usage of Helmfile. This introduces breaking changes that are detailed below. +> - Helm v2 support was [dropped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0. Use Helm v3 instead. -This [GitLab built-in project template](../project/working_with_projects.md#built-in-templates) -provides a quicker start for users interested in managing cluster -applications via [Helm v3](https://helm.sh/) charts. More specifically, taking advantage of the -[Helmfile](https://github.com/roboll/helmfile) utility client. The template consists of some pre-configured apps that -should help you get started quickly using various GitLab features. Still, you have all the flexibility to remove the ones you do not -need, or even add new ones that are not built-in. +With a [cluster management project](management_project.md) you can manage +your cluster's deployment and applications through a repository in GitLab. -## How to use this template +The Custer Management project template provides you a baseline to get +started and flexibility to customize your project to your cluster's needs. +For instance, you can: -1. Create a new project, choosing "GitLab Cluster Management" from the list of [built-in project templates](../project/working_with_projects.md#built-in-templates). -1. Make this project a [cluster management project](management_project.md). -1. If you used the [GitLab Managed Apps](applications.md), refer to - [Migrating from GitLab Managed Apps](migrating_from_gma_to_project_template.md). +- Extend the CI/CD configuration. +- Configure the built-in cluster applications. +- Remove the built-in cluster applications you don't need. +- Add other cluster applications using the same structure as the ones already available. -### Components +The template contains the following [components](#available-components): -In the repository of the newly-created project, you will find: +- A pre-configured GitLab CI/CD file so that you can configure deployment pipelines. +- A pre-configured [Helmfile](https://github.com/roboll/helmfile) so that +you can manage cluster applications with [Helm v3](https://helm.sh/). +- An `applications` directory with a `helmfile.yaml` configured for each +application available in the template. -- A predefined [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/.gitlab-ci.yml) - file, with a CI pipeline already configured. -- A main [`helmfile.yaml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/helmfile.yaml) to toggle which applications you would like to manage. -- An `applications` directory with a `helmfile.yaml` configured for each application GitLab provides. +WARNING: +If you used [GitLab Managed Apps](applications.md) to manage your +cluster from GitLab, see how to [migrate from GitLab Managed Apps](migrating_from_gma_to_project_template.md) to the Cluster Management +project. -#### The `.gitlab-ci.yml` file +## Set up the management project from the Cluster Management project template + +To set up your cluster's management project off of the Cluster Management project template: + +1. [Create a new project based on the Cluster Management template](#create-a-new-project-based-on-the-cluster-management-template). +1. [Associate the cluster management project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster). +1. Use the [available components](#available-components) to manage your cluster. + +### Create a new project based on the Cluster Management template + +To get started, create a new project based on the Cluster Management +project template to use as a cluster management project. + +You can either create the [new project](../project/working_with_projects.md#create-a-project) +from the template or import the project from the URL. Importing +the project is useful if you are using a GitLab self-managed +instance that may not have the latest version of the template. + +To create the new project: + +- From the template: select the **GitLab Cluster Management** project template. +- Importing from the URL: use `https://gitlab.com/gitlab-org/project-templates/cluster-management.git`. + +## Available components + +Use the available components to configure your cluster: + +- [A `.gitlab-ci.yml` file](#the-gitlab-ciyml-file). +- [A main `helmfile.yml` file](#the-main-helmfileyml-file). +- [A directory with built-in applications](#built-in-applications). + +### The `.gitlab-ci.yml` file The base image used in your pipeline is built by the [cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications) project. This image consists of a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts): @@ -48,23 +81,21 @@ project. This image consists of a set of Bash utility scripts to support [Helm v facilitate the GitLab Managed Apps adoption. - `gl-helmfile {arguments}`: A thin wrapper that triggers the [Helmfile](https://github.com/roboll/helmfile) command. -#### The main `helmfile.yml` file +### The main `helmfile.yml` file This file has a list of paths to other Helmfiles for each app. They're all commented out by default, so you must uncomment -the paths for the apps that you would like to manage. +the paths for the apps that you would like to use in your cluster. -By default, each `helmfile.yaml` in these sub-paths have the attribute `installed: true`. This signifies that every time +By default, each `helmfile.yaml` in these sub-paths has the attribute `installed: true`. This means that every time the pipeline runs, Helmfile tries to either install or update your apps according to the current state of your cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile tries try to uninstall this app from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works. -Furthermore, each app has an `applications/{app}/values.yaml` file. This is the -place where you can define some default values for your app's Helm chart. Some apps already have defaults +Furthermore, each app has an `applications/{app}/values.yaml` file (`applicaton/{app}/values.yaml.gotmpl` in case of GitLab Runner). This is the +place where you can define default values for your app's Helm chart. Some apps already have defaults pre-defined by GitLab. -#### Built-in applications - -The built-in applications are intended to provide an easy way to get started with various Kubernetes oriented GitLab features. +### Built-in applications The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are: @@ -79,8 +110,3 @@ The [built-in supported applications](https://gitlab.com/gitlab-org/project-temp - [Prometheus](../infrastructure/clusters/manage/management_project_applications/prometheus.md) - [Sentry](../infrastructure/clusters/manage/management_project_applications/sentry.md) - [Vault](../infrastructure/clusters/manage/management_project_applications/vault.md) - -### Migrate from GitLab Managed Apps - -If you had GitLab Managed Apps, either One-Click or CI/CD install, read the docs on how to -[migrate from GitLab Managed Apps to project template](migrating_from_gma_to_project_template.md) diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index dc16cf5cc45..2da058fb5bc 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -4,13 +4,24 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from GitLab Managed Apps to a management project template +# Migrate from GitLab Managed Apps to Cluster Management Projects -The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To migrate to the new way of managing them: +The [GitLab Managed Apps](applications.md) were deprecated in GitLab 14.0 +in favor of [Cluster Management Projects](management_project.md). +Managing your cluster applications through a project enables you a +lot more flexibility to manage your cluster than through the late GitLab Managed Apps. +To migrate to the cluster management project you need +[GitLab Runners](../../ci/runners/index.md) +available and be familiar with [Helm](https://helm.sh/). -1. Read how the [management project template](management_project_template.md) works, and - create a new project based on the "GitLab Cluster Management" template. -1. Create a new project as explained in the [management project template](management_project_template.md). +## Migrate to a Cluster Management Project + +To migrate from GitLab Managed Apps to a Cluster Management Project, +follow the steps below. +See also [video walk-throughs](#video-walk-throughs) with examples. + +1. Create a new project based on the [Cluster Management Project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template). +1. [Associate your new Cluster Management Project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster). 1. Detect apps deployed through Helm v2 releases by using the pre-configured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml-file) file: - In case you had overwritten the default GitLab Managed Apps namespace, edit `.gitlab-ci.yml`, and make sure the script is receiving the correct namespace as an argument: @@ -80,6 +91,16 @@ The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To mig used in Helm v3. So, the only way to integrate it with this Cluster Management Project is to actually uninstall this app and accept the chart version proposed in `applications/vault/values.yaml`. + - Cert-manager: + - For users on Kubernetes version 1.20 or above, the deprecated cert-manager v0.10 is no longer valid and + and the upgrade includes a breaking change. So we suggest that you [backup and uninstall cert-manager v0.10](#backup-and-uninstall-cert-manager-v010) + , and install cert-manager v1.4 instead. To install this version, uncomment the `applications/cert-manager-1-4/helmfile.yaml` + from the [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file). + This triggers a pipeline to install the new version. + - For users on Kubernetes versions lower than 1.20, you can stick to v0.10 by uncommenting + `applications/cert-manager/helmfile.yaml` + in your project's main Helmfile ([`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file)). + 1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and watch the `apply` job logs to see if any of your applications were successfully detected, installed, and whether they got any unexpected updates. @@ -93,3 +114,21 @@ The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To mig After getting a successful pipeline, repeat these steps for any other deployed apps you want to manage with the Cluster Management Project. + +## Backup and uninstall cert-manager v0.10 + +1. Follow the [official docs](https://docs.cert-manager.io/en/release-0.10/tasks/backup-restore-crds.html) on how to + backup your cert-manager v0.10 data. +1. Uninstall cert-manager by editing the setting all the occurrences of `installed: true` to `installed: false` in the + `applications/cert-manager/helmfile.yaml` file. +1. Search for any left-over resources by executing the following command `kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges,Secrets,ConfigMaps -n gitlab-managed-apps | grep certmanager`. +1. For each of the resources found in the previous step, delete them with `kubectl delete -n gitlab-managed-apps {ResourceType} {ResourceName}`. + For example, if you found a resource of type `ConfigMap` named `cert-manager-controller`, delete it by executing: + `kubectl delete configmap -n gitlab-managed-apps cert-manager-controller`. + +## Video walk-throughs + +You can watch these videos with examples on how to migrate from GMA to a Cluster Management project: + +- [Migrating from scratch using a brand new cluster management project](https://youtu.be/jCUFGWT0jS0). Also covers Helm v2 apps migration. +- [Migrating from an existing GitLab managed apps CI/CD project](https://youtu.be/U2lbBGZjZmc). diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index c51636e33f5..d30cedfb3cd 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -14,17 +14,32 @@ Compliance report gives you the ability to see a group's merge request activity. high-level view for all projects in the group. For example, code approved for merging into production. -To access compliance report for a group, go to **{shield}** **Security & Compliance > Compliance** -on the group's menu. +You can use the report to: + +- Get an overview of the latest merge request for each project. +- See if merge requests were approved and by whom. +- See merge request authors. +- See the latest [CI/CD pipeline](../../../ci/pipelines/index.md) result for each merge request. + +## View the compliance report for a group + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +To view the compliance report: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Security & Compliance > Compliance**. NOTE: -Compliance report shows only the latest merge request on each project. +The compliance report shows only the latest merge request on each project. ## Merge request drawer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299357) in GitLab 14.1. -When you click on a row, a drawer is shown that provides further details about the merge +When you select a row, a drawer is shown that provides further details about the merge request: - Project name and [compliance framework label](../../project/settings/index.md#compliance-frameworks), @@ -36,22 +51,6 @@ request: - A list of users that approved the merge request. - The user that merged the merge request. -## Use cases - -This feature is for people who care about the compliance status of projects within their group. - -You can use the report to: - -- Get an overview of the latest merge request for each project. -- See if merge requests were approved and by whom. -- See merge request authors. -- See the latest [CI Pipeline](../../../ci/pipelines/index.md) result for each merge request. - -## Permissions - -- On [GitLab Ultimate](https://about.gitlab.com/pricing/) tier. -- By **Administrators** and **Group Owners**. - ## Approval status and separation of duties > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. @@ -85,14 +84,23 @@ The data provides a comprehensive view with respect to merge commits. It include merge request author, merge request ID, merge user, pipeline ID, group name, project name, and merge request approvers. Depending on the merge strategy, the merge commit SHA can be a merge commit, squash commit, or a diff head commit. -To download the Chain of Custody report, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu and click **List of all merge commits** +To download the Chain of Custody report: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Security & Compliance > Compliance**. +1. Select **List of all merge commits**. ### Commit-specific Chain of Custody Report **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. -You can generate a commit-specific Chain of Custody report for a given commit SHA. To do so, select -the dropdown next to the **List of all merge commits** button at the top of the compliance report. +You can generate a commit-specific Chain of Custody report for a given commit SHA. + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Security & Compliance > Compliance**. +1. At the top of the compliance report, to the right of **List of all merge commits**, select the down arrow (**{angle-down}**). +1. Enter the merge commit SHA, and then select **Export commit custody report**. + SHA and then select **Export commit custody report**. NOTE: The Chain of Custody report download is a CSV file, with a maximum size of 15 MB. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index e39a3f7111b..165150a58a1 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -40,7 +40,7 @@ compliance report is shown properly.  -You can click on a license to see more information. +You can select a license to see more information. When GitLab detects a **Denied** license, you can view it in the [license list](#license-list). @@ -49,11 +49,20 @@ When GitLab detects a **Denied** license, you can view it in the [license list]( You can view and modify existing policies from the [policies](#policies) tab.  +## License expressions + +GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/). +License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, +if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](#policies), +GitLab evaluates the composite license as _denied_, as this is the safer option. +The ability to support other license expression operators (like `OR`, `WITH`) is tracked +in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6571). + ## Supported languages and package managers The following languages and package managers are supported. -Java 8 and Gradle 1.x projects are not supported. The minimum supported version of Maven is 3.2.5. +Gradle 1.x projects are not supported. The minimum supported version of Maven is 3.2.5. | Language | Package managers | Notes | |------------|----------------------------------------------------------------------------------------------|-------| @@ -140,12 +149,12 @@ License Compliance can be configured using CI/CD variables. | `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and npm projects). | | `ASDF_JAVA_VERSION` | no | Version of Java to use for the scan. | | `ASDF_NODEJS_VERSION` | no | Version of Node.js to use for the scan. | -| `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. | +| `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. [Configuration](#selecting-the-version-of-python) | | `ASDF_RUBY_VERSION` | no | Version of Ruby to use for the scan. | | `GRADLE_CLI_OPTS` | no | Additional arguments for the Gradle executable. If not supplied, defaults to `--exclude-task=test`. | | `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if you have multiple projects in nested directories, you can update your `.gitlab-ci-yml` template to specify a recursive scan, like `LICENSE_FINDER_CLI_OPTS: '--recursive'`. | -| `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. | -| `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | +| `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. [Configuration](#selecting-the-version-of-java) | +| `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. [Configuration](#selecting-the-version-of-python) | | `MAVEN_CLI_OPTS` | no | Additional arguments for the `mvn` executable. If not supplied, defaults to `-DskipTests`. | | `PIP_INDEX_URL` | no | Base URL of Python Package Index (default: `https://pypi.org/simple/`). | | `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | @@ -245,6 +254,12 @@ Alternatively, you can use a Java key store to verify the TLS connection. For in generate a key store file, see the [Maven Guide to Remote repository access through authenticated HTTPS](http://maven.apache.org/guides/mini/guide-repository-ssl.html). +### Selecting the version of Java + +License Compliance uses Java 8 by default. You can specify a different Java version using `LM_JAVA_VERSION`. + +`LM_JAVA_VERSION` only accepts versions: 8, 11, 14, 15. + ### Selecting the version of Python > - [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. @@ -264,6 +279,8 @@ license_scanning: LM_PYTHON_VERSION: 2 ``` +`LM_PYTHON_VERSION` or `ASDF_PYTHON_VERSION` can be used to specify the desired version of Python. When both variables are specified `LM_PYTHON_VERSION` takes precedence. + ### Custom root certificates for Python You can supply a custom root certificate to complete TLS verification by using the @@ -693,15 +710,16 @@ instance's administrator can manually update it with a [Rake task](../../../rake The License list allows you to see your project's licenses and key details about them. -In order for the licenses to appear under the license list, the following +For the licenses to appear under the license list, the following requirements must be met: 1. The License Compliance CI job must be [configured](#configuration) for your project. 1. Your project must use at least one of the [supported languages and package managers](#supported-languages-and-package-managers). -Once everything is set, navigate to **Security & Compliance > License Compliance** -in your project's sidebar, and the licenses are displayed, where: +When everything is configured, on the left sidebar, select **Security & Compliance > License Compliance**. + +The licenses are displayed, where: - **Name:** The name of the license. - **Component:** The components which have this license. @@ -741,8 +759,10 @@ license. You can enable `License-Check` one of two ways: -1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. -1. Click **Enable** or **Edit**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge request approvals**. +1. Select **Enable** or **Edit**. 1. Add or change the **Rule name** to `License-Check` (case sensitive).  @@ -802,11 +822,11 @@ or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-conf activate the appropriate version. For example, the following `.tool-versions` file activates version `12.16.3` of [Node.js](https://nodejs.org/) -and version `2.7.2` of [Ruby](https://www.ruby-lang.org/). +and version `2.7.4` of [Ruby](https://www.ruby-lang.org/). ```plaintext nodejs 12.16.3 -ruby 2.7.2 +ruby 2.7.4 ``` The next example shows how to activate the same versions of the tools mentioned above by using CI/CD variables defined in your @@ -819,7 +839,7 @@ include: license_scanning: variables: ASDF_NODEJS_VERSION: '12.16.3' - ASDF_RUBY_VERSION: '2.7.2' + ASDF_RUBY_VERSION: '2.7.4' ``` A full list of variables can be found in [CI/CD variables](#available-cicd-variables). diff --git a/doc/user/discussions/img/btn_new_issue_for_all_threads.png b/doc/user/discussions/img/btn_new_issue_for_all_threads.png Binary files differdeleted file mode 100644 index b07267a011a..00000000000 --- a/doc/user/discussions/img/btn_new_issue_for_all_threads.png +++ /dev/null diff --git a/doc/user/discussions/img/create-new-issue_v14_3.png b/doc/user/discussions/img/create-new-issue_v14_3.png Binary files differnew file mode 100644 index 00000000000..d76fed6cb42 --- /dev/null +++ b/doc/user/discussions/img/create-new-issue_v14_3.png diff --git a/doc/user/discussions/img/new-issue-one-thread_v14_3.png b/doc/user/discussions/img/new-issue-one-thread_v14_3.png Binary files differnew file mode 100644 index 00000000000..34d3a3be0a7 --- /dev/null +++ b/doc/user/discussions/img/new-issue-one-thread_v14_3.png diff --git a/doc/user/discussions/img/new_issue_for_thread.png b/doc/user/discussions/img/new_issue_for_thread.png Binary files differdeleted file mode 100644 index c7f0fd76844..00000000000 --- a/doc/user/discussions/img/new_issue_for_thread.png +++ /dev/null diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index a1d8863710c..aa4e3ce6f49 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -13,7 +13,7 @@ GitLab encourages communication through comments, threads, and There are two types of comments: - A standard comment. -- A comment in a thread, which has to be resolved. +- A comment in a thread, which can be [resolved](#resolve-a-thread). In a comment, you can enter [Markdown](../markdown.md) and use [quick actions](../project/quick_actions.md). @@ -46,9 +46,9 @@ To add a commit diff comment: 1. To select a specific commit, on the merge request, select the **Commits** tab, select the commit message. To view the latest commit, select the **Changes** tab. -1. By the line you want to comment on, hover over the line number and select **{comment}**. - You can select multiple lines by dragging the **{comment}** icon. -1. Type your comment and select **Start a review** or **Add comment now**. +1. By the line you want to comment on, hover over the line number and select **Comment** (**{comment}**). + You can select multiple lines by dragging the **Comment** (**{comment}**) icon. +1. Enter your comment and select **Start a review** or **Add comment now**. The comment is displayed on the merge request's **Discussions** tab. @@ -164,12 +164,10 @@ from any device you're logged into. You can assign an issue to a user who made a comment. -1. In the comment, select the **More Actions** menu. -1. Select **Assign to commenting user**. - - - -Select the button again to unassign the commenter. +1. In the comment, select the **More Actions** (**{ellipsis_v}**) menu. +1. Select **Assign to commenting user**: +  +1. To unassign the commenter, select the button again. ## Create a thread by replying to a standard comment @@ -184,13 +182,13 @@ Prerequisites: To create a thread by replying to a comment: -1. On the top right of the comment, select **{comment}** (**Reply to comment**). +1. On the top right of the comment, select **Reply to comment** (**{comment}**).  The reply area is displayed. -1. Type your reply. +1. Enter your reply. 1. Select **Comment** or **Add comment now** (depending on where in the UI you are replying). The top comment is converted to a thread. @@ -206,7 +204,7 @@ Prerequisites: To create a thread: -1. Type a comment. +1. Enter a comment. 1. Below the comment, to the right of the **Comment** button, select the down arrow (**{chevron-down}**). 1. From the list, select **Start thread**. 1. Select **Start thread** again. @@ -218,16 +216,16 @@ A threaded comment is created. ## Resolve a thread > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5022) in GitLab 8.11. -> - Resolvable threads can be added only to merge request diffs. > - Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. -You can resolve a thread when you want to finish a conversation. +In a merge request, you can resolve a thread when you want to finish a conversation. Prerequisites: - You must have at least the [Developer role](../permissions.md#project-members-permissions) or be the author of the change being reviewed. -- You must be in an issue, merge request, commit, or snippet. +- Resolvable threads can be added only to merge requests. It doesn't work + for comments in issues, commits, or snippets. To resolve a thread: @@ -237,33 +235,30 @@ To resolve a thread: - Below the last reply, in the **Reply** field, select **Resolve thread**. - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. -At the top of the page, the number of unresolved threads is updated. +At the top of the page, the number of unresolved threads is updated:  ### Move all unresolved threads in a merge request to an issue If you have multiple unresolved threads in a merge request, you can -create an issue to resolve them separately. +create an issue to resolve them separately. In the merge request, at the top of the page, +select **Create issue to resolve all threads** (**{issue-new}**): -- In the merge request, at the top of the page, select **Resolve all threads in new issue**. + -  - -All threads are marked as resolved and a link is added from the merge request to +All threads are marked as resolved, and a link is added from the merge request to the newly created issue. ### Move one unresolved thread in a merge request to an issue If you have one specific unresolved thread in a merge request, you can -create an issue to resolve it separately. - -- In the merge request, under the last reply to the thread, next to the - **Resolve thread** button, select **Resolve this thread in a new issue**. +create an issue to resolve it separately. In the merge request, under the last reply +to the thread, next to **Resolve thread**, select **Create issue to resolve thread** (**{issue-new}**): -  + -The thread is marked as resolved and a link is added from the merge request to +The thread is marked as resolved, and a link is added from the merge request to the newly created issue. ### Prevent merge unless all threads are resolved diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 024ab86a1b7..23765de8f46 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -9,6 +9,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w This page contains information about the settings that are used on GitLab.com, available to [GitLab SaaS](https://about.gitlab.com/pricing/) customers. +## Password requirements + +GitLab.com has the following requirements for passwords on new accounts and password changes: + +- Minimum character length 8 characters. +- Maximum character length 128 characters. +- All characters are accepted. For example, `~`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `()`, + `[]`, `_`, `+`, `=`, and `-`. + +## SSH key restrictions + +GitLab.com uses the default [SSH key restrictions](../../security/ssh_keys_restrictions.md). + ## SSH host keys fingerprints Below are the fingerprints for SSH host keys on GitLab.com. The first time you @@ -123,6 +136,7 @@ the related documentation. | [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited | | [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited | | [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | +| [Max pipelines per schedule](../../administration/instance_limits.md#limit-the-number-of-pipelines-created-by-a-pipeline-schedule-per-day) | `24` for Free tier, `288` for all paid tiers | Unlimited | | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | | Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | | [Max registered runners](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | `50` per-project and per-group for Free tier,<br/>`1_000` per-group for all paid tiers / `1_000` per-project for all paid tiers | `1_000` per-group / `1_000` per-project | @@ -292,7 +306,7 @@ endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). For information on rate limiting responses, see: - [List of headers on responses to blocked requests](../admin_area/settings/user_and_ip_rate_limits.md#response-headers). -- [Customizable response text](../admin_area/settings/user_and_ip_rate_limits.md#response-text). +- [Customizable response text](../admin_area/settings/user_and_ip_rate_limits.md#use-a-custom-rate-limit-response). ### Protected paths throttle @@ -349,7 +363,7 @@ doesn't return the following headers: ### Visibility settings If created before GitLab 12.2 (July 2019), these items have the -[Internal visibility](../../public_access/public_access.md#internal-projects) +[Internal visibility](../../public_access/public_access.md#internal-projects-and-groups) setting [disabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/12388): - Projects diff --git a/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png b/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png Binary files differindex 073e747153f..21e38907a10 100644 --- a/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png +++ b/doc/user/group/devops_adoption/img/group_devops_adoption_v14_2.png diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 5c84a343da9..554d01039ad 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -13,6 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. > - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. > - Multiselect [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. +> - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. Prerequisites: diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 34eebfb9e3b..d184030718a 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -4,7 +4,7 @@ group: Product Planning info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Epic Boards **(PREMIUM)** +# Epic boards **(PREMIUM)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.1. @@ -54,7 +54,7 @@ Prerequisites: To delete the active epic board: -1. Select the dropdown with the current board name in the upper left corner of the Epic Boards page. +1. Select the dropdown with the current board name in the upper left corner of the epic boards page. 1. Select **Delete board**. 1. Select **Delete**. diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 24c78d169c4..68df71d1c5d 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -64,7 +64,7 @@ You can also consult the [group permissions table](../../permissions.md#group-me ## Related topics - [Manage epics](manage_epics.md) and multi-level child epics. -- Create workflows with [Epic Boards](epic_boards.md). +- Create workflows with [epic boards](epic_boards.md). - [Turn on notifications](../../profile/notifications.md) for about epic events. - [Award an emoji](../../award_emojis.md) to an epic or its comments. - Collaborate on an epic by posting comments in a [thread](../../discussions/index.md). diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 721afa219d0..31c3a8e774e 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -77,7 +77,7 @@ Any other items are **not** migrated. ## Enable or disable GitLab Group Migration -GitLab Migration is deployed behind a feature flag that is **disabled by default**. +GitLab Migration is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it. To enable it: diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 948f9cab659..caf874cfe28 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -82,6 +82,10 @@ To create a group: - Underscores - Dashes and dots (it cannot start with dashes or end in a dot) 1. Choose the [visibility level](../../public_access/public_access.md). +1. Personalize your GitLab experience by answering the following questions: + - What is your role? + - Who will be using this group? + - What will you use this group for? 1. Invite GitLab members or other users to join the group. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -263,7 +267,7 @@ These Group Activity Analytics can be enabled with the `group_activity_analytics ### View group activity -You can view the most recent actions taken in a group. +You can view the most recent actions taken in a group, either in your browser or in an RSS feed: 1. On the top bar, select **Menu > Groups**. 1. Select **Your Groups**. @@ -312,7 +316,7 @@ In GitLab 13.11, you can optionally replace the sharing form with a modal window To share a group after enabling this feature: 1. Go to your group's page. -1. In the left sidebar, go to **Group information > Members**, and then select **Invite a group**. +1. On the left sidebar, go to **Group information > Members**, and then select **Invite a group**. 1. Select a group, and select a **Max role**. 1. (Optional) Select an **Access expiration date**. 1. Select **Invite**. @@ -664,16 +668,16 @@ Projects can be configured to be deleted either: - Immediately. - After a delayed interval. During this interval period, the projects are in a read-only state - and can be restored, if required. The default interval period is seven days but + and can be restored. The default interval period is seven days but [is configurable](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). -On: +On self-managed GitLab, projects are deleted immediately by default. +In GitLab 14.2 and later, an administrator can +[change the default setting](../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion) +for projects in newly-created groups. -- GitLab self-managed instances, projects are deleted immediately by default. In GitLab - 14.2 and later, an administrator can - [change the default setting](../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion) for projects in newly-created groups. -- GitLab.com, see [GitLab.com settings page](../gitlab_com/index.md#delayed-project-deletion) for - the default setting. +On GitLab.com, see the [GitLab.com settings page](../gitlab_com/index.md#delayed-project-deletion) for +the default setting. To enable delayed deletion of projects in a group: @@ -750,7 +754,7 @@ The group's new subgroups have push rules set for them based on either: - [Transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). - [Share a project with a group](../project/members/share_project_with_groups.md): Give all group members access to the project at once. - [Lock the sharing with group feature](#prevent-a-project-from-being-shared-with-groups). -- [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforcing-2fa-for-all-users-in-a-group): Enforce 2FA +- [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforce-2fa-for-all-users-in-a-group): Enforce 2FA for all group members. - Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/features.md).. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 9240828db0a..3d28ef5306d 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue Analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. Issue Analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 5c4e66a4539..70fa3ba639d 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -110,7 +110,17 @@ Prerequisites: - You must have at least the [Developer role](../../permissions.md) for a group. -To edit an iteration, select the three-dot menu (**{ellipsis_v}**) > **Edit iteration**. +To edit an iteration, select the three-dot menu (**{ellipsis_v}**) > **Edit**. + +## Delete an iteration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292268) in GitLab 14.3. + +Prerequisites: + +- You must have at least the [Developer role](../../permissions.md) for a group. + +To delete an iteration, select the three-dot menu (**{ellipsis_v}**) > **Delete**. ## Add an issue to an iteration diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 054c6ab7a6b..685c4601ac4 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -16,7 +16,7 @@ This feature might not be available to you. Check the **version history** note a ## Current group code coverage -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. The **Analytics > Repositories** group page displays the overall test coverage of all your projects in your group. In the **Overall activity** section, you can see: @@ -27,13 +27,13 @@ In the **Overall activity** section, you can see: ## Average group test coverage from the last 30 days -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215140) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215140) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.9. The **Analytics > Repositories** group page displays the average test coverage of all your projects in your group in a graph for the last 30 days. ## Latest project test coverage list -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. To see the latest code coverage for each project in your group: diff --git a/doc/user/group/roadmap/img/epics_state_dropdown_v12_10.png b/doc/user/group/roadmap/img/epics_state_dropdown_v12_10.png Binary files differdeleted file mode 100644 index c6d0b17455f..00000000000 --- a/doc/user/group/roadmap/img/epics_state_dropdown_v12_10.png +++ /dev/null diff --git a/doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png b/doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png Binary files differnew file mode 100644 index 00000000000..171876e34a9 --- /dev/null +++ b/doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png diff --git a/doc/user/group/roadmap/img/roadmap_view_v13_2.png b/doc/user/group/roadmap/img/roadmap_view_v13_2.png Binary files differdeleted file mode 100644 index 94cf2258569..00000000000 --- a/doc/user/group/roadmap/img/roadmap_view_v13_2.png +++ /dev/null diff --git a/doc/user/group/roadmap/img/roadmap_view_v14_3.png b/doc/user/group/roadmap/img/roadmap_view_v14_3.png Binary files differnew file mode 100644 index 00000000000..ca4b87b9fdd --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_view_v14_3.png diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 811297c6eda..656c40d1915 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -32,7 +32,7 @@ When you hover over a milestone bar or title, a popover appears with its title, date. You can also click the chevron (**{chevron-down}**) next to the **Milestones** heading to toggle the list of the milestone bars. - + ## Sort and filter the Roadmap @@ -52,7 +52,7 @@ filtering them by what's important for you. A dropdown menu lets you show only open or closed epics. By default, all epics are shown. - + You can sort epics in the Roadmap view by: @@ -101,18 +101,38 @@ Feature.disable(:async_filtering) > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. > - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198062), Timelines were moved to the Premium tier. -Roadmap supports the following date ranges: +### Date range presets -- Quarters -- Months (default) -- Weeks +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/204994) in GitLab 14.3. [Deployed behind the `roadmap_daterange_filter` flag](../../../administration/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/323917) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per group, +ask an administrator to [enable the `roadmap_daterange_filter` flag](../../../administration/feature_flags.md). +On GitLab.com, this feature is available. +The feature is ready for production use. + +Roadmap provides three date range options, each with predetermined timeline duration: + +- **This quarter**: includes weeks present in current quarter. +- **This year**: includes weeks or months present in current year. +- **Within 3 years**: includes weeks, months, or quarters present in the previous 18 months and + upcoming 18 months (that is, three years in total). + +### Layout presets + +Depending on selected [date range preset](#date-range-presets), Roadmap supports the following layout presets: + +- **Quarters**: only available when the "Within 3 years" date range is selected. +- **Months**: available when either "This year" or "Within 3 years" date range is selected. +- **Weeks** (default): available for all the date range presets. ### Quarters  In the **Quarters** preset, roadmap shows epics and milestones which have start or due dates -**falling within** or **going through** past quarter, current quarter, and the next four quarters, +**falling within** currently selected date range preset, where **today** is shown by the vertical red line in the timeline. The sub-headers underneath the quarter name on the timeline header represent the month of the quarter. @@ -123,7 +143,7 @@ the timeline header represent the month of the quarter. In the **Months** preset, roadmap shows epics and milestones which have start or due dates **falling within** or -**going through** the past month, current month, and the next five months, where **today** +**going through** currently selected date range preset, where **today** is shown by the vertical red line in the timeline. The sub-headers underneath the month name on the timeline header represent the date on starting day (Sunday) of the week. This preset is selected by default. @@ -133,7 +153,7 @@ selected by default.  In the **Weeks** preset, roadmap shows epics and milestones which have start or due dates **falling -within** or **going through** the past week, current week and the next four weeks, where **today** +within** or **going through** currently selected date range preset, where **today** is shown by the vertical red line in the timeline. The sub-headers underneath the week name on the timeline header represent the days of the week. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index a627f04fa46..8f6b3e7244a 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -57,6 +57,7 @@ Once users have signed into GitLab using the SSO SAML setup, changing the `NameI #### NameID Format We recommend setting the NameID format to `Persistent` unless using a field (such as email) that requires a different format. +Most NameID formats can be used, except `Transient` due to the temporary nature of this format. ### Assertions @@ -120,6 +121,14 @@ SSO has the following effects when enabled: - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). <!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> +When SSO is enforced, users are not immediately revoked. If the user: + +- Is signed out, they cannot access the group after being removed from the identity provider. +- Has an active session, they can continue accessing the group for up to 24 hours until the identity + provider session times out. + +When SCIM updates, the user's access is immediately revoked. + ## Providers The SAML standard means that a wide range of identity providers will work with GitLab. Your identity provider may have relevant documentation. It may be generic SAML documentation, or specifically targeted for GitLab. @@ -140,13 +149,13 @@ Follow the Azure documentation on [configuring single sign-on to applications](h For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). The video is outdated in regard to objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). -| GitLab Setting | Azure Field | -|--------------|----------------| -| Identifier | Identifier (Entity ID) | -| Assertion consumer service URL | Reply URL (Assertion Consumer Service URL) | -| GitLab single sign-on URL | Sign on URL | -| Identity provider single sign-on URL | Login URL | -| Certificate fingerprint | Thumbprint | +| GitLab Setting | Azure Field | +| ------------------------------------ | ------------------------------------------ | +| Identifier | Identifier (Entity ID) | +| Assertion consumer service URL | Reply URL (Assertion Consumer Service URL) | +| GitLab single sign-on URL | Sign on URL | +| Identity provider single sign-on URL | Login URL | +| Certificate fingerprint | Thumbprint | We recommend: @@ -164,12 +173,12 @@ Please follow the Okta documentation on [setting up a SAML application in Okta]( <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & SCIM setup](https://youtu.be/0ES9HsZq0AQ). -| GitLab Setting | Okta Field | -|--------------|----------------| -| Identifier | Audience URI | -| Assertion consumer service URL | Single sign-on URL | -| GitLab single sign-on URL | Login page URL (under **Application Login Page** settings) | -| Identity provider single sign-on URL | Identity Provider Single Sign-On URL | +| GitLab Setting | Okta Field | +| ------------------------------------ | ---------------------------------------------------------- | +| Identifier | Audience URI | +| Assertion consumer service URL | Single sign-on URL | +| GitLab single sign-on URL | Login page URL (under **Application Login Page** settings) | +| Identity provider single sign-on URL | Identity Provider Single Sign-On URL | Under Okta's **Single sign-on URL** field, check the option **Use this for Recipient URL and Destination URL**. @@ -186,14 +195,14 @@ application. If you decide to use the OneLogin generic [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934), we recommend the ["Use the OneLogin SAML Test Connector" documentation](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) with the following settings: -| GitLab Setting | OneLogin Field | -|--------------|----------------| -| Identifier | Audience | -| Assertion consumer service URL | Recipient | -| Assertion consumer service URL | ACS (Consumer) URL | +| GitLab Setting | OneLogin Field | +| ------------------------------------------------ | ---------------------------- | +| Identifier | Audience | +| Assertion consumer service URL | Recipient | +| Assertion consumer service URL | ACS (Consumer) URL | | Assertion consumer service URL (escaped version) | ACS (Consumer) URL Validator | -| GitLab single sign-on URL | Login URL | -| Identity provider single sign-on URL | SAML 2.0 Endpoint | +| GitLab single sign-on URL | Login URL | +| Identity provider single sign-on URL | SAML 2.0 Endpoint | Recommended `NameID` value: `OneLogin ID`. @@ -281,10 +290,7 @@ If a user is already a member of the group, linking the SAML identity does not c ### Blocking access -To rescind access to the group, perform the following steps, in order: - -1. Remove the user from the user data store on the identity provider or the list of users on the specific app. -1. Remove the user from the GitLab.com group. +Please refer to [Blocking access via SCIM](scim_setup.md#blocking-access). ### Unlinking accounts @@ -305,7 +311,7 @@ For example, to unlink the `MyOrg` account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Social sign-in** section, select **Disconnect** next to the connected account.  @@ -331,7 +337,7 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o NOTE: To inspect the SAML response, you can use one of these [SAML debugging tools](#saml-debugging-tools). -Also note that the value for `Groups` or `groups` in the SAML reponse can be either the group name or +Also note that the value for `Groups` or `groups` in the SAML response can be either the group name or the group ID depending what the IdP sends to GitLab. When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users @@ -352,10 +358,88 @@ the user gets the highest access level from the groups. For example, if one grou is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` access. -Users who are not members of any mapped SAML groups are removed from the GitLab group. +### Automatic member removal + +After a group sync, users who are not members of a mapped SAML group are removed from +the GitLab group. + +For example, in the following diagram: -You can prevent accidental member removal. For example, if you have a SAML group link for `Owner` level access -in a top-level group, you should also set up a group link for all other members. +- Alex Garcia signs into GitLab and is removed from GitLab Group C because they don't belong + to SAML Group C. +- Sidney Jones belongs to SAML Group C, but is not added to GitLab Group C because they have + not yet signed in. + +```mermaid +graph TB + subgraph SAML users + SAMLUserA[Sidney Jones] + SAMLUserB[Zhang Wei] + SAMLUserC[Alex Garcia] + SAMLUserD[Charlie Smith] + end + + subgraph SAML groups + SAMLGroupA["Group A"] --> SAMLGroupB["Group B"] + SAMLGroupA --> SAMLGroupC["Group C"] + SAMLGroupA --> SAMLGroupD["Group D"] + end + + SAMLGroupB --> |Member|SAMLUserA + SAMLGroupB --> |Member|SAMLUserB + + SAMLGroupC --> |Member|SAMLUserA + SAMLGroupC --> |Member|SAMLUserB + + SAMLGroupD --> |Member|SAMLUserD + SAMLGroupD --> |Member|SAMLUserC +``` + +```mermaid +graph TB + subgraph GitLab users + GitLabUserA[Sidney Jones] + GitLabUserB[Zhang Wei] + GitLabUserC[Alex Garcia] + GitLabUserD[Charlie Smith] + end + + subgraph GitLab groups + GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] + GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] + GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] + end + + GitLabGroupB --> |Member|GitLabUserA + + GitLabGroupC --> |Member|GitLabUserB + GitLabGroupC --> |Member|GitLabUserC + + GitLabGroupD --> |Member|GitLabUserC + GitLabGroupD --> |Member|GitLabUserD +``` + +```mermaid +graph TB + subgraph GitLab users + GitLabUserA[Sidney Jones] + GitLabUserB[Zhang Wei] + GitLabUserC[Alex Garcia] + GitLabUserD[Charlie Smith] + end + + subgraph GitLab groups after Alex Garcia signs in + GitLabGroupA[Group A] + GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] + GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] + GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] + end + + GitLabGroupB --> |Member|GitLabUserA + GitLabGroupC --> |Member|GitLabUserB + GitLabGroupD --> |Member|GitLabUserC + GitLabGroupD --> |Member|GitLabUserD +``` ## Passwords for users created via SAML SSO for Groups @@ -392,6 +476,9 @@ This can then be compared to the [NameID](#nameid) being sent by the identity pr ### Users receive a 404 +If you receive a `404` during setup when using "verify configuration", make sure you have used the correct +[SHA-1 generated fingerprint](../../../integration/saml.md#notes-on-configuring-your-identity-provider). + If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](#configuring-your-identity-provider), they may see a 404. As outlined in the [user access section](#linking-saml-to-your-existing-gitlabcom-account), a group Owner will need to provide the URL to users. @@ -403,17 +490,18 @@ If you do not wish to use that GitLab user with the SAML login, you can [unlink ### Message: "SAML authentication failed: User has already been taken" -The user that you're signed in with already has SAML linked to a different identity. +The user that you're signed in with already has SAML linked to a different identity, or the NameID value has changed. Here are possible causes and solutions: -| Cause | Solution | -|------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Cause | Solution | +| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | You've tried to link multiple SAML identities to the same user, for a given identity provider. | Change the identity that you sign in with. To do so, [unlink the previous SAML identity](#unlinking-accounts) from this GitLab account before attempting to sign in again. | +| The NameID changes everytime the user requests SSO identification | Check the NameID is not set with `Transient` format, or the NameID is not changing on subsequent requests.| ### Message: "SAML authentication failed: Email has already been taken" | Cause | Solution | -|------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| +| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | When a user account with the email address already exists in GitLab, but the user does not have the SAML identity tied to their account. | The user will need to [link their account](#user-access-and-management). | ### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" @@ -439,8 +527,8 @@ Alternatively, when users need to [link SAML to their existing GitLab.com accoun ### The NameID has changed -| Cause | Solution | -|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Cause | Solution | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | As mentioned in the [NameID](#nameid) section, if the NameID changes for any user, the user can be locked out. This is a common problem when an email address is used as the identifier. | Follow the steps outlined in the ["SAML authentication failed: User has already been taken"](#message-saml-authentication-failed-user-has-already-been-taken) section. | ### I need to change my SAML app diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index a0c281971fc..5e90501d487 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -58,7 +58,10 @@ During this configuration, note the following: - The `Tenant URL` and `secret token` are the ones retrieved in the [previous step](#gitlab-configuration). - It is recommended to set a notification email and check the **Send an email notification when a failure occurs** checkbox. -- For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled. +- For mappings, we only leave `Synchronize Azure Active Directory Users to AppName` enabled. + `Synchronize Azure Active Directory Groups to AppName` is usually disabled. However, this + does not mean Azure AD users cannot be provisioned in groups. Leaving it enabled does not break + the SCIM user provisioning, but causes errors in Azure AD that may be confusing and misleading. You can then test the connection by clicking on **Test Connection**. If the connection is successful, be sure to save your configuration before moving on. See below for [troubleshooting](#troubleshooting). @@ -69,13 +72,13 @@ Follow [Azure documentation to configure the attribute mapping](https://docs.mic The following table below provides an attribute mapping known to work with GitLab. If your SAML configuration differs from [the recommended SAML settings](index.md#azure-setup-notes), modify the corresponding `customappsso` settings accordingly. If a mapping is not listed in the -table, use the Azure defaults. +table, use the Azure defaults. For a list of required attributes, refer to the [SCIM API documentation](../../../api/scim.md). -| Azure Active Directory Attribute | `customappsso` Attribute | Matching precedence | -| -------------------------------- | ---------------------- | -------------------- | -| `objectId` | `externalId` | 1 | -| `userPrincipalName` | `emails[type eq "work"].value` | | -| `mailNickname` | `userName` | | +| Azure Active Directory Attribute | `customappsso` Attribute | Matching precedence | +| -------------------------------- | ------------------------------ | ------------------- | +| `objectId` | `externalId` | 1 | +| `userPrincipalName` | `emails[type eq "work"].value` | | +| `mailNickname` | `userName` | | For guidance, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). @@ -162,6 +165,12 @@ graph TD B -->|Yes| D[GitLab sends message back 'Email exists'] ``` +During provisioning: + +- Both primary and secondary emails are considered when checking whether a GitLab user account exists. +- Duplicate usernames are also handled, by adding suffix `1` upon user creation. For example, + due to already existing `test_user` username, `test_user1` is used. + As long as [Group SAML](index.md) has been configured, existing GitLab.com users can link to their accounts in one of the following ways: - By updating their *primary* email address in their GitLab.com user account to match their identity provider's user profile email address. @@ -183,13 +192,12 @@ For role information, please see the [Group SAML page](index.md#user-access-and- ### Blocking access -To rescind access to the group, remove the user from the identity -provider or users list for the specific app. - -Upon the next sync, the user is deprovisioned, which means that the user is removed from the group. +To rescind access to the top-level group, all sub-groups, and projects, remove or deactivate the user +on the identity provider. SCIM providers generally update GitLab with the changes on demand, which +is minutes at most. The user's membership is revoked and they immediately lose access. NOTE: -Deprovisioning does not delete the user account. +Deprovisioning does not delete the GitLab user account. ```mermaid graph TD @@ -260,9 +268,9 @@ Alternatively, users can be removed from the SCIM app which de-links all removed Changing the SAML or SCIM configuration or provider can cause the following problems: -| Problem | Solution | -|------------------------------------------------------------------------------|--------------------| -| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | +| Problem | Solution | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | | SCIM identity mismatch between GitLab and the Identify Provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) to update the SCIM `id` for the user on GitLab.com. | ### Azure diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index a0930867b2a..516f3504a98 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- # Group import/export **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. Existing groups running on any GitLab instance or GitLab.com can be exported with all their related data and moved to a new GitLab instance. @@ -22,7 +22,7 @@ See also: Users with the [Owner role](../../permissions.md) for a group can enable import and export for that group: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General > Visibility and access controls**. 1. Scroll to **Import sources**. 1. Enable the desired **Import sources**. @@ -69,7 +69,7 @@ Users with the [Owner role](../../permissions.md) for a group can export the contents of that group: 1. On the top bar, select **Menu >** **Groups** and find your group. -1. In the left sidebar, select **Settings**. +1. On the left sidebar, select **Settings**. 1. Scroll to the **Advanced** section, and select **Export Group**. 1. After the export is generated, you should receive an email with a link to the [exported contents](#exported-contents) in a compressed tar archive, with contents in NDJSON format. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 7d674b5deac..aaff0574ef0 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -88,7 +88,7 @@ The setting can be changed for any group by: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions, LFS, 2FA** section. - An administrator: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. 1. Select the group, and select **Edit**. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 4d254279a3d..68ae5e0df2d 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Value Stream Analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the group level. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 for groups. Value Stream Analytics measures the time spent to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) @@ -79,6 +79,9 @@ Data is shown for workflow items created during the selected date range. To filt ## How metrics are measured +> DORA API-based deployment metrics [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) +> to Premium in GitLab 14.3 for group-level Value Stream Analytics. + The "Time" metrics near the top of the page are measured as follows: - **Lead time**: median time from issue created to issue closed. @@ -113,7 +116,7 @@ Each stage of Value Stream Analytics is further described in the table below. | **Stage** | **Description** | | --------- | --------------- | -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label is tracked only if it already has an [Issue Board list](../../project/issue_board.md) created for it. | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label is tracked only if it already has an [issue board list](../../project/issue_board.md) created for it. | | Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (for example, `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | | Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the closing pattern is not present, then the calculation takes the creation time of the first commit in the merge request as the start time. | | Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | @@ -136,7 +139,7 @@ To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flo Value Stream Analytics dashboard does not present any data for: - Merge requests that do not close an issue. -- Issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. +- Issues not labeled with a label present in the issue board or for issues not assigned a milestone. - Staging stage, if the project has no [production environment](#how-the-production-environment-is-identified). ## How the production environment is identified diff --git a/doc/user/index.md b/doc/user/index.md index 8fc91ec95ea..d6eaad469c1 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -43,7 +43,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools - Hosting code in repositories with version control. - Tracking proposals for new implementations, bug reports, and feedback with a fully featured [Issue tracker](project/issues/index.md). -- Organizing and prioritizing with [Issue Boards](project/issue_board.md). +- Organizing and prioritizing with [issue boards](project/issue_board.md). - Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per branch with [Review Apps](../ci/review_apps/index.md). - Building, testing, and deploying with built-in [Continuous Integration](../ci/index.md). @@ -58,7 +58,7 @@ With GitLab Enterprise Edition, you can also: - Improve collaboration with: - [Merge Request Approvals](project/merge_requests/approvals/index.md). - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). - - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). + - [Multiple issue boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [linked issues](project/issues/related_issues.md). - Use [Burndown Charts](project/milestones/burndown_and_burnup_charts.md) to track progress during a sprint or while working on a new version of their software. - Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Search](search/advanced_search.md) for faster, more advanced code search across your entire GitLab instance. @@ -66,7 +66,7 @@ With GitLab Enterprise Edition, you can also: - [Mirror a repository](project/repository/repository_mirroring.md) from elsewhere on your local server. - View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipelines](../ci/pipelines/multi_project_pipelines.md). - [Lock files](project/file_lock.md) to prevent conflicts. -- View the current health and status of each CI environment running on Kubernetes with [Deploy Boards](project/deploy_boards.md). +- View the current health and status of each CI environment running on Kubernetes with [deploy boards](project/deploy_boards.md). - Leverage continuous delivery method with [Canary Deployments](project/canary_deployments.md). - Scan your code for vulnerabilities and [display them in merge requests](application_security/sast/index.md). diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md new file mode 100644 index 00000000000..ada278292a9 --- /dev/null +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -0,0 +1,126 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Connect a cluster to GitLab **(FREE)** + +You can create new or connect existing clusters to GitLab through different [levels](#cluster-levels), +using different [methods](#methods-to-connect-a-cluster-to-gitlab). + +Before getting started: + +1. Check the [supported Kubernetes cluster versions](#supported-cluster-versions). +1. Define the [cluster level](#cluster-levels) according to your case. + +After that: + +1. Choose the [method](#methods-to-connect-a-cluster-to-gitlab) +to connect your cluster according to your case. +1. [View your clusters](#view-your-clusters) connected to GitLab. + +## Methods to connect a cluster to GitLab + +GitLab offers three methods to connect existing and create new clusters: + +- **GitLab Kubernetes Agent**: the best solution to +[connect existing clusters](#connect-existing-clusters-to-gitlab). +- **Infrastructure as Code**: it's a broader infrastructure management +toolset that includes managing your cluster. It's the recommended +solution to [create a new cluster](#create-new-clusters-from-gitlab) +from GitLab. +- **Certificate-based method**: our first and legacy solution uses +cluster certificates to connect your cluster to GitLab. It is no longer +recommended for [security implications](#security-implications-for-clusters-connected-with-certificates). + +### Connect existing clusters to GitLab + +To safely connect and configure an existing cluster on the **project level**, +we **recommend** using the [GitLab Kubernetes Agent](../../../clusters/agent/index.md). +We are working to support [the Agent for connecting a cluster at the group level](https://gitlab.com/groups/gitlab-org/-/epics/5784). + +Alternatively, you can use [cluster certificates](../../../project/clusters/add_existing_cluster.md) +to connect clusters in all levels (projects, group, instance). However, +for [security implications](#security-implications-for-clusters-connected-with-certificates), +we don't recommend using this method. + +### Create new clusters from GitLab + +To safely create new clusters from GitLab, use +[Infrastructure as Code](../../iac/index.md#create-a-new-cluster-through-iac). + +The [certificate-based method to create a new cluster](../../../project/clusters/add_remove_clusters.md) +is still available through the GitLab UI but was **deprecated** in GitLab 14.0. +If possible, we don't recommend using this method. + +### Connect multiple clusters to a single project + +To connect multiple clusters to a single project in GitLab, +we **recommend** using the [GitLab Kubernetes Agent](../../../clusters/agent/index.md). + +You can also use the [certificate-based method](../../../project/clusters/multiple_kubernetes_clusters.md), +but, for [security implications](#security-implications-for-clusters-connected-with-certificates), +we don't recommend using this method. + +## Cluster levels + +Choose your cluster's level according to its purpose: + +| Level | Purpose | +|--|--| +| [Project level](../../../project/clusters/index.md) | Use your cluster for a single project. | +| [Group level](../../../group/clusters/index.md) | Use the same cluster across multiple projects within your group. | +| [Instance level](../../../instance/clusters/index.md) **(FREE SELF)** | Use the same cluster across groups and projects within your instance. | + +## Supported cluster versions + +GitLab is committed to support at least two production-ready Kubernetes minor +versions at any given time. We regularly review the versions we support, and +provide a three-month deprecation period before we remove support of a specific +version. The range of supported versions is based on the evaluation of: + +- The versions supported by major managed Kubernetes providers. +- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions). + +GitLab supports the following Kubernetes versions, and you can upgrade your +Kubernetes version to any supported version at any time: + +- 1.19 (support ends on February 22, 2022) +- 1.18 (support ends on November 22, 2021) +- 1.17 (support ends on September 22, 2021) + +Some GitLab features may support versions outside the range provided here. + +## View your clusters + +To view the Kubernetes clusters connected to your project, +group, or instance, open the cluster's page according to the +[level](#cluster-levels) of your cluster. + +**Project-level clusters:** + +1. Go to your project's homepage. +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. + +**Group-level clusters:** + +1. Go to your group's homepage. +1. On the left sidebar, select **Kubernetes**. + +**Instance-level clusters:** **(FREE SELF)** + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Kubernetes**. + +## Security implications for clusters connected with certificates + +WARNING: +The whole cluster security is based on a model where [developers](../../../permissions.md) +are trusted, so **only trusted users should be allowed to control your clusters**. + +The use of cluster certificates to connect your cluster grants +access to a wide set of functionalities needed to successfully +build and deploy a containerized application. Bear in mind that +the same credentials are used for all the applications running +on the cluster. diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 35af316d7ac..90044fa74e1 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -48,7 +48,7 @@ so that your credentials are not exposed through the code. To do so, follow the 1. On your computer, encode the JSON file to `base64` (replace `/path/to/sa-key.json` to the path to your key): ```shell - base64 /path/to/sa-key.json | tr -d \\n` + base64 /path/to/sa-key.json | tr -d \\n ``` 1. Use the output of this command as the `BASE64_GOOGLE_CREDENTIALS` environment variable in the next step. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md index 3bf79ea90c7..9ef7bd0f3ff 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -6,16 +6,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Install cert-manager with a cluster management project -> [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. +> - Support for cert-manager v1.4 was [introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/69405) in GitLab 14.3. Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a [management project template](../../../../../user/clusters/management_project_template.md), to install cert-manager you should uncomment this line from your `helmfile.yaml`: ```yaml - - path: applications/cert-manager/helmfile.yaml + - path: applications/cert-manager-1-4/helmfile.yaml ``` +NOTE: +We kept the `- path: applications/cert-manager/helmfile.yaml` with cert-manager v0.10 to facilitate +the [migration from GitLab Managed Apps to a cluster management project](../../../../clusters/migrating_from_gma_to_project_template.md). + cert-manager: - Is installed by default into the `gitlab-managed-apps` namespace of your cluster. @@ -24,7 +29,7 @@ cert-manager: email address to be specified. The email address is used by Let's Encrypt to contact you about expiring certificates and issues related to your account. -The following configuration in your `applications/cert-manager/helmfile.yaml` is required to install cert-manager: +To install cert-manager in your cluster, configure your `applications/cert-manager-1-4/helmfile.yaml` to: ```yaml certManager: @@ -48,9 +53,3 @@ You can customize the installation of cert-manager by defining a management project. Refer to the [chart](https://github.com/jetstack/cert-manager) for the available configuration options. - -Support for installing the Cert Manager managed application is provided by the -GitLab Configure group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md index 4e84f2c5ef4..c19bfbfb1b1 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md @@ -120,9 +120,3 @@ global: enabled: - 'flow:sourceContext=namespace;destinationContext=namespace' ``` - -Support for installing the Cilium managed application is provided by the -GitLab Container Security group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md index 3d2b3caf0af..dbde9bd90b0 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md @@ -27,8 +27,3 @@ You can customize the installation of Elastic Stack by updating the management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all available configuration options. - -Support for installing the Elastic Stack managed application is provided by the -GitLab APM group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md b/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md index dff0c3bd7bc..7bd2a4a5133 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/falco.md @@ -93,9 +93,3 @@ You can check these logs with the following command: ```shell kubectl -n gitlab-managed-apps logs -l app=falco ``` - -Support for installing the Falco managed application is provided by the -GitLab Container Security group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md b/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md index bf05f8f87d8..c5de0511c2f 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/fluentd.md @@ -28,9 +28,3 @@ for the current development release of Fluentd for all available configuration o The configuration chart link points to the current development release, which may differ from the version you have installed. To ensure compatibility, switch to the specific branch or tag you are using. - -Support for installing the Fluentd managed application is provided by the -GitLab Container Security group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md index 4f17dbab11b..5ee26db754e 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md @@ -24,8 +24,3 @@ You can customize the installation of Ingress by updating the management project. Refer to the [chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress) for the available configuration options. - -Support for installing the Ingress managed application is provided by the GitLab Configure group. -If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), -and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md index 19e6c76d133..3420f340c94 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md @@ -25,8 +25,3 @@ You can customize the installation of Prometheus by updating the management project. Refer to the [Configuration section](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) of the Prometheus chart's README for the available configuration options. - -Support for installing the Prometheus managed application is provided by the -GitLab APM group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md index 56e01be68cb..841f2af7863 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -18,6 +18,8 @@ uncomment this line from your `helmfile.yaml`: GitLab Runner is installed by default into the `gitlab-managed-apps` namespace of your cluster. +## Required variables + For GitLab Runner to function, you _must_ specify the following in your `applications/gitlab-runner/values.yaml.gotmpl` file: @@ -28,10 +30,10 @@ For GitLab Runner to function, you _must_ specify the following in your These values can be specified using [CI/CD variables](../../../../../ci/variables/index.md): -- `GITLAB_RUNNER_GITLAB_URL` is used for `gitlabUrl`. +- `CI_SERVER_URL` is used for `gitlabUrl`. If you are using GitLab.com, you don't need to set this variable. - `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` -The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `GITLAB_RUNNER_TOKEN` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `runnerToken:` in `applications/gitlab-runner/values.yaml.gotmpl`. +The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `CI_SERVER_URL` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `gitlabUrl:` in `applications/gitlab-runner/values.yaml.gotmpl`. The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../../../../ci/variables/index.md#protect-a-cicd-variable) and [masked variable](../../../../../ci/variables/index.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml.gotmpl` file. @@ -40,9 +42,3 @@ You can customize the installation of GitLab Runner by defining management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/gitlab-runner) for the available configuration options. - -Support for installing the GitLab Runner managed application is provided by the -GitLab Runner group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Runner group](https://about.gitlab.com/handbook/product/categories/#runner-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md index 4d82fe389d2..300350010af 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md @@ -68,9 +68,3 @@ ingress: postgresql: postgresqlPassword: example-postgresql-password ``` - -Support for installing the Sentry managed application is provided by the -GitLab Health group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Health group](https://about.gitlab.com/handbook/product/categories/#health-group). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md index 291321963d0..d6b4eb5c157 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -100,9 +100,3 @@ kubectl -n gitlab-managed-apps exec -it vault-0 sh This should give you your unseal keys and initial root token. Make sure to note these down and keep these safe, as they're required to unseal the Vault throughout its lifecycle. - -Support for installing the Vault managed application is provided by the -GitLab Release Management group. If you run into unknown issues, -[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the -[Release Management group](https://about.gitlab.com/handbook/product/categories/#release-management-group). diff --git a/doc/user/infrastructure/img/terraform_list_view_v13_8.png b/doc/user/infrastructure/iac/img/terraform_list_view_v13_8.png Binary files differindex 6eb85285e81..6eb85285e81 100644 --- a/doc/user/infrastructure/img/terraform_list_view_v13_8.png +++ b/doc/user/infrastructure/iac/img/terraform_list_view_v13_8.png diff --git a/doc/user/infrastructure/img/terraform_plan_log_v13_0.png b/doc/user/infrastructure/iac/img/terraform_plan_log_v13_0.png Binary files differindex c3c6f6b2f8b..c3c6f6b2f8b 100644 --- a/doc/user/infrastructure/img/terraform_plan_log_v13_0.png +++ b/doc/user/infrastructure/iac/img/terraform_plan_log_v13_0.png diff --git a/doc/user/infrastructure/img/terraform_plan_widget_v13_2.png b/doc/user/infrastructure/iac/img/terraform_plan_widget_v13_2.png Binary files differindex 564835a5dbe..564835a5dbe 100644 --- a/doc/user/infrastructure/img/terraform_plan_widget_v13_2.png +++ b/doc/user/infrastructure/iac/img/terraform_plan_widget_v13_2.png diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 5b44490f78d..89df9c1d18f 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -65,7 +65,7 @@ Amazon S3 or Google Cloud Storage. Its features include: - Locking and unlocking state. - Remote Terraform plan and apply execution. -Read more on setting up and [using GitLab Managed Terraform states](../terraform_state.md) +Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md). ## Terraform module registry @@ -81,7 +81,7 @@ solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. -Read more on setting up and [using the merge request integrations](../mr_integration.md). +Read more on setting up and [using the merge request integrations](mr_integration.md). ## The GitLab Terraform provider diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md new file mode 100644 index 00000000000..853a39a59a8 --- /dev/null +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -0,0 +1,210 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Terraform integration in Merge Requests **(FREE)** + +Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. + +## Output Terraform Plan information into a merge request + +Using the [GitLab Terraform Report artifact](../../../ci/yaml/index.md#artifactsreportsterraform), +you can expose details from `terraform plan` runs directly into a merge request widget, +enabling you to see statistics about the resources that Terraform creates, +modifies, or destroys. + +WARNING: +Like any other job artifact, Terraform Plan data is [viewable by anyone with Guest access](../../permissions.md) to the repository. +Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform Plan +includes sensitive data such as passwords, access tokens, or certificates, we strongly +recommend encrypting plan output or modifying the project visibility settings. + +## Configure Terraform report artifacts + +GitLab ships with a [pre-built CI template](index.md#quick-start) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. + +To manually configure a GitLab Terraform Report artifact: + +1. For simplicity, let's define a few reusable variables to allow us to + refer to these files multiple times: + + ```yaml + variables: + PLAN: plan.cache + PLAN_JSON: plan.json + ``` + +1. Install `jq`, a + [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). +1. Create an alias for a specific `jq` command that parses out the information we + want to extract from the `terraform plan` output: + + ```yaml + before_script: + - apk --no-cache add jq + - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" + ``` + + NOTE: + In distributions that use Bash (for example, Ubuntu), `alias` statements are not + expanded in non-interactive mode. If your pipelines fail with the error + `convert_report: command not found`, alias expansion can be activated explicitly + by adding a `shopt` command to your script: + + ```yaml + before_script: + - shopt -s expand_aliases + - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" + ``` + +1. Define a `script` that runs `terraform plan` and `terraform show`. These commands + pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. + This JSON is used to create a + [GitLab Terraform Report artifact](../../../ci/yaml/index.md#artifactsreportsterraform). + The Terraform report obtains a Terraform `tfplan.json` file. The collected + Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. + + ```yaml + plan: + stage: build + script: + - terraform plan -out=$PLAN + - terraform show --json $PLAN | convert_report > $PLAN_JSON + artifacts: + reports: + terraform: $PLAN_JSON + ``` + + For a full example using the pre-built image, see [Example `.gitlab-ci.yml` + file](#example-gitlab-ciyml-file). + + For an example displaying multiple reports, see [`.gitlab-ci.yml` multiple reports file](#multiple-terraform-plan-reports). + +1. Running the pipeline displays the widget in the merge request, like this: + +  + +1. Clicking the **View Full Log** button in the widget takes you directly to the + plan output present in the pipeline logs: + +  + +### Example `.gitlab-ci.yml` file + +```yaml +default: + image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest + + cache: + key: example-production + paths: + - ${TF_ROOT}/.terraform + +variables: + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production + +before_script: + - cd ${TF_ROOT} + +stages: + - prepare + - validate + - build + - deploy + +init: + stage: prepare + script: + - gitlab-terraform init + +validate: + stage: validate + script: + - gitlab-terraform validate + +plan: + stage: build + script: + - gitlab-terraform plan + - gitlab-terraform plan-json + artifacts: + name: plan + paths: + - ${TF_ROOT}/plan.cache + reports: + terraform: ${TF_ROOT}/plan.json + +apply: + stage: deploy + environment: + name: production + script: + - gitlab-terraform apply + dependencies: + - plan + when: manual + only: + - master +``` + +### Multiple Terraform Plan reports + +Starting with GitLab version 13.2, you can display multiple reports on the Merge Request +page. The reports also display the `artifacts: name:`. See example below for a suggested setup. + +```yaml +default: + image: + name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform + entrypoint: + - '/usr/bin/env' + - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' + + cache: + paths: + - .terraform + +stages: + - build + +.terraform-plan-generation: + stage: build + variables: + PLAN: plan.tfplan + JSON_PLAN_FILE: tfplan.json + before_script: + - cd ${TERRAFORM_DIRECTORY} + - terraform --version + - terraform init + - apk --no-cache add jq + script: + - terraform validate + - terraform plan -out=${PLAN} + - terraform show --json ${PLAN} | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > ${JSON_PLAN_FILE} + artifacts: + reports: + terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE} + +review_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "review/" + # Review will not include an artifact name + +staging_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "staging/" + artifacts: + name: Staging + +production_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "production/" + artifacts: + name: Production +``` diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md new file mode 100644 index 00000000000..fb051c7fa14 --- /dev/null +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -0,0 +1,446 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# GitLab managed Terraform State **(FREE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. + +[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) +enable you to store the state file in a remote, shared store. GitLab uses the +[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) +to securely store the state files in local storage (the default) or +[the remote store of your choice](../../../administration/terraform_state.md). + +WARNING: +Using local storage (the default) on clustered deployments of GitLab will result in +a split state across nodes, making subsequent executions of Terraform inconsistent. +You are highly advised to use a remote storage in that case. + +The GitLab managed Terraform state backend can store your Terraform state easily and +securely, and spares you from setting up additional remote resources like +Amazon S3 or Google Cloud Storage. Its features include: + +- Versioning of Terraform state files. +- Supporting encryption of the state file both in transit and at rest. +- Locking and unlocking state. +- Remote Terraform plan and apply execution. + +A GitLab **administrator** must [setup the Terraform state storage configuration](../../../administration/terraform_state.md) +before using this feature. + +## Permissions for using Terraform + +In GitLab version 13.1, the [Maintainer role](../../permissions.md) was required to use a +GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, the +[Maintainer role](../../permissions.md) is required to lock, unlock, and write to the state +(using `terraform apply`), while the [Developer role](../../permissions.md) is required to read +the state (using `terraform plan -lock=false`). + +## Set up GitLab-managed Terraform state + +To get started with a GitLab-managed Terraform state, there are two different options: + +- [Use a local machine](#get-started-using-local-development). +- [Use GitLab CI](#get-started-using-gitlab-ci). + +Terraform States can be found by navigating to a Project's +**{cloud-gear}** **Infrastructure > Terraform** page. + +### Get started using local development + +If you plan to only run `terraform plan` and `terraform apply` commands from your +local machine, this is a simple way to get started: + +1. Create your project on your GitLab instance. +1. Navigate to **Settings > General** and note your **Project name** + and **Project ID**. +1. Define the Terraform backend in your Terraform project to be: + + ```hcl + terraform { + backend "http" { + } + } + ``` + +1. Create a [Personal Access Token](../../profile/personal_access_tokens.md) with + the `api` scope. + +1. On your local machine, run `terraform init`, passing in the following options, + replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and + `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your + Terraform state, and stores that state in your GitLab project. The name of + your state can contain only uppercase and lowercase letters, decimal digits, + hyphens, and underscores. This example uses `gitlab.com`: + + ```shell + terraform init \ + -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>" \ + -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ + -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ + -backend-config="username=<YOUR-USERNAME>" \ + -backend-config="password=<YOUR-ACCESS-TOKEN>" \ + -backend-config="lock_method=POST" \ + -backend-config="unlock_method=DELETE" \ + -backend-config="retry_wait_min=5" + ``` + +If you already have a GitLab-managed Terraform state, you can use the `terraform init` command +with the prepopulated parameters values: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Infrastructure > Terraform**. +1. Next to the environment you want to use, select the [Actions menu](#managing-state-files) + **{ellipsis_v}** and select **Copy Terraform init command**. + +You can now run `terraform plan` and `terraform apply` as you normally would. + +### Get started using GitLab CI + +If you don't want to start with local development, you can also use GitLab CI to +run your `terraform plan` and `terraform apply` commands. + +Next, [configure the backend](#configure-the-backend). + +#### Configure the backend + +After executing the `terraform init` command, you must configure the Terraform backend +and the CI YAML file: + +1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) + by adding the following code block in a `.tf` file (such as `backend.tf`) to + define the remote backend: + + ```hcl + terraform { + backend "http" { + } + } + ``` + +1. In the root directory of your project repository, configure a + `.gitlab-ci.yml` file. This example uses a pre-built image which includes a + `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab + Terraform Images project](https://gitlab.com/gitlab-org/terraform-images). + + ```yaml + image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest + ``` + +1. In the `.gitlab-ci.yml` file, define some CI/CD variables to ease + development. In this example, `TF_ROOT` is the directory where the Terraform + commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab + instance where this pipeline runs, and the final path segment in `TF_ADDRESS` + is the name of the Terraform state. Projects may have multiple states, and + this name is arbitrary, so in this example we set it to `example-production` + which corresponds with the directory we're using as our `TF_ROOT`, and we + ensure that the `.terraform` directory is cached between jobs in the pipeline + using a cache key based on the state name (`example-production`): + + ```yaml + variables: + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production + + cache: + key: example-production + paths: + - ${TF_ROOT}/.terraform + ``` + +1. In a `before_script`, change to your `TF_ROOT`: + + ```yaml + before_script: + - cd ${TF_ROOT} + + stages: + - prepare + - validate + - build + - deploy + + init: + stage: prepare + script: + - gitlab-terraform init + + validate: + stage: validate + script: + - gitlab-terraform validate + + plan: + stage: build + script: + - gitlab-terraform plan + - gitlab-terraform plan-json + artifacts: + name: plan + paths: + - ${TF_ROOT}/plan.cache + reports: + terraform: ${TF_ROOT}/plan.json + + apply: + stage: deploy + environment: + name: production + script: + - gitlab-terraform apply + dependencies: + - plan + when: manual + only: + - master + ``` + +1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline + runs the `gitlab-terraform init`, `gitlab-terraform validate`, and + `gitlab-terraform plan` commands. + +The output from the above `terraform` commands should be viewable in the job logs. + +WARNING: +Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../../permissions.md) to the repository. +Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan +includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly +recommends encrypting plan output or modifying the project visibility settings. + +### Example project + +See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 in a custom VPC. + +## Using a GitLab managed Terraform state backend as a remote data source + +You can use a GitLab-managed Terraform state as a +[Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html). +To use your existing Terraform state backend as a data source, provide the following details +as [Terraform input variables](https://www.terraform.io/docs/language/values/variables.html): + +- **address**: The URL of the remote state backend you want to use as a data source. + For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. +- **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../../profile/personal_access_tokens.md) for + authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. +- **password**: The password to authenticate with the data source. If you are using a Personal Access Token for + authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI/CD variable. + +An example setup is shown below: + +1. Create a file named `example.auto.tfvars` with the following contents: + + ```plaintext + example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> + example_username=<GitLab username> + example_access_token=<GitLab Personal Access Token> + ``` + +1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): + + ```hcl + data "terraform_remote_state" "example" { + backend = "http" + + config = { + address = var.example_remote_state_address + username = var.example_username + password = var.example_access_token + } + } + ``` + +Outputs from the data source can now be referenced in your Terraform resources +using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. + +You need at least the [Developer role](../../permissions.md) in the target project +to read the Terraform state. + +## Migrating to GitLab Managed Terraform state + +Terraform supports copying the state when the backend is changed or +reconfigured. This can be useful if you need to migrate from another backend to +GitLab managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab Managed Terraform state. + +The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab Managed Terraform state from a different state storage backend. + +### Setting up the initial backend + +```shell +PROJECT_ID="<gitlab-project-id>" +TF_USERNAME="<gitlab-username>" +TF_PASSWORD="<gitlab-personal-access-token>" +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +### Changing the backend + +Now that `terraform init` has created a `.terraform/` directory that knows where +the old state is, you can tell it about the new location: + +```shell +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... +Backend configuration changed! + +Terraform has detected that the configuration specified for the backend +has changed. Terraform will now check for existing state in the backends. + + +Acquiring state lock. This may take a few moments... +Do you want to copy existing state to the new backend? + Pre-existing state was found while migrating the previous "http" backend to the + newly configured "http" backend. No existing state was found in the newly + configured "http" backend. Do you want to copy this state to the new "http" + backend? Enter "yes" to copy and "no" to start with an empty state. + + Enter a value: yes + + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +If you type `yes`, it copies your state from the old location to the new +location. You can then go back to running it in GitLab CI/CD. + +## Managing state files + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. + +Users with Developer and greater [permissions](../../permissions.md) can view the +state files attached to a project at **Infrastructure > Terraform**. Users with the +Maintainer role can perform commands on the state files. The user interface +contains these fields: + + + +- **Name**: The name of the environment, with a locked (**{lock}**) icon if the + state file is locked. +- **Pipeline**: A link to the most recent pipeline and its status. +- **Details**: Information about when the state file was created or changed. +- **Actions**: Actions you can take on the state file, including copying the `terraform init` command, + downloading, locking, unlocking, or [removing](#remove-a-state-file) the state file and versions. + +NOTE: +Additional improvements to the +[graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563) +are planned. + +## Remove a state file + +Users with Maintainer and greater [permissions](../../permissions.md) can use the +following options to remove a state file: + +- **GitLab UI**: Go to **Infrastructure > Terraform**. In the **Actions** column, + click the vertical ellipsis (**{ellipsis_v}**) button and select + **Remove state file and versions**. +- **GitLab REST API**: You can remove a state file by making a request to the + REST API. For example: + + ```shell + curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>" + ``` + +- [GitLab GraphQL API](#remove-a-state-file-with-the-gitlab-graphql-api). + +### Remove a state file with the GitLab GraphQL API + +You can remove a state file by making a GraphQL API request. For example: + +```shell +mutation deleteState { + terraformStateDelete(input: { id: "<global_id_for_the_state>" }) { + errors + } +} +``` + +You can obtain the `<global_id_for_the_state>` by querying the list of states: + +```shell +query ProjectTerraformStates { + project(fullPath: "<your_project_path>") { + terraformStates { + nodes { + id + name + } + } + } +} +``` + +For those new to the GitLab GraphQL API, read +[Getting started with GitLab GraphQL API](../../../api/graphql/getting_started.md). + +## Troubleshooting + +### Unable to lock Terraform state files in CI jobs for `terraform apply` using a plan created in a previous job + +When passing `-backend-config=` to `terraform init`, Terraform persists these values inside the plan +cache file. This includes the `password` value. + +As a result, to create a plan and later use the same plan in another CI job, you might get the error +`Error: Error acquiring the state lock` errors when using `-backend-config=password=$CI_JOB_TOKEN`. +This happens because the value of `$CI_JOB_TOKEN` is only valid for the duration of the current job. + +As a workaround, use [http backend configuration variables](https://www.terraform.io/docs/language/settings/backends/http.html#configuration-variables) in your CI job, +which is what happens behind the scenes when following the +[Get started using GitLab CI](#get-started-using-gitlab-ci) instructions. diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index b2d75a22615..9f28a40474e 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -6,9 +6,40 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Infrastructure management **(FREE)** -GitLab provides you with great solutions to help you manage your -infrastructure: +With the rise of DevOps and SRE approaches, infrastructure management becomes codified, +automatable, and software development best practices gain their place around infrastructure +management too. On one hand, the daily tasks of classical operations people changed +and are more similar to traditional software development. On the other hand, software engineers +are more likely to control their whole DevOps lifecycle, including deployments and delivery. -- [Infrastructure as Code and GitOps](iac/index.md) -- [Kubernetes clusters](../project/clusters/index.md) -- [Runbooks](../project/clusters/runbooks/index.md) +GitLab offers various features to speed up and simplify your infrastructure management practices. + +## Infrastructure as Code + +GitLab has deep integrations with Terraform to run Infrastructure as Code pipelines +and support various processes. Terraform is considered the standard in cloud infrastructure provisioning. +The various GitLab integrations help you: + +- Get started quickly without any setup. +- Collaborate around infrastructure changes in merge requests the same as you might + with code changes. +- Scale using a module registry. + +Learn more about how GitLab can help you run [Infrastructure as Code](iac/index.md). + +## Integrated Kubernetes management + +GitLab has special integrations with Kubernetes to help you deploy, manage and troubleshoot +third-party or custom applications in Kubernetes clusters. Auto DevOps provides a full +DevSecOps pipeline by default targeted at Kubernetes based deployments. To support +all the GitLab features, GitLab offers a cluster management project for easy onboarding. +The deploy boards provide quick insights into your cluster, including pod logs tailing. + +Learn more about the [GitLab integration with Kubernetes](../project/clusters/index.md). + +## Runbooks in GitLab + +Runbooks are a collection of documented procedures that explain how to carry out a task, +such as starting, stopping, debugging, or troubleshooting a system. + +Read more about [how executable runbooks work in GitLab](../project/clusters/runbooks/index.md). diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md index 29bf218b109..81e8f7cbd33 100644 --- a/doc/user/infrastructure/mr_integration.md +++ b/doc/user/infrastructure/mr_integration.md @@ -1,210 +1,9 @@ --- -stage: Configure -group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'iac/mr_integration.md' +remove_date: '2021-11-26' --- -# Terraform integration in Merge Requests **(FREE)** +This document was moved to [another location](iac/mr_integration.md). -Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. - -## Output Terraform Plan information into a merge request - -Using the [GitLab Terraform Report artifact](../../ci/yaml/index.md#artifactsreportsterraform), -you can expose details from `terraform plan` runs directly into a merge request widget, -enabling you to see statistics about the resources that Terraform creates, -modifies, or destroys. - -WARNING: -Like any other job artifact, Terraform Plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. -Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform Plan -includes sensitive data such as passwords, access tokens, or certificates, we strongly -recommend encrypting plan output or modifying the project visibility settings. - -## Configure Terraform report artifacts - -GitLab ships with a [pre-built CI template](iac/index.md#quick-start) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. - -To manually configure a GitLab Terraform Report artifact: - -1. For simplicity, let's define a few reusable variables to allow us to - refer to these files multiple times: - - ```yaml - variables: - PLAN: plan.cache - PLAN_JSON: plan.json - ``` - -1. Install `jq`, a - [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). -1. Create an alias for a specific `jq` command that parses out the information we - want to extract from the `terraform plan` output: - - ```yaml - before_script: - - apk --no-cache add jq - - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" - ``` - - NOTE: - In distributions that use Bash (for example, Ubuntu), `alias` statements are not - expanded in non-interactive mode. If your pipelines fail with the error - `convert_report: command not found`, alias expansion can be activated explicitly - by adding a `shopt` command to your script: - - ```yaml - before_script: - - shopt -s expand_aliases - - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" - ``` - -1. Define a `script` that runs `terraform plan` and `terraform show`. These commands - pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. - This JSON is used to create a - [GitLab Terraform Report artifact](../../ci/yaml/index.md#artifactsreportsterraform). - The Terraform report obtains a Terraform `tfplan.json` file. The collected - Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. - - ```yaml - plan: - stage: build - script: - - terraform plan -out=$PLAN - - terraform show --json $PLAN | convert_report > $PLAN_JSON - artifacts: - reports: - terraform: $PLAN_JSON - ``` - - For a full example using the pre-built image, see [Example `.gitlab-ci.yml` - file](#example-gitlab-ciyml-file). - - For an example displaying multiple reports, see [`.gitlab-ci.yml` multiple reports file](#multiple-terraform-plan-reports). - -1. Running the pipeline displays the widget in the merge request, like this: - -  - -1. Clicking the **View Full Log** button in the widget takes you directly to the - plan output present in the pipeline logs: - -  - -### Example `.gitlab-ci.yml` file - -```yaml -default: - image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest - - cache: - key: example-production - paths: - - ${TF_ROOT}/.terraform - -variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production - -before_script: - - cd ${TF_ROOT} - -stages: - - prepare - - validate - - build - - deploy - -init: - stage: prepare - script: - - gitlab-terraform init - -validate: - stage: validate - script: - - gitlab-terraform validate - -plan: - stage: build - script: - - gitlab-terraform plan - - gitlab-terraform plan-json - artifacts: - name: plan - paths: - - ${TF_ROOT}/plan.cache - reports: - terraform: ${TF_ROOT}/plan.json - -apply: - stage: deploy - environment: - name: production - script: - - gitlab-terraform apply - dependencies: - - plan - when: manual - only: - - master -``` - -### Multiple Terraform Plan reports - -Starting with GitLab version 13.2, you can display multiple reports on the Merge Request -page. The reports also display the `artifacts: name:`. See example below for a suggested setup. - -```yaml -default: - image: - name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform - entrypoint: - - '/usr/bin/env' - - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' - - cache: - paths: - - .terraform - -stages: - - build - -.terraform-plan-generation: - stage: build - variables: - PLAN: plan.tfplan - JSON_PLAN_FILE: tfplan.json - before_script: - - cd ${TERRAFORM_DIRECTORY} - - terraform --version - - terraform init - - apk --no-cache add jq - script: - - terraform validate - - terraform plan -out=${PLAN} - - terraform show --json ${PLAN} | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > ${JSON_PLAN_FILE} - artifacts: - reports: - terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE} - -review_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "review/" - # Review will not include an artifact name - -staging_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "staging/" - artifacts: - name: Staging - -production_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "production/" - artifacts: - name: Production -``` +<!-- This redirect file can be deleted after <2021-11-26>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index 179f9677b96..e71291d502e 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -1,431 +1,9 @@ --- -stage: Configure -group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'iac/terraform_state.md' +remove_date: '2021-11-26' --- -# GitLab managed Terraform State **(FREE)** +This document was moved to [another location](iac/terraform_state.md). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. - -[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) -enable you to store the state file in a remote, shared store. GitLab uses the -[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) -to securely store the state files in local storage (the default) or -[the remote store of your choice](../../administration/terraform_state.md). - -WARNING: -Using local storage (the default) on clustered deployments of GitLab will result in -a split state across nodes, making subsequent executions of Terraform inconsistent. -You are highly advised to use a remote storage in that case. - -The GitLab managed Terraform state backend can store your Terraform state easily and -securely, and spares you from setting up additional remote resources like -Amazon S3 or Google Cloud Storage. Its features include: - -- Versioning of Terraform state files. -- Supporting encryption of the state file both in transit and at rest. -- Locking and unlocking state. -- Remote Terraform plan and apply execution. - -A GitLab **administrator** must [setup the Terraform state storage configuration](../../administration/terraform_state.md) -before using this feature. - -## Permissions for using Terraform - -In GitLab version 13.1, the [Maintainer role](../permissions.md) was required to use a -GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, the -[Maintainer role](../permissions.md) is required to lock, unlock, and write to the state -(using `terraform apply`), while the [Developer role](../permissions.md) is required to read -the state (using `terraform plan -lock=false`). - -## Set up GitLab-managed Terraform state - -To get started with a GitLab-managed Terraform state, there are two different options: - -- [Use a local machine](#get-started-using-local-development). -- [Use GitLab CI](#get-started-using-gitlab-ci). - -Terraform States can be found by navigating to a Project's -**{cloud-gear}** **Infrastructure > Terraform** page. - -### Get started using local development - -If you plan to only run `terraform plan` and `terraform apply` commands from your -local machine, this is a simple way to get started: - -1. Create your project on your GitLab instance. -1. Navigate to **Settings > General** and note your **Project name** - and **Project ID**. -1. Define the Terraform backend in your Terraform project to be: - - ```hcl - terraform { - backend "http" { - } - } - ``` - -1. Create a [Personal Access Token](../profile/personal_access_tokens.md) with - the `api` scope. - -1. On your local machine, run `terraform init`, passing in the following options, - replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and - `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your - Terraform state, and stores that state in your GitLab project. The name of - your state can contain only uppercase and lowercase letters, decimal digits, - hyphens, and underscores. This example uses `gitlab.com`: - - ```shell - terraform init \ - -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>" \ - -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ - -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ - -backend-config="username=<YOUR-USERNAME>" \ - -backend-config="password=<YOUR-ACCESS-TOKEN>" \ - -backend-config="lock_method=POST" \ - -backend-config="unlock_method=DELETE" \ - -backend-config="retry_wait_min=5" - ``` - -If you already have a GitLab-managed Terraform state, you can use the `terraform init` command -with the prepopulated parameters values: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Infrastructure > Terraform**. -1. Next to the environment you want to use, select the [Actions menu](#managing-state-files) - **{ellipsis_v}** and select **Copy Terraform init command**. - -You can now run `terraform plan` and `terraform apply` as you normally would. - -### Get started using GitLab CI - -If you don't want to start with local development, you can also use GitLab CI to -run your `terraform plan` and `terraform apply` commands. - -Next, [configure the backend](#configure-the-backend). - -#### Configure the backend - -After executing the `terraform init` command, you must configure the Terraform backend -and the CI YAML file: - -1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) - by adding the following code block in a `.tf` file (such as `backend.tf`) to - define the remote backend: - - ```hcl - terraform { - backend "http" { - } - } - ``` - -1. In the root directory of your project repository, configure a - `.gitlab-ci.yml` file. This example uses a pre-built image which includes a - `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab - Terraform Images project](https://gitlab.com/gitlab-org/terraform-images). - - ```yaml - image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest - ``` - -1. In the `.gitlab-ci.yml` file, define some CI/CD variables to ease - development. In this example, `TF_ROOT` is the directory where the Terraform - commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab - instance where this pipeline runs, and the final path segment in `TF_ADDRESS` - is the name of the Terraform state. Projects may have multiple states, and - this name is arbitrary, so in this example we set it to `example-production` - which corresponds with the directory we're using as our `TF_ROOT`, and we - ensure that the `.terraform` directory is cached between jobs in the pipeline - using a cache key based on the state name (`example-production`): - - ```yaml - variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production - - cache: - key: example-production - paths: - - ${TF_ROOT}/.terraform - ``` - -1. In a `before_script`, change to your `TF_ROOT`: - - ```yaml - before_script: - - cd ${TF_ROOT} - - stages: - - prepare - - validate - - build - - deploy - - init: - stage: prepare - script: - - gitlab-terraform init - - validate: - stage: validate - script: - - gitlab-terraform validate - - plan: - stage: build - script: - - gitlab-terraform plan - - gitlab-terraform plan-json - artifacts: - name: plan - paths: - - ${TF_ROOT}/plan.cache - reports: - terraform: ${TF_ROOT}/plan.json - - apply: - stage: deploy - environment: - name: production - script: - - gitlab-terraform apply - dependencies: - - plan - when: manual - only: - - master - ``` - -1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline - runs the `gitlab-terraform init`, `gitlab-terraform validate`, and - `gitlab-terraform plan` commands. - -The output from the above `terraform` commands should be viewable in the job logs. - -WARNING: -Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. -Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan -includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly -recommends encrypting plan output or modifying the project visibility settings. - -### Example project - -See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 in a custom VPC. - -## Using a GitLab managed Terraform state backend as a remote data source - -You can use a GitLab-managed Terraform state as a -[Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html). -To use your existing Terraform state backend as a data source, provide the following details -as [Terraform input variables](https://www.terraform.io/docs/language/values/variables.html): - -- **address**: The URL of the remote state backend you want to use as a data source. - For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. -- **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../profile/personal_access_tokens.md) for - authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. -- **password**: The password to authenticate with the data source. If you are using a Personal Access Token for - authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI/CD variable. - -An example setup is shown below: - -1. Create a file named `example.auto.tfvars` with the following contents: - - ```plaintext - example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> - example_username=<GitLab username> - example_access_token=<GitLab Personal Access Token> - ``` - -1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): - - ```hcl - data "terraform_remote_state" "example" { - backend = "http" - - config = { - address = var.example_remote_state_address - username = var.example_username - password = var.example_access_token - } - } - ``` - -Outputs from the data source can now be referenced in your Terraform resources -using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. - -You need at least the [Developer role](../permissions.md) in the target project -to read the Terraform state. - -## Migrating to GitLab Managed Terraform state - -Terraform supports copying the state when the backend is changed or -reconfigured. This can be useful if you need to migrate from another backend to -GitLab managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab Managed Terraform state. - -The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab Managed Terraform state from a different state storage backend. - -### Setting up the initial backend - -```shell -PROJECT_ID="<gitlab-project-id>" -TF_USERNAME="<gitlab-username>" -TF_PASSWORD="<gitlab-personal-access-token>" -TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name" - -terraform init \ - -backend-config=address=${TF_ADDRESS} \ - -backend-config=lock_address=${TF_ADDRESS}/lock \ - -backend-config=unlock_address=${TF_ADDRESS}/lock \ - -backend-config=username=${TF_USERNAME} \ - -backend-config=password=${TF_PASSWORD} \ - -backend-config=lock_method=POST \ - -backend-config=unlock_method=DELETE \ - -backend-config=retry_wait_min=5 -``` - -```plaintext -Initializing the backend... - -Successfully configured the backend "http"! Terraform will automatically -use this backend unless the backend configuration changes. - -Initializing provider plugins... - -Terraform has been successfully initialized! - -You may now begin working with Terraform. Try running "terraform plan" to see -any changes that are required for your infrastructure. All Terraform commands -should now work. - -If you ever set or change modules or backend configuration for Terraform, -rerun this command to reinitialize your working directory. If you forget, other -commands will detect it and remind you to do so if necessary. -``` - -### Changing the backend - -Now that `terraform init` has created a `.terraform/` directory that knows where -the old state is, you can tell it about the new location: - -```shell -TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" - -terraform init \ - -backend-config=address=${TF_ADDRESS} \ - -backend-config=lock_address=${TF_ADDRESS}/lock \ - -backend-config=unlock_address=${TF_ADDRESS}/lock \ - -backend-config=username=${TF_USERNAME} \ - -backend-config=password=${TF_PASSWORD} \ - -backend-config=lock_method=POST \ - -backend-config=unlock_method=DELETE \ - -backend-config=retry_wait_min=5 -``` - -```plaintext -Initializing the backend... -Backend configuration changed! - -Terraform has detected that the configuration specified for the backend -has changed. Terraform will now check for existing state in the backends. - - -Acquiring state lock. This may take a few moments... -Do you want to copy existing state to the new backend? - Pre-existing state was found while migrating the previous "http" backend to the - newly configured "http" backend. No existing state was found in the newly - configured "http" backend. Do you want to copy this state to the new "http" - backend? Enter "yes" to copy and "no" to start with an empty state. - - Enter a value: yes - - -Successfully configured the backend "http"! Terraform will automatically -use this backend unless the backend configuration changes. - -Initializing provider plugins... - -Terraform has been successfully initialized! - -You may now begin working with Terraform. Try running "terraform plan" to see -any changes that are required for your infrastructure. All Terraform commands -should now work. - -If you ever set or change modules or backend configuration for Terraform, -rerun this command to reinitialize your working directory. If you forget, other -commands will detect it and remind you to do so if necessary. -``` - -If you type `yes`, it copies your state from the old location to the new -location. You can then go back to running it in GitLab CI/CD. - -## Managing state files - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. - -Users with Developer and greater [permissions](../permissions.md) can view the -state files attached to a project at **Infrastructure > Terraform**. Users with the -Maintainer role can perform commands on the state files. The user interface -contains these fields: - - - -- **Name**: The name of the environment, with a locked (**{lock}**) icon if the - state file is locked. -- **Pipeline**: A link to the most recent pipeline and its status. -- **Details**: Information about when the state file was created or changed. -- **Actions**: Actions you can take on the state file, including copying the `terraform init` command, - downloading, locking, unlocking, or [removing](#remove-a-state-file) the state file and versions. - -NOTE: -Additional improvements to the -[graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563) -are planned. - -## Remove a state file - -Users with Maintainer and greater [permissions](../permissions.md) can use the -following options to remove a state file: - -- **GitLab UI**: Go to **Infrastructure > Terraform**. In the **Actions** column, - click the vertical ellipsis (**{ellipsis_v}**) button and select - **Remove state file and versions**. -- **GitLab REST API**: You can remove a state file by making a request to the - REST API. For example: - - ```shell - curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>" - ``` - -- [GitLab GraphQL API](#remove-a-state-file-with-the-gitlab-graphql-api). - -### Remove a state file with the GitLab GraphQL API - -You can remove a state file by making a GraphQL API request. For example: - -```shell -mutation deleteState { - terraformStateDelete(input: { id: "<global_id_for_the_state>" }) { - errors - } -} -``` - -You can obtain the `<global_id_for_the_state>` by querying the list of states: - -```shell -query ProjectTerraformStates { - project(fullPath: "<your_project_path>") { - terraformStates { - nodes { - id - name - } - } - } -} -``` - -For those new to the GitLab GraphQL API, read -[Getting started with GitLab GraphQL API](../../api/graphql/getting_started.md). +<!-- This redirect file can be deleted after <2021-11-26>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 5f51286cf7f..20cd30b6110 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -16,8 +16,8 @@ projects. To view the instance level Kubernetes clusters: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Kubernetes**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Kubernetes**. ## Cluster precedence diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index d3e913edfda..dc08baaf731 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -297,9 +297,6 @@ dependency. You can install a package from the scope of your instance or your pr If multiple packages have the same recipe, when you install a package, the most recently-published package is retrieved. -WARNING: -Project-level packages [cannot be downloaded currently](https://gitlab.com/gitlab-org/gitlab/-/issues/270129). - Conan packages are often installed as dependencies by using the `conanfile.txt` file. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 18b86c4a357..1db2165cd5d 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -154,7 +154,7 @@ To use CI/CD to authenticate, you can use: docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY ``` -- A [CI job token](../../../ci/triggers/index.md#ci-job-token). +- A [CI job token](../../../ci/jobs/ci_job_token.md). ```shell docker login -u $CI_JOB_USER -p $CI_JOB_TOKEN $CI_REGISTRY @@ -747,6 +747,8 @@ The **Packages & Registries > Container Registry** entry is removed from the pro ## Change visibility of the Container Registry +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18792) in GitLab 14.2. + By default, the Container Registry is visible to everyone with access to the project. You can, however, change the visibility of the Container Registry for a project. @@ -863,6 +865,18 @@ these steps: echo -n "" > list_o_tags.out; for i in {1..N}; do curl --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags?per_page=100&page=${i}" | jq '.[].name' | sed 's:^.\(.*\).$:\1:' >> list_o_tags.out; done ``` + If you have Rails console access, you can enter the following commands to retrieve a list of tags limited by date: + + ```shell + output = File.open( "/tmp/list_o_tags.out","w" ) + Project.find(<Project_id>).container_repositories.find(<container_repo_id>).tags.each do |tag| + output << tag.name + "\n" if tag.created_at < 1.month.ago + end;nil + output.close + ``` + + This set of commands creates a `/tmp/list_o_tags.out` file listing all tags with a `created_at` date of older than one month. + 1. Remove from the `list_o_tags.out` file any tags that you want to keep. Here are some example `sed` commands for this. Note that these commands are simply examples. You may change them to best suit your needs: diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 789902c03e3..29641380753 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -67,7 +67,7 @@ To create a distribution, publish a package, or install a private package, you n following: - [Personal access token](../../../api/index.md#personalproject-access-tokens) -- [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token) +- [CI/CD job token](../../../ci/jobs/ci_job_token.md) - [Deploy token](../../project/deploy_tokens/index.md) ## Create a Distribution @@ -78,7 +78,7 @@ packages on the group level, create a distribution with the same `codename`. To create a project-level distribution: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=unstable +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=unstable" ``` Example response: diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index c76b0a6810f..ad25ec7edbf 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -94,8 +94,11 @@ Proxy. > - The prefix for group names containing uppercase letters was [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54559) in GitLab 13.10. Runners log in to the Dependency Proxy automatically. To pull through -the Dependency Proxy, use the `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` -[predefined CI/CD variable](../../../ci/variables/predefined_variables.md): +the Dependency Proxy, use one of the [predefined variables](../../../ci/variables/predefined_variables.md): + +- `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` pulls through the top-level group. +- `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX` pulls through the subgroup, or direct group the + project exists in. Example pulling the latest alpine image: @@ -109,7 +112,10 @@ There are other additional predefined CI/CD variables you can also use: - `CI_DEPENDENCY_PROXY_USER`: A CI/CD user for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_PASSWORD`: A CI/CD password for logging in to the Dependency Proxy. - `CI_DEPENDENCY_PROXY_SERVER`: The server for logging in to the Dependency Proxy. -- `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`: The image prefix for pulling images through the Dependency Proxy. +- `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`: the image prefix for pulling images through the + dependency proxy from the top-level group. +- `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX`: the image prefix for pulling images through the + dependency proxy from the direct group or subgroup that the project belongs to. `CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` include the server port. If you explicitly include the Dependency Proxy diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index aa6373b66cb..6d35273ae6f 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -21,13 +21,13 @@ Publish generic files, like release binaries, in your project's Package Registry ## Authenticate to the Package Registry To authenticate to the Package Registry, you need either a [personal access token](../../../api/index.md#personalproject-access-tokens), -[CI/CD job token](../../../api/index.md#gitlab-cicd-job-token), or [deploy token](../../project/deploy_tokens/index.md). +[CI/CD job token](../../../ci/jobs/ci_job_token.md), or [deploy token](../../project/deploy_tokens/index.md). In addition to the standard API authentication mechanisms, the generic package API allows authentication with HTTP Basic authentication for use with tools that do not support the other available mechanisms. The `user-id` is not checked and may be any value, and the `password` must be either a [personal access token](../../../api/index.md#personalproject-access-tokens), -a [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token), or a [deploy token](../../project/deploy_tokens/index.md). +a [CI/CD job token](../../../ci/jobs/ci_job_token.md), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file @@ -125,7 +125,7 @@ Example request that uses HTTP Basic authentication: ```shell curl --user "user:<your_access_token>" \ - https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt" ``` ## Publish a generic package by using CI/CD diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index f98fc352ab5..2d984d76b97 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -25,9 +25,9 @@ Read more in the Helm documentation about these topics: To authenticate to the Helm repository, you need either: -- A [personal access token](../../../api/index.md#personalproject-access-tokens). -- A [deploy token](../../project/deploy_tokens/index.md). -- A [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token). +- A [personal access token](../../../api/index.md#personalproject-access-tokens) with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. +- A [CI/CD job token](../../../ci/jobs/ci_job_token.md). ## Publish a package @@ -35,24 +35,35 @@ NOTE: You can publish Helm charts with duplicate names or versions. If duplicates exist, GitLab always returns the chart with the latest version. -Once built, a chart can be uploaded to the `stable` channel with `curl` or `helm-push`: +Once built, a chart can be uploaded to the desired channel with `curl` or `helm-push`: - With `curl`: ```shell curl --request POST \ --form 'chart=@mychart-0.1.0.tgz' \ - --user <username>:<personal_access_token> \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/api/stable/charts + --user <username>:<access_token> \ + https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/api/<channel>/charts ``` + - `<username>`: the GitLab username or the deploy token username. + - `<access_token>`: the personal access token or the deploy token. + - `<project_id>`: the project ID (like `42`) or the + [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project (like `group%2Fproject`). + - `<channel>`: the name of the channel (like `stable`). + - With the [`helm-push`](https://github.com/chartmuseum/helm-push/#readme) plugin: ```shell - helm repo add --username <username> --password <personal_access_token> project-1 https://gitlab.example.com/api/v4/projects/1/packages/helm/stable + helm repo add --username <username> --password <access_token> project-1 https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/<channel> helm push mychart-0.1.0.tgz project-1 ``` + - `<username>`: the GitLab username or the deploy token username. + - `<access_token>`: the personal access token or the deploy token. + - `<project_id>`: the project ID (like `42`). + - `<channel>`: the name of the channel (like `stable`). + ## Use CI/CD to publish a Helm package To publish a Helm package automated through [GitLab CI/CD](../../../ci/index.md), you can use @@ -69,18 +80,31 @@ stages: upload: stage: upload script: - - 'curl --request POST --user gitlab-ci-token:$CI_JOB_TOKEN --form "chart=@mychart-0.1.0.tgz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/helm/api/stable/charts"' + - 'curl --request POST --user gitlab-ci-token:$CI_JOB_TOKEN --form "chart=@mychart-0.1.0.tgz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/helm/api/<channel>/charts"' ``` +- `<username>`: the GitLab username or the deploy token username. +- `<access_token>`: the personal access token or the deploy token. +- `<channel>`: the name of the channel (like `stable`). + ## Install a package +NOTE: +When requesting a package, GitLab considers only the 300 most recent packages created. +For each package, only the most recent package file is returned. + To install the latest version of a chart, use the following command: ```shell -helm repo add --username <username> --password <personal_access_token> project-1 https://gitlab.example.com/api/v4/projects/1/packages/helm/stable +helm repo add --username <username> --password <access_token> project-1 https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/<channel> helm install my-release project-1/mychart ``` +- `<username>`: the GitLab username or the deploy token username. +- `<access_token>`: the personal access token or the deploy token. +- `<project_id>`: the project ID (like `42`). +- `<channel>`: the name of the channel (like `stable`). + If the repo has previously been added, you may need to run: ```shell diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index e3b9563a143..7f101adccad 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Terraform module registry **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. Publish Terraform modules in your project's Infrastructure Registry, then reference them using GitLab as a Terraform module registry. @@ -16,7 +16,7 @@ as a Terraform module registry. To authenticate to the Terraform module registry, you need either: - A [personal access token](../../../api/index.md#personalproject-access-tokens) with at least `read_api` rights. -- A [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token). +- A [CI/CD job token](../../../ci/jobs/ci_job_token.md). ## Publish a Terraform Module @@ -41,6 +41,10 @@ PUT /projects/:id/packages/terraform/modules/:module_name/:module_system/:module Provide the file content in the request body. +Note that, in the following example, the request must end with `/file`. +If you send a request ending with something else, it results in a 404 +error `{"error":"404 Not Found"}`. + Example request using a personal access token: ```shell diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 81681ec1303..f240a9fd407 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -41,23 +41,23 @@ For more information, see [projects members documentation](project/members/index The following table lists project permissions available for each role: -<!-- Keep this table sorted: first, by minimum role, then alphabetically. --> +<!-- Keep this table sorted: By topic first, then by minimum role, then alphabetically. --> | Action | Guest | Reporter | Developer | Maintainer | Owner | |-------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|-------| | [Analytics](analytics/index.md):<br>View issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | | [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) **(ULTIMATE)** | | | | | ✓ | | [CI/CD](../ci/README.md):<br>Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | [CI/CD](../ci/README.md):<br>View a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | @@ -74,13 +74,22 @@ The following table lists project permissions available for each role: | [CI/CD](../ci/README.md):<br>Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | | [CI/CD](../ci/README.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals) | | | | ✓ | ✓ | | [CI/CD](../ci/README.md):<br>Delete pipelines | | | | | ✓ | +| [Clusters](project/clusters/index.md):<br>View pod logs | | | ✓ | ✓ | ✓ | +| [Clusters](project/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Remove a container registry image | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Update container registry | | | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Add Labels | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Assign | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Create | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set weight | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set weight | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | @@ -89,6 +98,10 @@ The following table lists project permissions available for each role: | [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | @@ -97,26 +110,38 @@ The following table lists project permissions available for each role: | [Merge requests](project/merge_requests/index.md):<br>Create | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage merge approval rules (project settings) | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Pull package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Publish package | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Delete package | | | | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*10*) | ✓ (*10*) | ✓ (*10*) | ✓ | ✓ | | [Projects](project/index.md):<br>View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View Requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View project statistics | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View project statistics | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | | [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*11*) | ✓ | ✓ | | [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (14) | ✓ | +| [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | @@ -133,6 +158,27 @@ The following table lists project permissions available for each role: | [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | | [Projects](project/index.md):<br>Rename project | | | | | ✓ | | [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | +| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*5*) | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to protected branches | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | +| [Repository](project/repository/index.md):<br>Force push to protected branches (*4*) | | | | | | +| [Repository](project/repository/index.md):<br>Remove protected branches (*4*) | | | | | | +| [Requirements Management](project/requirements/index.md):<br>Archive / reopen **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Create / edit **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Import / export **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | @@ -143,60 +189,17 @@ The following table lists project permissions available for each role: | [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | -| Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View [Releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | -| View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | -| View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| Archive [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| Archive/reopen requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Create new [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| Create/edit requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Import/export requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| Move [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| Pull [packages](packages/index.md) | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| Reopen [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | -| See a commit status | | ✓ | ✓ | ✓ | ✓ | -| View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | -| View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| Add tags | | | ✓ | ✓ | ✓ | -| Create new branches | | | ✓ | ✓ | ✓ | -| Create or update commit status | | | ✓ (*5*) | ✓ | ✓ | -| Create/edit/delete [releases](project/releases/index.md)| | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | -| Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | -| Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| Force push to non-protected branches | | | ✓ | ✓ | ✓ | -| Manage Feature Flags **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | -| Push to non-protected branches | | | ✓ | ✓ | ✓ | -| Read Terraform state | | | ✓ | ✓ | ✓ | -| Remove a container registry image | | | ✓ | ✓ | ✓ | -| Remove non-protected branches | | | ✓ | ✓ | ✓ | -| Rewrite/remove Git tags | | | ✓ | ✓ | ✓ | -| Update a container registry | | | ✓ | ✓ | ✓ | -| View Pods logs | | | ✓ | ✓ | ✓ | -| Configure project hooks | | | | ✓ | ✓ | -| Delete [packages](packages/index.md) | | | | ✓ | ✓ | -| Enable/disable branch protection | | | | ✓ | ✓ | -| Enable/disable tag protections | | | | ✓ | ✓ | -| Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| Manage clusters | | | | ✓ | ✓ | -| Manage Error Tracking | | | | ✓ | ✓ | -| Manage GitLab Pages | | | | ✓ | ✓ | -| Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | -| Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | -| Manage Terraform state | | | | ✓ | ✓ | -| Push to protected branches | | | | ✓ | ✓ | -| Remove GitLab Pages | | | | ✓ | ✓ | -| Turn on/off protected branch push for developers | | | | ✓ | ✓ | -| Remove fork relationship | | | | | ✓ | -| Force push to protected branches (*4*) | | | | | | -| Remove protected branches (*4*) | | | | | | - -1. Guest users are able to perform this action on public and internal projects, but not private projects. This doesn't apply to [external users](#external-users) where explicit access must be given even if the project is internal. +| [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | +| [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | + +1. On self-managed GitLab instances, guest users are able to perform this action only on + public and internal projects (not on private projects). [External users](#external-users) + must be given explicit access even if the project is internal. For GitLab.com, see the + [GitLab.com visibility settings](gitlab_com/index.md#visibility-settings). 1. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves. 1. If **Public pipelines** is enabled in **Project Settings > CI/CD**. 1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). @@ -242,10 +245,10 @@ to learn more. Find the current permissions on the Value Stream Analytics dashboard, as described in [related documentation](analytics/value_stream_analytics.md#permissions). -### Issue Board permissions +### Issue board permissions -Find the current permissions for interacting with the Issue Board feature in the -[Issue Boards permissions page](project/issue_board.md#permissions). +Find the current permissions for interacting with the issue board feature in the +[issue boards permissions page](project/issue_board.md#permissions). ### File Locking permissions **(PREMIUM)** @@ -280,6 +283,7 @@ The following table lists group permissions available for each role: |--------------------------------------------------------|-------|----------|-----------|------------|-------| | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | | Edit SAML SSO Billing **(PREMIUM SAAS)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | +| Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View group wiki pages **(PREMIUM)** | ✓ (6) | ✓ | ✓ | ✓ | ✓ | @@ -301,7 +305,6 @@ The following table lists group permissions available for each role: | Create/edit/delete iterations | | | ✓ | ✓ | ✓ | | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | | Enable/disable a dependency proxy | | | ✓ | ✓ | ✓ | -| Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | | Purge the dependency proxy for a group | | | | | ✓ | | Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | @@ -314,6 +317,7 @@ The following table lists group permissions available for each role: | View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | | Administer project compliance frameworks | | | | | ✓ | | Create/Delete group deploy tokens | | | | | ✓ | +| Change group visibility level | | | | | ✓ | | Delete group | | | | | ✓ | | Delete group epic **(PREMIUM)** | | | | | ✓ | | Disable notification emails | | | | | ✓ | @@ -381,7 +385,7 @@ An administrator can flag a user as external by either of the following methods: - [Through the API](../api/users.md#user-modification). - Using the GitLab UI: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. There, you can find the option to flag the user as external. @@ -393,7 +397,7 @@ and [LDAP groups](../administration/auth/ldap/index.md#external-groups). By default, new users are not set as external users. This behavior can be changed by an administrator: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 972414dbf0b..3cc56cc47e6 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -26,7 +26,7 @@ their own accounts by either: As an Admin user, you can manually create users: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users** (`/admin/users`). 1. Select **New user**. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index f6af373e295..41b4e508c38 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -21,14 +21,14 @@ As a user, to delete your own account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. Select **Delete account**. ## As an administrator As an administrator, to delete a user account: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select a user. 1. Under the **Account** tab, select: diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 597170540ab..14e6f4dad3a 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -35,8 +35,19 @@ still access your account if you lose your U2F / WebAuthn device. ## Enabling 2FA -There are multiple ways to enable two-factor authentication: by using a one-time -password authenticator or a U2F / WebAuthn device. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35102) in GitLab 14.3, account email confirmation required. + +There are multiple ways to enable two-factor authentication (2FA): + +- Using a one-time password authenticator. +- Using a U2F / WebAuthn device. + +In GitLab 14.3 and later, your account email must be confirmed to enable two-factor authentication. + +FLAG: +On self-managed GitLab, account email confirmation requirement is enabled. To disable this +restriction, ask an administrator to +[disable the `ensure_verified_primary_email_for_2fa` flag](../../../administration/feature_flags.md). ### One-time password @@ -377,7 +388,7 @@ have lost your code generation device) you can: - [Use a saved recovery code](#use-a-saved-recovery-code). - [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh). - [Regenerate 2FA recovery codes](#regenerate-2fa-recovery-codes). -- [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account). +- [Have 2FA disabled on your account](#have-2fa-disabled-on-your-account). ### Use a saved recovery code @@ -454,12 +465,9 @@ To regenerate 2FA recovery codes, you need access to a desktop browser: NOTE: If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. -### Ask a GitLab administrator to disable two-factor authentication on your account +### Have 2FA disabled on your account -If you cannot use a saved recovery code or generate new recovery codes, ask a -GitLab global administrator to disable two-factor authentication for your -account. This temporarily leaves your account in a less secure state. -Sign in and re-enable two-factor authentication as soon as possible. +If you cannot use a saved recovery code or generate new recovery codes then please submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) requesting that a GitLab global administrator disables two-factor authentication for your account. Please note that only the actual owner of the account can make this request and that disabling this setting will temporarily leave your account in a less secure state. You should therefore sign in and re-enable two-factor authentication as soon as possible. ## Note to GitLab administrators @@ -516,7 +524,7 @@ To avoid the time sync issue, enable time synchronization in the device that gen 1. Go to Settings. 1. Select General. 1. Select Date & Time. - 1. Enable Set Automatically. If it’s already enabled, disable it, wait a few seconds, and re-enable. + 1. Enable Set Automatically. If it's already enabled, disable it, wait a few seconds, and re-enable. <!-- ## Troubleshooting diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index e55b92378bd..25f349d9272 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -18,7 +18,7 @@ To list all active sessions: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Active Sessions**. +1. On the left sidebar, select **Active Sessions**.  @@ -35,7 +35,7 @@ To revoke an active session: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Active Sessions**. +1. On the left sidebar, select **Active Sessions**. 1. Select **Revoke** next to a session. The current session cannot be revoked, as this would sign you out of GitLab. NOTE: diff --git a/doc/user/profile/img/notification_group_settings_v12_8.png b/doc/user/profile/img/notification_group_settings_v12_8.png Binary files differdeleted file mode 100644 index 4aa4c32a260..00000000000 --- a/doc/user/profile/img/notification_group_settings_v12_8.png +++ /dev/null diff --git a/doc/user/profile/img/notification_project_settings_v12_8.png b/doc/user/profile/img/notification_project_settings_v12_8.png Binary files differdeleted file mode 100644 index 9b8837a4ef4..00000000000 --- a/doc/user/profile/img/notification_project_settings_v12_8.png +++ /dev/null diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 2c76b46249e..24006e6f875 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -31,7 +31,7 @@ To change your password: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Password**. +1. On the left sidebar, select **Password**. 1. In the **Current password** field, enter your current password. 1. In the **New password** and **Password confirmation** field, enter your new password. 1. Select **Save password**. @@ -55,10 +55,21 @@ To change your username: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Account**. +1. On the left sidebar, select **Account**. 1. In the **Change username** section, enter a new username as the path. 1. Select **Update username**. +## Add emails to your user profile + +To add new email to your account: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Emails**. +1. In the **Email** box, enter the new email. +1. Select **Add email address**. +1. Verify your email address with the verification email received. + ## Make your user profile page private You can make your user profile visible to only you and GitLab administrators. @@ -219,6 +230,7 @@ To set your time zone: A commit email is an email address displayed in every Git-related action carried out through the GitLab interface. Any of your own verified email addresses can be used as the commit email. +Your primary email is used by default. To change your commit email: diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 17b4251662e..aaa311a4097 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -5,57 +5,72 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Notification Emails **(FREE)** +# Notification emails **(FREE)** -GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications -enabled, you can receive updates about activity in issues, merge requests, epics, and designs. -Notifications are sent via email. +Stay informed about what's happening in GitLab with email notifications. +You can receive updates about activity in issues, merge requests, epics, and designs. -For the tool that enables GitLab administrators to send messages to users, read +For the tool that GitLab administrators can use to send messages to users, read [Email from GitLab](../../tools/email.md). -## Receiving notifications +## Receive notifications You receive notifications for one of the following reasons: -- You participate in an issue, merge request, epic, or design. In this context, _participate_ means comment, or edit. -- You [enable notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). +- You participate in an issue, merge request, epic, or design. In this context, _participate_ means + comment or edit. +- You've [enabled notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). - You configured notifications at the [project](#project-notifications) and/or [group](#group-notifications) level. While notifications are enabled, you receive notification of actions occurring in that issue, merge request, or epic. NOTE: -Notifications can be blocked by an administrator, preventing them from being sent. +Administrators can block notifications, preventing them from being sent. -## Tuning your notifications +## Tune your notifications -The number of notifications can be overwhelming. GitLab allows you to tune the notifications you receive. +Getting many notifications can be overwhelming. You can tune the notifications you receive. For example, you might want to be notified about all activity in a specific project. -For other projects, you only need to be notified when you are mentioned by name. +For other projects, you only want to be notified when you are mentioned by name. -You can tune the notifications you receive by combining your notification settings: +You can tune the notifications you receive by changing your notification settings: - [Global notification settings](#global-notification-settings) - [Notification scope](#notification-scope) - [Notification levels](#notification-levels) -## Editing notification settings +## Edit notification settings + +These notification settings apply only to you. They do not affect the notifications received by +anyone else in the same project or group. To edit your notification settings: 1. In the top-right corner, select your avatar. 1. Select **Preferences**. -1. In the left sidebar, select **Notifications**. +1. On the left sidebar, select **Notifications**. 1. Edit the desired notification settings. Edited settings are automatically saved and enabled. -These notification settings apply only to you. They do not affect the notifications received by anyone else in the same project or group. +## Notification scope + +You can tune the scope of your notifications by selecting different notification levels for each project and group. -## Global notification settings +Notification scope is applied from the broadest to most specific levels: + +- **Global (default)**: Your global, or _default_, notification level applies if you + have not selected a notification level for the project or group in which the activity occurred. +- **Group**: For each group, you can select a notification level. Your group setting + overrides your default setting. +- **Project**: For each project, you can select a notification level. Your project + setting overrides the group setting. + +### Global notification settings Your **Global notification settings** are the default settings unless you select different values for a project or a group. - **Notification email**: the email address your notifications are sent to. + Defaults to your primary email address. - **Receive product marketing emails**: select this checkbox to receive [periodic emails](#product-marketing-emails) about GitLab features. - **Global notification level**: the default [notification level](#notification-levels) @@ -65,95 +80,78 @@ different values for a project or a group.  -### Notification scope - -You can tune the scope of your notifications by selecting different notification levels for each project and group. +### Group notifications -Notification scope is applied in order of precedence (highest to lowest): - -- **Project**: For each project, you can select a notification level. Your project - setting overrides the group setting. -- **Group**: For each group, you can select a notification level. Your group setting - overrides your default setting. -- **Global (default)**: Your global, or _default_, notification level applies if you - have not selected a notification level for the project or group in which the activity occurred. - -#### Project notifications - -You can select a notification level for each project to help you closely monitor activity in select projects. +You can select a notification level and email address for each group. - +#### Group notification level -To select a notification level for a project, use either of these methods: +To select a notification level for a group, use either of these methods: 1. In the top-right corner, select your avatar. 1. Select **Preferences**. -1. In the left sidebar, select **Notifications**. -1. Locate the project in the **Projects** section. +1. On the left sidebar, select **Notifications**. +1. Locate the project in the **Groups** section. 1. Select the desired [notification level](#notification-levels). Or: -1. Go to your project. -1. Select the notification dropdown, marked with a bell icon (**{notifications}**). +1. On the top bar, select **Menu > Groups** and find your group. +1. Select the notification dropdown, next to the bell icon (**{notifications}**). 1. Select the desired [notification level](#notification-levels). -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demonstration of how to be notified when a new release is available, see [Notification for releases](https://www.youtube.com/watch?v=qyeNkGgqmH4). +#### Group notification email address -#### Group notifications +> Introduced in GitLab 12.0 -You can select a notification level and email address for each group. +You can select an email address to receive notifications for each group you belong to. This could be useful, for example, if you work freelance, and want to keep email about clients' projects separate. - +1. In the top-right corner, select your avatar. +1. Select **Preferences**. +1. On the left sidebar, select **Notifications**. +1. Locate the project in the **Groups** section. +1. Select the desired email address. -##### Group notification level +### Project notifications -To select a notification level for a group, use either of these methods: +You can select a notification level for each project to help you closely monitor activity in select projects. + +To select a notification level for a project, use either of these methods: 1. In the top-right corner, select your avatar. 1. Select **Preferences**. -1. In the left sidebar, select **Notifications**. -1. Locate the project in the **Groups** section. +1. On the left sidebar, select **Notifications**. +1. Locate the project in the **Projects** section. 1. Select the desired [notification level](#notification-levels). ---- +Or: -1. Go to your group. -1. Select the notification dropdown, marked with a bell icon (**{notifications}**). +1. On the top bar, select **Menu > Projects** and find your project. +1. Select the notification dropdown, next to the bell icon (**{notifications}**). 1. Select the desired [notification level](#notification-levels). -##### Group notification email address - -> Introduced in GitLab 12.0 - -You can select an email address to receive notifications for each group you belong to. This could be useful, for example, if you work freelance, and want to keep email about clients' projects separate. - -1. In the top-right corner, select your avatar. -1. Select **Preferences**. -1. In the left sidebar, select **Notifications**. -1. Locate the project in the **Groups** section. -1. Select the desired email address. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +To learn how to be notified when a new release is available, see [Notification for releases](https://www.youtube.com/watch?v=qyeNkGgqmH4). ### Notification levels For each project and group you can select one of the following levels: -| Level | Description | -|:------------|:------------| -| Global | Your global settings apply. | -| Watch | Receive notifications for any activity. | +| Level | Description | +| ----------- | ----------------------------------------------------------- | +| Global | Your global settings apply. | +| Watch | Receive notifications for any activity. | | On mention | Receive notifications when [mentioned](../project/issues/issue_data_and_actions.md#mentions) in a comment. | | Participate | Receive notifications for threads you have participated in. | -| Disabled | Turns off notifications. | -| Custom | Receive notifications for custom selected events. | +| Disabled | Turns off notifications. | +| Custom | Receive notifications for custom selected events. | ### Product marketing emails You can receive emails that teach you about various GitLab features. This is enabled by default. -To opt out, [edit your notification settings](#editing-notification-settings) and clear the +To opt out, [edit your notification settings](#edit-notification-settings) and clear the **Receive product marketing emails** checkbox. Disabling these emails does not disable all emails. @@ -173,51 +171,56 @@ for all users. Users are notified of the following events: +<!-- The table is sorted first by recipient, then alphabetically. --> + | Event | Sent to | Settings level | |------------------------------|---------------------|------------------------------| -| New SSH key added | User | Security email, always sent. | -| SSH key has expired | User | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12 | -| New email added | User | Security email, always sent. | +| New release | Project members | Custom notification | +| Project moved | Project members (1) | (1) not disabled | | Email changed | User | Security email, always sent. | +| Group access level changed | User | Sent when user group access level is changed | +| New email added | User | Security email, always sent. | +| New SAML/SCIM user provisioned | User | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 | +| New SSH key added | User | Security email, always sent. | +| New user created | User | Sent on user creation, except for OmniAuth (LDAP)| | Password changed | User | Security email, always sent when user changes their own password | | Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user | -| Two-factor authentication disabled | User | Security email, always sent. | -| New user created | User | Sent on user creation, except for OmniAuth (LDAP)| -| New SAML/SCIM user provisioned | User | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 | -| User added to project | User | Sent when user is added to project | +| Personal access tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User | Security email, always sent. | +| Personal access tokens have expired | User | Security email, always sent. | | Project access level changed | User | Sent when user project access level is changed | +| SSH key has expired | User | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12 | +| Two-factor authentication disabled | User | Security email, always sent. | | User added to group | User | Sent when user is added to group | -| Group access level changed | User | Sent when user group access level is changed | -| Personal Access Tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User | Security email, always sent. | -| Personal Access Tokens have expired | User | Security email, always sent. | -| Project moved | Project members (1) | (1) not disabled | -| New release | Project members | Custom notification | +| User added to project | User | Sent when user is added to project | ## Notifications on issues, merge requests, and epics -To enable notifications on one specific issue, merge request or epic, you need to enable the **Notifications** toggle in the right sidebar. +To enable notifications on a specific issue, merge request, or epic, you must turn on the +**Notifications** toggle in the right sidebar. -- **Enable**: If you are not a participant in the discussion on that issue, but - want to receive notifications on each update, subscribe to it. -- **Disable**: If you are receiving notifications for updates to that issue but no - longer want to receive them, unsubscribe from it. +- To subscribe, **turn on** if you are not a participant in the discussion, but want to receive + notifications on each update. +- To unsubscribe, **turn off** if you are receiving notifications for updates but no longer want to + receive them, unsubscribe from it. -Disabling this toggle only unsubscribes you from updates related to this issue, merge request, or epic. +Turning this toggle off only unsubscribes you from updates related to this issue, merge request, or epic. Learn how to [opt out of all emails from GitLab](#opt-out-of-all-gitlab-emails). -Enabling this notification on an epic doesn't automatically subscribe you to the issues linked +Turning notifications on in an epic doesn't automatically subscribe you to the issues linked to the epic. For most events, the notification is sent to: - Participants: - The author and assignee of the issue/merge request. - - Authors of comments on the issue/merge request. - - Anyone mentioned by `@username` in the title or description of the issue, merge request or epic. - - Anyone with notification level "Participating" or higher that is mentioned by `@username` in any of the comments on the issue, merge request, or epic. + - Authors of comments. + - Anyone [mentioned](../project/issues/issue_data_and_actions.md#mentions) by username in the title + or description of the issue, merge request or epic. + - Anyone with notification level "Participating" or higher that is mentioned by their username in + any of the comments on the issue, merge request, or epic. - Watchers: users with notification level "Watch". - Subscribers: anyone who manually subscribed to the issue, merge request, or epic. -- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below. +- Custom: Users with notification level "custom" who turned on notifications for any of the events in the following table. NOTE: To minimize the number of notifications that do not require any action, in @@ -259,16 +262,17 @@ If the title or description of an issue or merge request is changed, notifications are sent to any **new** mentions by `@username` as if they had been mentioned in the original text. -You don't receive notifications for issues, merge requests or milestones created -by yourself (except when an issue is due). You only receive automatic -notifications when somebody else comments or adds changes to the ones that -you've created or mentions you. +By default, you don't receive notifications for issues, merge requests, or epics created +by yourself. You only receive notifications when somebody else comments or adds changes to the ones +that you've created or mentions you, or when an issue is due soon. +To always receive notifications on your own issues and so on, you must turn on +[notifications about your own activity](#global-notification-settings). If an open merge request becomes unmergeable due to conflict, its author is notified about the cause. -If a user has also set the merge request to automatically merge once pipeline succeeds, +If a user has also set the merge request to automatically merge when pipeline succeeds, then that user is also notified. -## Design email notifications +## Notifications on designs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217095) in GitLab 13.6. @@ -284,7 +288,7 @@ The participants are: If you no longer wish to receive any email notifications: -1. [Go to the Notifications settings page.](#editing-notification-settings) +1. [Go to the Notifications settings page.](#edit-notification-settings) 1. Clear the **Receive product marketing emails** checkbox. 1. Set your **Global notification level** to **Disabled**. 1. Clear the **Receive notifications about your own activity** checkbox. @@ -295,7 +299,7 @@ On self-managed installations, even after doing this, your instance administrato [can still email you](../../tools/email.md). To unsubscribe, select the unsubscribe link in one of these emails. -## Filtering email +## Filter email Notification email messages include GitLab-specific headers. You can filter the notification emails based on the content of these headers to better manage your notifications. For example, you could filter all emails for a specific project where you are being assigned either a merge request or issue. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index c534a630480..bdd49b00a15 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -12,11 +12,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in GitLab 13.3: [Additional notifications for expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/214721). > - Introduced in GitLab 14.1: [Prefill token name and scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/334664). -If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/index.md#personalproject-access-tokens). You can also use a personal access token with Git to authenticate over HTTP. +Personal access tokens can be an alternative to [OAuth2](../../api/oauth2.md) and used to: + +- Authenticate with the [GitLab API](../../api/index.md#personalproject-access-tokens). +- Authenticate with Git using HTTP Basic Authentication. In both cases, you authenticate with a personal access token in place of your password. -Personal access tokens are required when [Two-Factor Authentication (2FA)](account/two_factor_authentication.md) is enabled. +Personal access tokens are: + +- Required when [two-factor authentication (2FA)](account/two_factor_authentication.md) is enabled. +- Used with a GitLab username to authenticate with GitLab features that require usernames. For example, + [GitLab managed Terraform state backend](../infrastructure/iac/terraform_state.md#using-a-gitlab-managed-terraform-state-backend-as-a-remote-data-source) + and [Docker container registry](../packages/container_registry/index.md#authenticate-with-the-container-registry), +- Similar to [project access tokens](../project/settings/project_access_tokens.md), but are attached + to a user rather than a project. + +NOTE: +Though required, GitLab usernames are ignored when authenticating with a personal access token. +There is an [issue for tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/212953) to make GitLab +use the username. For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/index.md#personalproject-access-tokens). @@ -29,7 +44,7 @@ You can create as many personal access tokens as you like. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +1. On the left sidebar, select **Access Tokens**. 1. Enter a name and optional expiry date for the token. 1. Select the [desired scopes](#personal-access-token-scopes). 1. Select **Create personal access token**. @@ -53,7 +68,7 @@ At any time, you can revoke a personal access token. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +1. On the left sidebar, select **Access Tokens**. 1. In the **Active personal access tokens** area, next to the key, select **Revoke**. ## View the last time a token was used @@ -65,7 +80,7 @@ To view the last time a token was used: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **Access Tokens**. +1. On the left sidebar, select **Access Tokens**. 1. In the **Active personal access tokens** area, next to the key, view the **Last Used** date. ## Personal access token scopes diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index cac283f6f18..b4723294438 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -26,7 +26,7 @@ percentage of users are affected and the change can either be fixed or quickly reverted. Leveraging [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments), visualize your canary -deployments right inside the [Deploy Board](deploy_boards.md), without the need to leave GitLab. +deployments right inside the [deploy board](deploy_boards.md), without the need to leave GitLab. ## Use cases @@ -47,9 +47,9 @@ this document. ## Enabling Canary Deployments -Canary deployments require that you properly configure Deploy Boards: +Canary deployments require that you properly configure deploy boards: -1. Follow the steps to [enable Deploy Boards](deploy_boards.md#enabling-deploy-boards). +1. Follow the steps to [enable deploy boards](deploy_boards.md#enabling-deploy-boards). 1. To track canary deployments you need to label your Kubernetes deployments and pods with `track: canary`. To get started quickly, you can use the [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy) template for canary deployments that GitLab provides. @@ -61,13 +61,13 @@ This allows GitLab to discover whether a deployment is stable or canary (tempora Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Pipelines > Environments**. -As the pipeline executes, Deploy Boards clearly mark canary pods, enabling +As the pipeline executes, deploy boards clearly mark canary pods, enabling quick and easy insight into the status of each environment and deployment. -Canary deployments are marked with a yellow dot in the Deploy Board so that you +Canary deployments are marked with a yellow dot in the deploy board so that you can easily notice them. - + ### Advanced traffic control with Canary Ingress @@ -104,17 +104,17 @@ Here's an example setup flow from scratch: #### How to check the current traffic weight on a Canary Ingress -1. Visit the [Deploy Board](../../user/project/deploy_boards.md). +1. Visit the [deploy board](../../user/project/deploy_boards.md). 1. View the current weights on the right.  #### How to change the traffic weight on a Canary Ingress -You can change the traffic weight within your environment's Deploy Board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), +You can change the traffic weight within your environment's deploy board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). -To use your [Deploy Board](../../user/project/deploy_boards.md): +To use your [deploy board](../../user/project/deploy_boards.md): 1. Navigate to **Deployments > Environments** for your project. 1. Set the new weight with the dropdown on the right side. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 7d006247177..f7dd24fcfad 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. WARNING: -Use [Infrastrucure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. +Use [Infrastructure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic Kubernetes Service (EKS). @@ -48,7 +48,7 @@ To create a new EKS cluster: 1. Go to your: - Project's **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - - **Menu >** **{admin}** **Admin > Kubernetes**, for an instance-level cluster. + - **Menu > Admin > Kubernetes**, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. @@ -166,7 +166,7 @@ When you create a new cluster, you have the following settings: | Kubernetes cluster name | Your cluster's name. | | Environment scope | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). | | Service role | The **EKS IAM role** (**role A**). | -| Kubernetes version | The [Kubernetes version](index.md#supported-cluster-versions) for your cluster. | +| Kubernetes version | The [Kubernetes version](../../infrastructure/clusters/connect/index.md#supported-cluster-versions) for your cluster. | | Key pair name | The [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes. | | VPC | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. | | Subnets | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. | @@ -240,7 +240,7 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. In GitLab, on the top bar, select **Menu >** **{admin}** **Admin > Settings > General** and expand the **Amazon EKS** section. +1. In GitLab, on the top bar, select **Menu > Admin > Settings > General** and expand the **Amazon EKS** section. 1. Check **Enable Amazon EKS integration**. 1. Enter your **Account ID**. 1. Enter your [access key and ID](#eks-access-key-and-id). diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index efd480fa3ce..505c493de4e 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -4,11 +4,17 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Add an existing Kubernetes cluster +# Connect existing clusters through cluster certificates If you have an existing Kubernetes cluster, you can add it to a project, group, or instance and benefit from the integration with GitLab. +WARNING: +The process described on this page uses cluster certificates to connect your cluster +to GitLab. Although this method still works, it is **no longer recommended**. +To connect your cluster to GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +instead. **(PREMIUM)** + ## Prerequisites See the prerequisites below to add existing clusters to GitLab. @@ -61,7 +67,7 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - 1. **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + 1. **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Click the **Add existing cluster** tab and fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. @@ -211,7 +217,8 @@ integration to work properly. WARNING: Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a -[security concern](index.md#security-implications), and may not be desirable. +[security concern](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates), +and may not be desirable. To effectively disable RBAC, global permissions can be applied granting full access: diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index a454b4dff99..78d4bce737d 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. WARNING: -Use [Infrastrucure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. +Use [Infrastructure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic Kubernetes Service (EKS). @@ -62,7 +62,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Click **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index fba02183be5..4f2bc5526e0 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -9,11 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. WARNING: -Creating a new cluster through the certificate-based method -is deprecated and no longer recommended. Kubernetes cluster, similar to any other -infrastructure, should be created, updated, maintained using [Infrastructure as Code](../../infrastructure/index.md). -GitLab is developing a built-in capability to create clusters with Terraform. -You can follow along in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/6049). +Creating a new cluster through cluster certificates +is deprecated and no longer recommended. To create a new cluster use +[Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). NOTE: Every new Google Cloud Platform (GCP) account receives @@ -30,29 +28,38 @@ in a few clicks. ## Create new cluster -> The certificate-based method for creating clusters from GitLab was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. + +As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +to **safely create new clusters from GitLab**. -As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/index.md) -to **safely create your new cluster from GitLab**. +Creating clusters from GitLab using cluster certificates is still available on the +GitLab UI but was **deprecated** in GitLab 14.0 and is scheduled for removal in +GitLab 15.0. We don't recommend using this method. -The certificate-based method is **deprecated** and scheduled for removal in -GitLab 15.0. However, you can still use it until then. Through -this method, you can host your cluster in EKS, GKE, on premises, and with other -providers. To host them on premises and with other providers, -use either the EKS or GKE method to guide you through and enter your cluster's -settings manually: +You can create a new cluster hosted in EKS, GKE, on premises, and with other +providers using cluster certificates: - [New cluster hosted on Google Kubernetes Engine (GKE)](add_gke_clusters.md). - [New cluster hosted on Amazon Elastic Kubernetes Service (EKS)](add_eks_clusters.md). +To host them on premises and with other providers, you can use Terraform +or your preferred tool of choice to create and connect a cluster with GitLab. +The [GitLab Terraform provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs/resources/project_cluster) +supports connecting existing clusters using the certificate-based connection method. + ## Add existing cluster -If you already have a cluster and want to integrate it with GitLab, see how to -[add an existing cluster](add_existing_cluster.md). +As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +to connect your cluster to GitLab. + +Alternatively, you can [add an existing cluster](add_existing_cluster.md) +through the certificate-based method, but we don't recommend using this method for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). ## Configure your cluster -As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to configure your cluster. +As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +to configure your cluster. ## Disable a cluster @@ -62,7 +69,7 @@ one to GitLab, the cluster connection to GitLab becomes enabled. To disable it: 1. Go to your: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Select the name of the cluster you want to disable. 1. Toggle **GitLab Integration** off (in gray). 1. Click **Save changes**. diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index fdd65d70242..54141fe1103 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -4,7 +4,13 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploy to a Kubernetes cluster +# Deploy to a Kubernetes cluster with cluster certificates + +WARNING: +The process described on this page uses cluster certificates to deploy to your cluster +from GitLab. Although this method still works, it is **no longer recommended**. +To deploy to your cluster from GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +instead. **(PREMIUM)** A Kubernetes cluster can be the destination for a deployment job. If diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index a0efea267f0..791dc90cad5 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -16,10 +16,6 @@ We offer extensive integrations to help you connect and manage your Kubernetes c Read through this document to get started. -## Clusters infrastructure - -Use [Infrastructure as Code](../../infrastructure) to create and manage your clusters with the GitLab integration with Terraform. - ## Benefit from the GitLab-Kubernetes integration Using the GitLab-Kubernetes integration, you can benefit of GitLab @@ -30,76 +26,18 @@ features such as: - Use [role-based or attribute-based access controls](cluster_access.md). - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). - Connect GitLab to in-cluster applications using [cluster integrations](../../clusters/integrations.md). -- Use [Deploy Boards](../deploy_boards.md) to see the health and status of each CI [environment](../../../ci/environments/index.md) running on your Kubernetes cluster. +- Use [deploy boards](../deploy_boards.md) to see the health and status of each CI [environment](../../../ci/environments/index.md) running on your Kubernetes cluster. - Use [Canary deployments](../canary_deployments.md) to update only a portion of your fleet with the latest version of your application. - View your [Kubernetes podlogs](kubernetes_pod_logs.md) directly in GitLab. - Connect to your cluster through GitLab [web terminals](deploy_to_cluster.md#web-terminals-for-kubernetes-clusters). ## Supported cluster versions -GitLab is committed to support at least two production-ready Kubernetes minor -versions at any given time. We regularly review the versions we support, and -provide a three-month deprecation period before we remove support of a specific -version. The range of supported versions is based on the evaluation of: - -- The versions supported by major managed Kubernetes providers. -- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions). - -GitLab supports the following Kubernetes versions, and you can upgrade your -Kubernetes version to any supported version at any time: - -- 1.19 (support ends on February 22, 2022) -- 1.18 (support ends on November 22, 2021) -- 1.17 (support ends on September 22, 2021) -- 1.16 (support ends on July 22, 2021) -- 1.15 (support ends on May 22, 2021) - -Some GitLab features may support versions outside the range provided here. - -## Add and remove clusters - -You can create new or add existing clusters to GitLab: - -- On the project-level, to have a cluster dedicated to a project. -- On the [group level](../../group/clusters/index.md), to use the same cluster across multiple projects within your group. -- On the [instance level](../../instance/clusters/index.md), to use the same cluster across multiple groups and projects. **(FREE SELF)** - -To create new clusters, use one of the following methods: - -- [Infrastructure as Code](../../infrastructure/index.md) (**recommended**). -- [Cluster certificates](add_remove_clusters.md) (**deprecated**). - -You can also [add existing clusters](add_existing_cluster.md) to GitLab. - -## View your clusters - -To view your project-level Kubernetes clusters, to go **Infrastructure > Kubernetes clusters** -from your project. On this page, you can add a new cluster -and view information about your existing clusters, such as: - -- Nodes count. -- Rough estimates of memory and CPU usage. - -## Configuring your Kubernetes cluster - -Use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to safely -configure your clusters. Otherwise, there are [security implications](#security-implications). - -### Security implications - -WARNING: -The whole cluster security is based on a model where [developers](../../permissions.md) -are trusted, so **only trusted users should be allowed to control your clusters**. - -The default cluster configuration grants access to a wide set of -functionalities needed to successfully build and deploy a containerized -application. Bear in mind that the same credentials are used for all the -applications running on the cluster. +See the [Kubernetes clusters versions supported by GitLab](../../infrastructure/clusters/connect/index.md#supported-cluster-versions). -## Multiple Kubernetes clusters +## Connect your cluster to GitLab -See how to associate [multiple Kubernetes clusters](multiple_kubernetes_clusters.md) -with your GitLab project. +Learn how to [create new and connect existing clusters to GitLab](../../infrastructure/clusters/connect/index.md). ## Cluster integrations diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 7a9c7eb423d..eb0e8d0e91c 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -46,15 +46,15 @@ a [metrics dashboard](../../../operations/metrics/index.md) and select **View lo [permissions](../../permissions.md#project-members-permissions) in the project. 1. To navigate to the **Log Explorer** from the sidebar menu, go to **Monitor > Logs** ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5.). -1. To navigate to the **Log Explorer** from a specific pod on a [Deploy Board](../deploy_boards.md): +1. To navigate to the **Log Explorer** from a specific pod on a [deploy board](../deploy_boards.md): 1. Go to **Deployments > Environments** and find the environment which contains the desired pod, like `production`. 1. On the **Environments** page, you should see the status of the environment's - pods with [Deploy Boards](../deploy_boards.md). + pods with [deploy boards](../deploy_boards.md). 1. When mousing over the list of pods, GitLab displays a tooltip with the exact pod name and status. -  +  1. Click on the desired pod to display the **Log Explorer**. ### Logs view diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 62010bb7802..1940cf229b8 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -137,7 +137,7 @@ Network Policies can be managed through GitLab in one of two ways: - Management through a YAML file in each application's project (for projects using Auto DevOps). For more information, see the [Network Policy documentation](../../../../../topics/autodevops/stages.md#network-policy). - Management through the GitLab Policy management UI (for projects not using Auto DevOps). For more - information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate only). + information, see the [Container Network Policy documentation](../../../../application_security/policies/index.md#container-network-policy) (Ultimate only). Each method has benefits and drawbacks: @@ -167,7 +167,7 @@ hubble: ``` Additional information about the statistics page is available in the -[documentation that describes the Threat Management UI](../../../../application_security/threat_monitoring/index.md#container-network-policy). +[documentation that describes the Threat Management UI](../../../../application_security/policies/index.md#container-network-policy). ## Forwarding logs to a SIEM diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index b2054c4befb..7357fc850e5 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -63,7 +63,7 @@ information. Follow this step-by-step guide to configure an executable runbook in GitLab using the components outlined above and the pre-loaded demo runbook. -1. Create an [OAuth Application for JupyterHub](../../../../integration/oauth_provider.md#gitlab-as-oauth2-authentication-service-provider). +1. Create an [OAuth Application for JupyterHub](../../../../integration/oauth_provider.md#gitlab-as-an-oauth-20-authentication-service-provider). 1. When [installing JupyterHub with Helm](https://zero-to-jupyterhub.readthedocs.io/en/latest/jupyterhub/installation.html), use the following values ```yaml diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index ec22f71157f..fb32579f40e 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -4,9 +4,10 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Serverless **(FREE)** +# Serverless (DEPRECATED) **(FREE)** -> Introduced in GitLab 11.5. +> - Introduced in GitLab 11.5. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/6) in GitLab 14.3. WARNING: Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). @@ -316,7 +317,7 @@ The optional `runtime` parameter can refer to one of the following runtime alias | `openfaas/classic/python3` | OpenFaaS | | `openfaas/classic/ruby` | OpenFaaS | -After the `gitlab-ci.yml` template has been added and the `serverless.yml` file +After the `.gitlab-ci.yml` template has been added and the `serverless.yml` file has been created, pushing a commit to your project results in a CI pipeline being executed which deploys each function as a Knative service. After the deploy stage has finished, additional details for the function display diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 64a5515136b..05f026cca18 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Boards **(FREE)** +# Deploy boards **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. @@ -16,7 +16,7 @@ type: howto, reference > This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60525) in > GitLab 13.12. -GitLab Deploy Boards offer a consolidated view of the current health and +GitLab deploy boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use @@ -28,23 +28,23 @@ environments by using [Auto DevOps](../../topics/autodevops/index.md). ## Overview -With Deploy Boards you can gain more insight into deploys with benefits such as: +With deploy boards you can gain more insight into deploys with benefits such as: - Following a deploy from the start, not just when it's done - Watching the rollout of a build across multiple servers - Finer state detail (Succeeded, Running, Failed, Pending, Unknown) - See [Canary Deployments](canary_deployments.md) -Here's an example of a Deploy Board of the production environment. +Here's an example of a deploy board of the production environment. - + The squares represent pods in your Kubernetes cluster that are associated with the given environment. Hovering above each square you can see the state of a deploy rolling out. The percentage is the percent of the pods that are updated to the latest release. -Since Deploy Boards are tightly coupled with Kubernetes, there is some required +Since deploy boards are tightly coupled with Kubernetes, there is some required knowledge. In particular, you should be familiar with: - [Kubernetes pods](https://kubernetes.io/docs/concepts/workloads/pods/) @@ -54,7 +54,7 @@ knowledge. In particular, you should be familiar with: ## Use cases -Since the Deploy Board is a visual representation of the Kubernetes pods for a +Since the deploy board is a visual representation of the Kubernetes pods for a specific environment, there are a lot of use cases. To name a few: - You want to promote what's running in staging, to production. You go to the @@ -73,9 +73,9 @@ specific environment, there are a lot of use cases. To name a few: list, find the [Review App](../../ci/review_apps/index.md) you're interested in, and click the manual action to deploy it to staging. -## Enabling Deploy Boards +## Enabling deploy boards -To display the Deploy Boards for a specific [environment](../../ci/environments/index.md) you should: +To display the deploy boards for a specific [environment](../../ci/environments/index.md) you should: 1. Have [defined an environment](../../ci/environments/index.md) with a deploy stage. @@ -83,7 +83,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ NOTE: If you're using OpenShift, ensure that you're using the `Deployment` resource - instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards don't render + instead of `DeploymentConfiguration`. Otherwise, the deploy boards don't render correctly. For more information, read the [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). @@ -114,17 +114,17 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ If you use GCP to manage clusters, you can see the deployment details in GCP itself by navigating to **Workloads > deployment name > Details**: -  +  Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Deployments > Environments**. -Deploy Boards are visible by default. You can explicitly click +Deploy boards are visible by default. You can explicitly click the triangle next to their respective environment name in order to hide them. ### Example manifest file -The following example is an extract of a Kubernetes manifest deployment file, using the two annotations `app.gitlab.com/env` and `app.gitlab.com/app` to enable the **Deploy Boards**: +The following example is an extract of a Kubernetes manifest deployment file, using the two annotations `app.gitlab.com/env` and `app.gitlab.com/app` to enable the **deploy boards**: ```yaml apiVersion: apps/v1 diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 1b9a17ee071..e9a38f91677 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -121,7 +121,7 @@ repositories to secure, shared services, such as CI/CD. Instance administrators can add public deploy keys: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Deploy Keys**. 1. Select **New deploy key**. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 70363b67c88..1798aa0c1c6 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -181,7 +181,7 @@ To pull images from the Dependency Proxy, you must: 1. Create a group deploy token with both `read_registry` and `write_registry` scopes. 1. Take note of your `username` and `token`. -1. Follow the Depenency Proxy [authentication instructions](../../packages/dependency_proxy/index.md). +1. Follow the Dependency Proxy [authentication instructions](../../packages/dependency_proxy/index.md). ### GitLab deploy token diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 72ef88b5fab..5b19a54bd91 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -116,7 +116,7 @@ Only instance administrators can set instance-level templates. To set the instance-level description template repository: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Templates**. 1. Expand **Templates** 1. From the dropdown, select your template project as the template repository at instance level. diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 802eb3efc51..cda018a0c37 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -16,18 +16,18 @@ Import your projects from Bitbucket Cloud to GitLab with minimal effort. The Bitbucket importer can import: -- Repository description (GitLab 7.7+) -- Git repository data (GitLab 7.7+) -- Issues (GitLab 7.7+) -- Issue comments (GitLab 8.15+) -- Pull requests (GitLab 8.4+) -- Pull request comments (GitLab 8.15+) -- Milestones (GitLab 8.15+) -- Wiki (GitLab 8.15+) +- Repository description +- Git repository data +- Issues +- Issue comments +- Pull requests +- Pull request comments +- Milestones +- Wiki When importing: -- References to pull requests and issues are preserved (GitLab 8.7+). +- References to pull requests and issues are preserved. - Repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 1ab343d75fb..4443ae902fb 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -31,13 +31,18 @@ each imported repository maintains visibility level unless that [visibility level is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), in which case it defaults to the default project visibility. -The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `gitlab.com/customer-success`. You can do some bulk actions to move projects to different namespaces in the rails console. +The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or +`gitlab.com/customer-success`. You can do some bulk actions to move projects to +different namespaces in the rails console. -This process does not migrate or import any types of groups or organizations from GitHub to GitLab. +This process does not migrate or import any types of groups or organizations +from GitHub to GitLab. ## Use cases -The steps you take depend on whether you are importing from GitHub.com or GitHub Enterprise, as well as whether you are importing to GitLab.com or self-managed GitLab instance. +The steps you take depend on whether you are importing from GitHub.com or +GitHub Enterprise. The steps also depend on whether you are importing to GitLab.com or +self-managed GitLab instance. - If you're importing to GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#use-a-github-token). We do not recommend @@ -49,12 +54,14 @@ The steps you take depend on whether you are importing from GitHub.com or GitHub - If you're importing from GitHub Enterprise to your self-managed GitLab instance, you must first enable [GitHub integration](../../../integration/github.md). - To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). -- If you're importing from GitHub.com to your self-managed GitLab instance, you do not need to set up GitHub integration. You can use the [Import API](../../../api/import.md). +- If you're importing from GitHub.com to your self-managed GitLab instance, + setting up GitHub integration is not required. You can use the [Import API](../../../api/import.md). ## How it works -When issues and pull requests are being imported, the importer attempts to find their GitHub authors and -assignees in the database of the GitLab instance (note that pull requests are called "merge requests" in GitLab). +When issues and pull requests are being imported, the importer attempts to find +their GitHub authors and assignees in the database of the GitLab instance (note +that pull requests are called "merge requests" in GitLab). For this association to succeed, each GitHub author and assignee in the repository must meet one of the following conditions prior to the import: @@ -64,12 +71,13 @@ must meet one of the following conditions prior to the import: that matches their GitLab account's email address. NOTE: - GitLab content imports that use GitHub accounts require that the GitHub public-facing - email address is populated so that all comments and contributions are properly mapped - to the same user in GitLab. GitHub Enterprise (on premise) does not require this field - to be populated to use the product, so you may need to add it on existing GitHub Enterprise - accounts for imported content to be properly mapped to the user in the new system. - Refer to GitHub documentation for instructions on how to add that address. + GitLab content imports that use GitHub accounts require that the GitHub + public-facing email address is populated so that all comments and + contributions are properly mapped to the same user in GitLab. GitHub + Enterprise (on premise) does not require this field to be populated to use the + product, so you may have to add it on existing accounts for the imported + content to be properly mapped to the user in the new system. Refer to GitHub + documentation for instructions on how to add this email address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original @@ -132,7 +140,7 @@ If you are not using the GitHub integration, you can still perform an authorizat 1. Copy the token hash. 1. Go back to GitLab and provide the token to the GitHub importer. 1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. - Once done, you'll be taken to the importer page to select the repositories to import. + Once done, you are taken to the importer page to select the repositories to import. To use a newer personal access token in imports after previously performing these steps, sign out of your GitLab account and sign in again, or revoke the older personal access token in GitHub. @@ -152,7 +160,7 @@ your GitHub repositories are listed.  -## Mirroring and pipeline status sharing +## Mirror a repository and share pipeline status Depending on your GitLab tier, [repository mirroring](../repository/repository_mirroring.md) can be set up to keep your imported repository in sync with its GitHub copy. @@ -169,7 +177,7 @@ Mirroring does not sync any new or updated pull requests from your GitHub projec ## Improve the speed of imports on self-managed instances NOTE: -Administrator access to the GitLab server is required. +An administrator role on the GitLab server is required for this process. For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: @@ -183,4 +191,52 @@ servers. For 4 servers with 8 cores this means you can import up to 32 objects ( Reducing the time spent in cloning a repository can be done by increasing network throughput, CPU capacity, and disk performance (by using high performance SSDs, for example) of the disks that store the Git repositories (for your GitLab instance). -Increasing the number of Sidekiq workers will *not* reduce the time spent cloning repositories. +Increasing the number of Sidekiq workers does *not* reduce the time spent cloning repositories. + +## Alternative way to import notes and diff notes + +When GitHub Importer runs on extremely large projects not all notes & diff notes can be imported due to GitHub API `issues_comments` & `pull_requests_comments` endpoints limitation. +Not all pages can be fetched due to the following error coming from GitHub API: `In order to keep the API fast for everyone, pagination is limited for this resource. Check the rel=last link relation in the Link response header to see how far back you can traverse.`. + +An alternative approach for importing notes and diff notes is available behind a feature flag. + +Instead of using `issues_comments` and `pull_requests_comments`, use individual resources `issue_comments` and `pull_request_comments` instead to pull notes from one object at a time. +This allows us to carry over any missing comments, however it increases the number of network requests required to perform the import, which means its execution takes a longer time. + +To use the alternative way of importing notes, the `github_importer_single_endpoint_notes_import` feature flag must be enabled on the group project is being imported into. + +Start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +```ruby +group = Group.find_by_full_path('my/group/fullpath') + +# Enable +Feature.enable(:github_importer_single_endpoint_notes_import, group) + +# Disable +Feature.disable(:github_importer_single_endpoint_notes_import, group) +``` + +## Reduce GitHub API request objects per page + +Some GitHub API endpoints may return a 500 or 502 error for project imports from large repositories. +To reduce the chance of such errors, you can enable the feature flag +`github_importer_lower_per_page_limit` in the group project importing the data. This reduces the +page size from 100 to 50. + +To enable this feature flag, start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +and run the following `enable` command: + +```ruby +group = Group.find_by_full_path('my/group/fullpath') + +# Enable +Feature.enable(:github_importer_lower_per_page_limit, group) +``` + +To disable the feature, run this command: + +```ruby +# Disable +Feature.disable(:github_importer_lower_per_page_limit, group) +``` diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index dcc41c6c85e..65e1eafa477 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -76,7 +76,7 @@ a self-managed instance from an old server to a new server. The backups produced don't depend on the operating system running GitLab. You can therefore use the restore method to switch between different operating system distributions or versions, as long -as the same GitLab version [is available for installation](https://docs.gitlab.com/omnibus/package-information/deprecated_os.md). +as the same GitLab version [is available for installation](../../../administration/package_information/deprecated_os.md). To instead merge two self-managed GitLab instances together, use the instructions in [Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 3e0faec0a49..c6992422733 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import your Jira project issues to GitLab **(PREMIUM)** +# Import your Jira project issues to GitLab **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2766) in GitLab 12.10. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 668a0dffd32..8c81af418a0 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -22,8 +22,8 @@ Projects include the following [features](https://about.gitlab.com/features/): **Repositories:** - [Issue tracker](issues/index.md): Discuss implementations with your team. - - [Issue Boards](issue_board.md): Organize and prioritize your workflow. - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. + - [Issue boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. - [Repositories](repository/index.md): Host your code in a fully-integrated platform. - [Branches](repository/branches/index.md): Use Git branching strategies to collaborate on code. @@ -41,8 +41,8 @@ Projects include the following [features](https://about.gitlab.com/features/): **Issues and merge requests:** - [Issue tracker](issues/index.md): Discuss implementations with your team. - - [Issue Boards](issue_board.md): Organize and prioritize your workflow. - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. + - [Issue boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. - [Merge Requests](merge_requests/index.md): Apply a branching strategy and get reviewed by your team. - [Merge Request Approvals](merge_requests/approvals/index.md): Ask for approval before @@ -141,7 +141,7 @@ There are numerous [APIs](../../api/index.md) to use with your projects: - [Threads](../../api/discussions.md) - [General](../../api/projects.md) - [Import/export](../../api/project_import_export.md) -- [Issue Board](../../api/boards.md) +- [Issue board](../../api/boards.md) - [Labels](../../api/labels.md) - [Markdown](../../api/markdown.md) - [Merge Requests](../../api/merge_requests.md) diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 6b342392bdf..4908d21e764 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab provides an integration for updating the pipeline statuses on GitHub. This is especially useful if using GitLab for CI/CD only. -This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirroring-and-pipeline-status-sharing) +This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) and is automatically configured on [GitHub import](../../../integration/github.md).  diff --git a/doc/user/project/integrations/img/slack_setup.png b/doc/user/project/integrations/img/slack_setup.png Binary files differindex 7928fb7d495..8acae659fb4 100644 --- a/doc/user/project/integrations/img/slack_setup.png +++ b/doc/user/project/integrations/img/slack_setup.png diff --git a/doc/user/project/integrations/img/zentao_product_id.png b/doc/user/project/integrations/img/zentao_product_id.png Binary files differnew file mode 100644 index 00000000000..a91b4c3f82d --- /dev/null +++ b/doc/user/project/integrations/img/zentao_product_id.png diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 6f86098b33d..ac6e18e8e6a 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -17,8 +17,8 @@ For more information, read the [overview of integrations](overview.md) or learn how to manage your integrations: - *For GitLab 13.3 and later,* read [Project integration management](../../admin_area/settings/project_integration_management.md). -- *For GitLab 13.2 and earlier,* read [Service Templates](services_templates.md), - which are deprecated and [scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) +- *For GitLab 13.2 and earlier,* read [Integration Management](../../admin_area/settings/project_integration_management.md), + which replaced the deprecated Service Templates [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) in GitLab 14.0. ## Project webhooks diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 5b5feb73b69..8027cc1c61e 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -22,7 +22,7 @@ on your configuration: - **Omnibus GitLab installations**: Mattermost is bundled with [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, read the - [Omnibus GitLab Mattermost documentation](https://docs.gitlab.com/omnibus/gitlab-mattermost/). + [Omnibus GitLab Mattermost documentation](../../../integration/mattermost/index.md). - **If Mattermost is installed on the same server as GitLab**, use the [automated configuration](#automated-configuration). - **For all other installations**, use the [manual configuration](#manual-configuration). @@ -68,7 +68,7 @@ information from GitLab. To get this information: 1. In a different browser tab than your current Mattermost session, sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. In the left menu, select **Settings > Integrations**, then select **Mattermost slash commands**. 1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 13def74450c..a6f739c6408 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -12,8 +12,10 @@ functionality to GitLab. ## Accessing integrations -You can find the available integrations under your project's -**Settings > Integrations** page. +To find the available integrations for your project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. There are more than 20 integrations to integrate with. Select the one that you want to configure. @@ -60,6 +62,7 @@ Click on the service links to see further configuration instructions and details | [Unify Circuit](unify_circuit.md) | Receive events notifications. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | +| [ZenTao](zentao.md) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | ## Push hooks limit diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md deleted file mode 100644 index 37df48c75f8..00000000000 --- a/doc/user/project/integrations/services_templates.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../admin_area/settings/project_integration_management.md' -remove_date: '2021-09-09' ---- - -This document was moved to [another location](../../admin_area/settings/project_integration_management.md). - -<!-- This redirect file can be deleted after <2021-09-09>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 5db4e839b54..a38d2157699 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -10,27 +10,27 @@ The Slack notifications service enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up Slack notifications requires configuration changes for both Slack and GitLab. -You can also use Slack slash commands to control GitLab inside Slack. This is the -separately configured [Slack slash commands](slack_slash_commands.md). +You can also use [Slack slash commands](slack_slash_commands.md) +to control GitLab from Slack. Slash commands are configured separately. -## Slack configuration +## Configure Slack 1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). 1. Identify the Slack channel where notifications should be sent to by default. Select **Add Incoming WebHooks integration** to add the configuration. -1. Copy the **Webhook URL**, which is used later in the GitLab configuration. +1. Copy the **Webhook URL** to use later when you configure GitLab. -## GitLab configuration +## Configure GitLab 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. -1. Select the **Slack notifications** integration to configure it. +1. Select **Slack notifications**. 1. In the **Enable integration** section, select the **Active** checkbox. 1. In the **Trigger** section, select the checkboxes for each type of GitLab event to send to Slack as a notification. For a full list, see - [Triggers available for Slack notifications](#triggers-available-for-slack-notifications). + [Triggers for Slack notifications](#triggers-for-slack-notifications). By default, messages are sent to the channel you configured during - [Slack integration](#slack-configuration). + [Slack configuration](#configure-slack). 1. (Optional) To send messages to a different channel, multiple channels, or as a direct message: - *To send messages to channels,* enter the Slack channel names, separated by @@ -40,38 +40,39 @@ separately configured [Slack slash commands](slack_slash_commands.md). NOTE: Usernames and private channels are not supported. -1. In **Webhook**, enter the webhook URL you copied from the previous - [Slack integration](#slack-configuration) step. +1. In **Webhook**, enter the webhook URL you copied in the + [Slack configuration](#configure-slack) step. 1. (Optional) In **Username**, enter the username of the Slack bot that sends the notifications. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. 1. In the **Branches to be notified** dropdown, select which types of branches to send notifications for. -1. Leave the **Labels to be notified** field blank to get all notifications or - add labels that the issue or merge request must have in order to trigger a +1. Leave the **Labels to be notified** field blank to get all notifications, or + add labels that the issue or merge request must have to trigger a notification. 1. Select **Test settings** to verify your information, and then select **Save changes**. Your Slack team now starts receiving GitLab event notifications as configured. -### Triggers available for Slack notifications +## Triggers for Slack notifications The following triggers are available for Slack notifications: -| Trigger | Description | -|------------------------|-------------| -| **Push** | Triggered by a push to the repository. | -| **Issue** | Triggered when an issue is created, updated, or closed. | -| **Confidential issue** | Triggered when a confidential issue is created, updated, or closed. | -| **Merge request** | Triggered when a merge request is created, updated, or merged. | -| **Note** | Triggered when someone adds a comment. | -| **Confidential note** | Triggered when someone adds a confidential note. | -| **Tag push** | Triggered when a new tag is pushed to the repository. | -| **Pipeline** | Triggered when a pipeline status changes. | -| **Wiki page** | Triggered when a wiki page is created or updated. | -| **Deployment** | Triggered when a deployment starts or finishes. | -| **Alert** | Triggered when a new, unique alert is recorded. | +| Trigger name | Trigger event | +| ------------------------ | ------------------------------------------------------ | +| **Push** | A push to the repository. | +| **Issue** | An issue is created, updated, or closed. | +| **Confidential issue** | A confidential issue is created, updated, or closed. | +| **Merge request** | A merge request is created, updated, or merged. | +| **Note** | A comment is added. | +| **Confidential note** | A confidential note is added. | +| **Tag push** | A new tag is pushed to the repository. | +| **Pipeline** | A pipeline status changed. | +| **Wiki page** | A wiki page is created or updated. | +| **Deployment** | A deployment starts or finishes. | +| **Alert** | A new, unique alert is recorded. | +| **Vulnerability** | **(ULTIMATE)** A new, unique vulnerability is recorded. | ## Troubleshooting @@ -81,45 +82,48 @@ for errors relating to your Slack service. ### Something went wrong on our end -This is a generic error shown in the GitLab UI and does not mean much by itself. +You might get this generic error message in the GitLab UI. Review [the logs](../../../administration/logs.md#productionlog) to find -an error message and keep troubleshooting from there. +the error message and keep troubleshooting from there. ### `certificate verify failed` -You may see an entry similar to the following in your Sidekiq log: +You might see an entry like the following in your Sidekiq log: ```plaintext 2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg ProjectServiceWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"ProjectServiceWorker", :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"} ``` -This is probably a problem either with GitLab communicating with Slack, or GitLab -communicating with itself. The former is less likely, as Slack's security certificates -should _hopefully_ always be trusted. We can establish which we're dealing with by using -the below rails console script. +This issue occurs when there is a problem with GitLab communicating with Slack, +or GitLab communicating with itself. +The former is less likely, as Slack security certificates should always be trusted. -```shell -# start a rails console: -sudo gitlab-rails console -e production +To view which of these problems is the cause of the issue: -# or for source installs: -bundle exec rails console -e production -``` +1. Start a Rails console: -```ruby -# run this in the Rails console -# replace <SLACK URL> with your actual Slack URL -result = Net::HTTP.get(URI('https://<SLACK URL>'));0 + ```shell + sudo gitlab-rails console -e production -# replace <GITLAB URL> with your actual GitLab URL -result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 -``` + # for source installs: + bundle exec rails console -e production + ``` + +1. Run the following commands: + + ```ruby + # replace <SLACK URL> with your actual Slack URL + result = Net::HTTP.get(URI('https://<SLACK URL>'));0 + + # replace <GITLAB URL> with your actual GitLab URL + result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 + ``` -If GitLab is not trusting HTTPS connections to itself, then you may -need to [add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +If GitLab does not trust HTTPS connections to itself, +[add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -If GitLab is not trusting connections to Slack, then the GitLab -OpenSSL trust store is incorrect. Some typical causes: +If GitLab does not trust connections to Slack, +the GitLab OpenSSL trust store is incorrect. Typical causes are: - Overriding the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}`. - Accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem`. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index dfebf9a1123..066a2f83753 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -8,27 +8,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 8.15. -Slack slash commands allow you to control GitLab and view content right inside -Slack, without having to leave it. This requires configurations in both Slack and GitLab. +If you want to control and view GitLab content while you're +working in Slack, you can use Slack slash commands. +To use Slack slash commands, you must configure both Slack and GitLab. -GitLab can also send events (e.g., `issue created`) to Slack as notifications. -This is the separately configured [Slack Notifications Service](slack.md). +GitLab can also send events (for example, `issue created`) to Slack as notifications. +The [Slack notifications service](slack.md) is configured separately. NOTE: -For GitLab.com, use the [Slack app](gitlab_slack_application.md) instead. +For GitLab.com, use the [GitLab Slack app](gitlab_slack_application.md) instead. -## Configuration +## Configure GitLab and Slack -1. Slack slash commands are scoped to a project. Navigate to the [Integrations page](overview.md#accessing-integrations) in your project's settings, i.e. **Project > Settings > Integrations**. -1. Select the **Slack slash commands** integration to configure it. This page contains required information to complete the configuration in Slack. Leave this browser tab open. -1. Open a new browser tab and sign in to your Slack team. [Start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). -1. Enter a trigger term. We suggest you use the project name. Click **Add Slash Command Integration**. -1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. In particular, the URL needs to be copied and pasted. Click **Save Integration** to complete the configuration in Slack. -1. While still on the Slack configuration page, copy the **token**. Go back to the GitLab browser tab and paste in the **token**. -1. Ensure that the **Active** toggle is enabled and click **Save changes** to complete the configuration in GitLab. +Slack slash command [integrations](overview.md#accessing-integrations) +are scoped to a project. - +1. In GitLab, on the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Slack slash commands**. Leave this browser tab open. +1. Open a new browser tab, sign in to your Slack team, and [start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). +1. Enter a trigger command. We suggest you use the project name. + Select **Add Slash Command Integration**. +1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. + In particular, make sure you copy and paste the **URL**. -## Usage +  -You can now use the [Slack slash commands](../../../integration/slash_commands.md). +1. On the Slack configuration page, select **Save Integration** and copy the **Token**. +1. Go back to the GitLab configuration page and paste in the **Token**. +1. Ensure the **Active** checkbox is selected and select **Save changes**. + +## Slash commands + +You can now use the available [Slack slash commands](../../../integration/slash_commands.md). diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 3632fdf0e0c..de152aabde5 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -27,7 +27,7 @@ notifications: 1. Navigate to: - **Settings > Integrations** in a project to enable the integration at the project level. - **Settings > Integrations** in a group to enable the integration at the group level. - - On the top bar, select **Menu >** **{admin}** **Admin**. Then, in the left sidebar, + - On the top bar, select **Menu > Admin**. Then, in the left sidebar, select **Settings > Integrations** to enable an instance-level integration. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md new file mode 100644 index 00000000000..ab8a7829139 --- /dev/null +++ b/doc/user/project/integrations/zentao.md @@ -0,0 +1,40 @@ +--- +stage: Ecosystem +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# ZenTao product integration **(PREMIUM)** + +[ZenTao](https://www.zentao.net/) is a web-based project management platform. + +## Configure ZenTao + +This integration requires a ZenTao API secret key. + +Complete these steps in ZenTao: + +1. Go to your **Admin** page and select **Develop > Application**. +1. Select **Add Application**. +1. Under **Name** and **Code**, enter a name and a code for the new secret key. +1. Under **Account**, select an existing account name. +1. Select **Save**. +1. Copy the generated key to use in GitLab. + +## Configure GitLab + +Complete these steps in GitLab: + +1. Go to your project and select **Settings > Integrations**. +1. Select **ZenTao**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the ZenTao configuration information: + - **ZenTao Web URL**: The base URL of the ZenTao instance web interface you're linking to this GitLab project (for example, `example.zentao.net`). + - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. + - **ZenTao API token**: Use the key you generated when you [configured ZenTao](#configure-zentao). + - **ZenTao Product ID**: To display issues from a single ZenTao product in a given GitLab project. The Product ID can be found in the ZenTao product page under **Settings > Overview**. + +  + +1. To verify the ZenTao connection is working, select **Test settings**. +1. Select **Save changes**. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 0c624d7df01..4d1805e3d31 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,9 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Boards **(FREE)** +# Issue boards **(FREE)** -The GitLab Issue Board is a software project management tool used to plan, +The issue board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board. @@ -46,7 +46,7 @@ To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enter <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of -the Issue Board feature. +the issue board feature. ## Multiple issue boards @@ -70,7 +70,7 @@ GitLab automatically loads the last board you visited. To create a new issue board: -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click the dropdown with the current board name in the upper left corner of the issue boards page. 1. Click **Create new board**. 1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. @@ -78,7 +78,7 @@ To create a new issue board: To delete the currently active issue board: -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click the dropdown with the current board name in the upper left corner of the issue boards page. 1. Click **Delete board**. 1. Click **Delete** to confirm. @@ -195,7 +195,7 @@ card includes: ## Permissions Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the -Issue Board feature to create or delete lists. They can also drag issues from one list to another. +issue board feature to create or delete lists. They can also drag issues from one list to another. ## How GitLab orders issues in a list @@ -229,8 +229,7 @@ and vice versa. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. > - [Deployed behind a feature flag](../feature_flags.md), enabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1 -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** +> - [Feature flag `graphql_board_lists`](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) removed in GitLab 14.3 There can be [risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features). @@ -271,7 +270,7 @@ clicking **View scope**. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of -the Configurable Issue Board feature. +the configurable issue board feature. ### Focus mode @@ -339,14 +338,14 @@ As in other list types, click the trash icon to remove a list. ### Iteration lists **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11. -> - [Deployed behind the `board_new_list` and `iteration_board_lists` feature flags](../feature_flags.md), enabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_list`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** +> - Enabled on GitLab.com and is ready for production use. +> - Enabled with `iteration_board_lists` flag for self-managed GitLab and is ready for production use. +> GitLab administrators can opt to [disable the feature flag](#enable-or-disable-iteration-lists-in-boards). -There can be -[risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features). -Refer to this feature's version history for more details. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the `iteration_board_lists` flag](../../administration/feature_flags.md). +On GitLab.com, this feature is available. You're also able to create lists of an iteration. These are lists that filter issues by the assigned @@ -387,7 +386,7 @@ appears on the right. There you can see and edit the issue's: - Title - Assignees -- Epic **PREMIUM** +- Epic **(PREMIUM)** - Milestone - Time tracking value (view only) - Due date @@ -673,52 +672,8 @@ A few things to remember: by default. If you have more than 20 issues, start scrolling down and the next 20 appear. -### Enable or disable GraphQL-based issue boards **(FREE SELF)** - -NOTE: -When enabling GraphQL-based issue boards, you must also enable the -[new add list form](#enable-or-disable-new-add-list-form). - -It is deployed behind a feature flag that is **enabled by default** as of GitLab 14.1. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can disable it. - -To enable it: - -```ruby -Feature.enable(:graphql_board_lists) -``` - -To disable it: - -```ruby -Feature.disable(:graphql_board_lists) -``` - -### Enable or disable new add list form **(FREE SELF)** - -The new form for adding lists is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can disable it. - -To enable it: - -```ruby -Feature.enable(:board_new_list) -``` - -To disable it: - -```ruby -Feature.disable(:board_new_list) -``` - ### Enable or disable iteration lists in boards **(PREMIUM SELF)** -NOTE: -When disabling iteration lists in boards, you also need to disable the [new add list form](#enable-or-disable-new-add-list-form). - The iteration list is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 2b07131df6e..ed6c07f2c6d 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -19,14 +19,20 @@ issue itself and the first commit related to that issue. If the issue and the code you're committing are both in the same project, add `#xxx` to the commit message, where `xxx` is the issue number. -If they are not in the same project, you can add the full URL to the issue -(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). ```shell git commit -m "this is my commit message. Ref #xxx" ``` -or +If they are in different projects, but in the same group, +add `projectname#xxx` to the commit message. + +```shell +git commit -m "this is my commit message. Ref projectname#xxx" +``` + +If they are not in the same group, you can add the full URL to the issue +(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). ```shell git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/issues/<xxx>" diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 56c219eb8c3..9842b0820e6 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -43,9 +43,9 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ - [Cross-link issues](crosslinking_issues.md) - [Bulk edit issues](../issues/managing_issues.md) - [Sort issue lists](sorting_issue_lists.md) -- [Search for issues](../../search/index.md#filtering-issue-and-merge-request-lists) +- [Search for issues](../../search/index.md#filter-issue-and-merge-request-lists) - [Epics](../../group/epics/index.md) -- [Issue Boards](../issue_board.md) +- [Issue boards](../issue_board.md) - [Issues API](../../../api/issues.md) - [Configure an external issue tracker](../../../integration/external-issue-tracker.md) - [Parts of an issue](issue_data_and_actions.md) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 78dc6805f2b..6bb60e5e31a 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -129,7 +129,7 @@ element. Due dates can be changed as many times as needed. ### Labels Categorize issues by giving them [labels](../labels.md). They help to organize workflows, -and they enable you to work with the [GitLab Issue Board](../issue_board.md). +and they enable you to work with the [issue board](../issue_board.md). Group Labels, which allow you to use the same labels for all projects in the same group, can also be given to issues. They work exactly the same, but are immediately diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a2185c83f4d..7033b90b736 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -44,7 +44,7 @@ There are many ways to get to the New Issue form from a project's page:  -- From an **Issue Board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. +- From an **issue board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. It opens a new issue for that project, pre-labeled with its respective list.  @@ -72,7 +72,7 @@ When you're creating a new issue, these are the fields you can fill in: To visit the issue tracker for all projects in your group: 1. Go to the group dashboard. -1. In the left sidebar, select **Issues**. +1. On the left sidebar, select **Issues**. 1. In the top-right, select the **Select project to create issue** button. 1. Select the project you'd like to create an issue for. The button now reflects the selected project. @@ -237,10 +237,10 @@ using the close button:  -You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card +You can also close an issue from the [issue boards](../issue_board.md) by dragging an issue card from its list and dropping it into the **Closed** list. - + ### Closing issues automatically diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 2681a39aeb6..aed346fb504 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -16,6 +16,7 @@ You can sort a list of issues several ways, including by: - Milestone due date - Popularity - Priority +- Title ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67234) in GitLab 14.3) - Weight The available sorting options can change based on the context of the list. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 353ce73329e..e1149b85cd5 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -59,7 +59,7 @@ In GitLab 13.11, you can optionally replace the sharing form with a modal window To share a project after enabling this feature: 1. Go to your project's page. -1. In the left sidebar, go to **Project information > Members**, and then select **Invite a group**. +1. On the left sidebar, go to **Project information > Members**, and then select **Invite a group**. 1. Select a group, and select a **Max role**. 1. (Optional) Select an **Access expiration date**. 1. Select **Invite**. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 47744edd5ce..aff55419a88 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -61,7 +61,9 @@ GitLab displays one of these buttons after the body of the merge request: Eligible approvers can also use the `/approve` [quick action](../../../project/quick_actions.md) when adding a comment to -a merge request. +a merge request. [In GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/292936), +if a user approves a merge request and is shown in the reviewer list, a green check mark +(**{check-circle-filled}**) displays next to their name. After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge unless it's blocked for another reason. Merge requests can be blocked by other problems, diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index c59d5973e21..d348c00bdc2 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -97,11 +97,8 @@ a merge request. You can choose to hide or show whitespace changes: ## Mark files as viewed -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. -> - Deployed behind a feature flag, enabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9 behind a feature flag, enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296674) in GitLab 14.3. When reviewing a merge request with many files multiple times, it may be useful to the reviewer to focus on new changes and ignore the files that they have already reviewed and don't want to @@ -116,25 +113,6 @@ To mark a file as viewed: Once checked, the file remains marked for that reviewer unless there are newly introduced changes to its content or the checkbox is unchecked. -### Enable or disable file views **(FREE SELF)** - -The file view feature is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to enable it for your instance. - -To enable it: - -```ruby -Feature.enable(:local_file_reviews) -``` - -To disable it: - -```ruby -Feature.disable(:local_file_reviews) -``` - ## Show merge request conflicts in diff > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index a0c3efe7143..4a2319774ac 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -11,7 +11,7 @@ GitLab implements Git's powerful feature to [cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") with a **Cherry-pick** button in merge requests and commit details. -## Cherry-picking a merge request +## Cherry-pick a merge request After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request. @@ -25,7 +25,7 @@ where you can choose to either: - Cherry-pick the changes directly into the selected branch. - Create a new merge request with the cherry-picked changes. -### Cherry-pick tracking +### Track a cherry-pick > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. @@ -40,7 +40,7 @@ NOTE: We only track cherry-pick executed from GitLab (both UI and API). Support for tracking cherry-picked commits through the command line is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/202215). -## Cherry-picking a commit +## Cherry-pick a commit You can cherry-pick a commit from the commit details page: diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 6337fb1e87b..e9f1874eb96 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -56,11 +56,10 @@ See also the Code Climate list of [Supported Languages for Maintainability](http ## Code Quality in diff view **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. -> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11, disabled by default behind the `codequality_mr_diff` [feature flag](../../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. -> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.1. +> - [Disabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0 due to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/334116). +> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example: @@ -276,7 +275,7 @@ might look like this example: job1: rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run job1 in merge request pipelines - - if: '$CI_COMMIT_BRANCH == "master"' # Run job1 in pipelines on the master branch (but not in other branch pipelines) + - if: '$CI_COMMIT_BRANCH == "main"' # Run job1 in pipelines on the main branch (but not in other branch pipelines) - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags ``` @@ -292,7 +291,7 @@ code_quality: - if: '$CODE_QUALITY_DISABLED' when: never - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run code quality job in merge request pipelines - - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' # Run code quality job in pipelines on the master branch (but not in other branch pipelines) + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' # Run code quality job in pipelines on the default branch (but not in other branch pipelines) - if: '$CI_COMMIT_TAG' # Run code quality job in pipelines for tags ``` diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 6d8a128c39f..0d87a04461b 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -45,7 +45,7 @@ This template requires: - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#configure-pipelines-for-merge-requests) - [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results) enabled in the project settings. -- A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#overriding-external-template-values) this. +- A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#override-included-configuration-values) this. ## Configuring Fast RSpec Failure diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index b1e8d761f5c..7edc379399b 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -24,9 +24,11 @@ When a fast-forward merge is not possible, the user is given the option to rebas ## Enabling fast-forward merges -1. Navigate to your project's **Settings** and search for the 'Merge method' -1. Select the **Fast-forward merge** option -1. Hit **Save changes** for the changes to take effect +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Merge method** section, select **Fast-forward merge**. +1. Select **Save changes**. Now, when you visit the merge request page, you can accept it **only if a fast-forward merge is possible**. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 46fc3ec141d..72fcd7f36b0 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -65,7 +65,7 @@ request's page at the top-right side: After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. -- [Perform inline code reviews](reviews/index.md#perform-inline-code-reviews). +- [Perform inline code reviews](reviews/index.md). - Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** - Preview continuous integration [pipelines on the merge request widget](widgets.md). - Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). @@ -166,10 +166,13 @@ is set for deletion, the merge request widget displays the ### Branch retargeting on merge **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. -> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) in GitLab 13.10. -> - Recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-branch-retargeting-on-merge). **(FREE SELF)** +> - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) GitLab 13.10. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to +[disable the `retarget_merge_requests` flag](../../../administration/feature_flags.md). In specific circumstances, GitLab can retarget the destination branch of open merge request, if the destination branch merges while the merge request is @@ -203,22 +206,3 @@ This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitla - Take one thing at a time and ship the smallest changes possible. By doing so, reviews are faster and your changes are less prone to errors. - Do not use capital letters nor special chars in branch names. - -### Enable or disable branch retargeting on merge **(FREE SELF)** - -Automatically retargeting merge requests is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:retarget_merge_requests) -``` - -To disable it: - -```ruby -Feature.disable(:retarget_merge_requests) -``` diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 6c2f07d7012..b7e055ca749 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -27,7 +27,7 @@ important parts of the merge request:  - **Overview**: Contains the description, notifications from pipelines, and a - discussion area for [comment threads](../../discussions/index.md#resolve-a-thread)) + discussion area for [comment threads](../../discussions/index.md#resolve-a-thread) and [code suggestions](reviews/suggestions.md). The right sidebar provides fields to add assignees, reviewers, labels, and a milestone to your work, and the [merge request widgets area](widgets.md) reports results from pipelines and tests. @@ -53,7 +53,7 @@ GitLab displays open merge requests, with tabs to filter the list by open and cl  -You can [search and filter](../../search/index.md#filtering-issue-and-merge-request-lists), +You can [search and filter](../../search/index.md#filter-issue-and-merge-request-lists), the results, or select a merge request to begin a review. ## Merge request sidebar @@ -76,6 +76,21 @@ can assign, categorize, and track progress on a merge request: - [**Notifications**](../../profile/notifications.md): A toggle to select whether or not to receive notifications for updates to a merge request. +## Add changes to a merge request + +If you have permission to add changes to a merge request, you can add your changes +to an existing merge request in several ways, depending on the complexity of your change and whether you need access to a development environment: + +- [Edit changes in the Web IDE](../web_ide/index.md) in your browser. Use this + browser-based method to edit multiple files, or if you are not comfortable with Git commands. + You cannot run tests from the Web IDE. +- [Edit changes in Gitpod](../../../integration/gitpod.md#launch-gitpod-in-gitlab), if you + need a fully-featured environment to both edit files, and run tests afterward. Gitpod + supports running the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit). + To use Gitpod, you must [enable Gitpod in your user account](../../../integration/gitpod.md#enable-gitpod-in-your-user-settings). +- [Push changes from the command line](../../../gitlab-basics/start-using-git.md), if you are + familiar with Git and the command line. + ## Close a merge request If you decide to permanently stop work on a merge request, @@ -130,7 +145,7 @@ For a web developer writing a webpage for your company's website: 1. You request your web designers for their implementation. 1. You request the [approval](approvals/index.md) from your manager. 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). -1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production. +1. Your production team [cherry-picks](cherry_pick_changes.md) the merge commit into production. ## Related topics diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 7ea785c00ea..1d892a3c2e1 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -181,7 +181,7 @@ include: review: stage: deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: http://$CI_ENVIRONMENT_SLUG.example.com script: - run_deploy_script diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index a798f2c9b85..e6fb619d365 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Reverting changes **(FREE)** +# Revert changes **(FREE)** You can use Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation") by clicking the **Revert** button in merge requests and commit details. -## Reverting a merge request +## Revert a merge request NOTE: The **Revert** button is available only for merge requests @@ -34,7 +34,7 @@ create a new merge request with the revert changes. After the merge request has been reverted, the **Revert** button is no longer available. -## Reverting a commit +## Revert a commit You can revert a commit from the commit details page: diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 61cd0d25aaf..dbf3b0180e6 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -12,9 +12,10 @@ type: index, reference [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) -to propose changes. Your team leaves [comments](../../../discussions/index.md), and -makes [code suggestions](suggestions.md) you can accept from the user interface. -When your work is reviewed, your team members can choose to accept or reject it. +to propose changes. Your team leaves [comments](../../../discussions/index.md) on +your merge request, and makes [code suggestions](suggestions.md) you can accept +from the user interface. When your work is reviewed, your team members can choose +to accept or reject it. ## Review a merge request @@ -28,7 +29,9 @@ To start your review: 1. Go to the merge request you want to review, and select the **Changes** tab. To learn more about navigating the diffs displayed in this tab, read [Changes tab in merge requests](../changes.md). -1. Select a line of code. In GitLab version 13.2 and later, you can [highlight a set of lines](#comment-on-multiple-lines). +1. Select the **{comment}** **comment** icon in the gutter to expand the diff lines + and display a comment box. In GitLab version 13.2 and later, you can + [select multiple lines](#comment-on-multiple-lines). 1. Write your first comment, and select **Start a review** below your comment:  1. Continue adding comments to lines of code, and select the appropriate button after @@ -40,7 +43,13 @@ To start your review: The comment shows the actions to perform after publication, but does not perform them until you submit your review. 1. When your review is complete, you can [submit the review](#submit-a-review). Your comments - are now visible, and any quick actions included your comments are performed. + are now visible, and any [quick actions](../../quick_actions.md) included in + your comments are performed. + +[In GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/292936), +if you [approve a merge request](../approvals/index.md#approve-a-merge-request) and +are shown in the reviewer list, a green check mark **{check-circle-filled}** +displays next to your name. ### Submit a review @@ -57,7 +66,7 @@ When you submit your review, GitLab: review comments attached. Replying to this email creates a new comment on the merge request. - Perform any quick actions you added to your review comments. -### Resolving/Unresolving threads +### Resolve or unresolve thread with a comment Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread)). When replying to a comment, a checkbox is displayed to resolve or unresolve @@ -72,7 +81,7 @@ comment itself.  -### Adding a new comment +### Add a new comment > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. @@ -97,7 +106,7 @@ This example shows reviewers and approval rules in a merge request sidebar:  -### Requesting a new review +### Request a new review > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. @@ -112,13 +121,6 @@ the author of the merge request can request a new review from the reviewer: GitLab creates a new [to-do item](../../../todos.md) for the reviewer, and sends them a notification email. -#### Approval status - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292936) in GitLab 13.10. - -If a user in the reviewer list has approved the merge request, a green tick symbol is -shown to the right of their name. - ## Semi-linear history merge requests A merge commit is created for every merge, but the branch is only merged if @@ -130,18 +132,7 @@ succeeded, the target branch build also succeeds after the merge. 1. In the **Merge method** section, select **Merge commit with semi-linear history**. 1. Select **Save changes**. -## Perform inline code reviews - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. - -In a merge request, you can leave comments in any part of the file being changed. -In the merge request Diff UI, you can: - -- **Comment on a single line**: Select the **{comment}** **comment** icon in the - gutter to expand the diff lines and display a comment box. -- [**Comment on multiple lines**](#comment-on-multiple-lines). - -### Comment on multiple lines +## Comment on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 8ee068531c8..4027ec08234 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -46,7 +46,7 @@ branch. The [Developer role](../../../permissions.md) is required to do so. ## Multi-line suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. Reviewers can also suggest changes to multiple lines with a single suggestion within merge request diff threads by adjusting the range offsets. The diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 2842c084bc5..c3fc2fa871f 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -12,8 +12,6 @@ type: reference, concepts With squash and merge you can combine all your merge request's commits into one and retain a clean history. -## Overview - Squashing lets you tidy up the commit history of a branch when accepting a merge request. It applies all of the changes in the merge request as a single commit, and then merges that commit using the merge method set for the project. @@ -58,7 +56,7 @@ meaningful commit messages and: - It's simpler to [revert](revert_changes.md) if necessary. - The merged branch retains the full commit history. -## Enabling squash for a merge request +## Enable squash for a merge request Anyone who can create or edit a merge request can choose for it to be squashed on the merge request form. Users can select or clear the checkbox when they @@ -98,7 +96,7 @@ it. This is because squashing is only available when accepting a merge request, so a merge request may need to be rebased before squashing, even though squashing can itself be considered equivalent to rebasing. -## Squash Commits Options +## Squash commits options > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2. > - Deployed behind a feature flag, disabled by default. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 1576b639a76..399d7958bbf 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -125,7 +125,7 @@ the status checks as `pending`:  -After GitLab [receives a response](../../../api/status_checks.md#set-approval-status-of-an-external-status-check) +After GitLab [receives a response](../../../api/status_checks.md#set-status-of-an-external-status-check) from the external status check, the widget updates accordingly. NOTE: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index ce8bfa2d054..813e3c1c9ce 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -24,7 +24,8 @@ Collecting the coverage information is done via GitLab CI/CD's [artifacts reports feature](../../../ci/yaml/index.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. GitLab then takes the coverage information in all the files and combines it -together. +together. Coverage files are parsed in a background job so there can be a delay +between pipeline completion and the visualization loading on the page. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to @@ -129,7 +130,7 @@ The `source` is ignored if the path does not follow this pattern. The parser ass ### JavaScript example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) JavaScript testing and [nyc](https://github.com/istanbuljs/nyc) coverage-tooling to generate the coverage artifact: @@ -147,7 +148,7 @@ test: #### Maven example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -185,7 +186,7 @@ coverage-jdk11: #### Gradle example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -223,7 +224,7 @@ coverage-jdk11: ### Python example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. The information isn't displayed without the conversion. This example assumes that the code for your package is in `src/` and your tests are in `tests.py`: @@ -243,7 +244,7 @@ run tests: ### C/C++ example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with `gcc` or `g++` as the compiler uses [`gcovr`](https://gcovr.com/en/stable/) to generate the coverage output file in Cobertura XML format. diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 1d196de36e2..3922ee4d770 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Create +group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 5a688fbb485..385a4fafa7d 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -46,7 +46,7 @@ To create a GitLab Pages website: | Document | Description | | -------- | ----------- | -| [Create a `gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | +| [Create a `.gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | | [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | | [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | | [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 532a36b2327..4b4d479e3e9 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -52,6 +52,6 @@ To sign out of your GitLab Pages website, revoke the application access token for GitLab Pages: 1. In the top menu, select your profile, and then select **Settings**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. Scroll to the **Authorized applications** section, find the **GitLab Pages** entry, and select its **Revoke** button. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 8ed6f214605..3deea92f56e 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -9,62 +9,58 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - In GitLab Pages, you can configure rules to forward one URL to another using [Netlify style](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) HTTP redirects. -## Supported features - -GitLab Pages only supports the -[`_redirects` plain text file syntax](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file), -and `.toml` files are not supported. - -Redirects are only supported at a basic level. GitLab Pages doesn't support all -[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/). - -Note that supported paths must start with a forward slash `/`. +Not all +[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/) +are supported. | Feature | Supported | Example | | ------- | --------- | ------- | -| Redirects (`301`, `302`) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` -| Rewrites (other status codes) | **{dotted-circle}** No | `/en/* /en/404.html 404` | -| [Splats](https://docs.netlify.com/routing/redirects/redirect-options/#splats) | **{dotted-circle}** No | `/news/* /blog/:splat` | -| Placeholders | **{dotted-circle}** No | `/news/:year/:month/:date/:slug /blog/:year/:month/:date/:slug` | +| [Redirects (`301`, `302`)](#redirects) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` +| [Rewrites (`200`)](#rewrites) | **{check-circle}** Yes | `/* / 200` | +| [Splats](#splats) | **{check-circle}** Yes | `/news/* /blog/:splat` | +| [Placeholders](#placeholders) | **{check-circle}** Yes | `/news/:year/:month/:date /blog-:year-:month-:date.html` | +| Rewrites (other than `200`) | **{dotted-circle}** No | `/en/* /en/404.html 404` | | Query parameters | **{dotted-circle}** No | `/store id=:id /blog/:id 301` | | Force ([shadowing](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing)) | **{dotted-circle}** No | `/app/ /app/index.html 200!` | | Domain-level redirects | **{dotted-circle}** No | `http://blog.example.com/* https://www.example.com/blog/:splat 301` | | Redirect by country or language | **{dotted-circle}** No | `/ /anz 302 Country=au,nz` | | Redirect by role | **{dotted-circle}** No | `/admin/* 200! Role=admin` | +NOTE: +The [matching behavior test cases](https://gitlab.com/gitlab-org/gitlab-pages/-/blob/master/internal/redirects/matching_test.go) +are a good resource for understanding how GitLab implements rule matching in +detail. Community contributions are welcome for any edge cases that aren't included in +this test suite! + ## Create redirects -To create redirects, -create a configuration file named `_redirects` in the `public/` directory of your -GitLab Pages site. +To create redirects, create a configuration file named `_redirects` in the +`public/` directory of your GitLab Pages site. -If your GitLab Pages site uses the default domain name (such as -`namespace.gitlab.io/projectname`) you must prefix every rule with the project name: +Note that: -```plaintext -/projectname/redirect-portal.html /projectname/magic-land.html 301 -/projectname/cake-portal.html /projectname/still-alive.html 302 -/projectname/wardrobe.html /projectname/narnia.html 302 -/projectname/pit.html /projectname/spikes.html 302 -``` +- All paths must start with a forward slash `/`. +- A default status code of `301` is applied if no [status code](#http-status-codes) is provided. +- The `_redirects` file has a file size limit of 64KB and a maximum of 1,000 rules per project. + Only the first 1,000 rules are processed. +- If your GitLab Pages site uses the default domain name (such as + `namespace.gitlab.io/projectname`) you must prefix every rule with the project name: -If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), -no project name prefix is needed. For example, if your custom domain is `example.com`, -your `_redirect` file would look like: + ```plaintext + /projectname/wardrobe.html /projectname/narnia.html 302 + ``` -```plaintext -/redirect-portal.html /magic-land.html 301 -/cake-portal.html /still-alive.html 302 -/wardrobe.html /narnia.html 302 -/pit.html /spikes.html 302 -``` +- If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), + no project name prefix is needed. For example, if your custom domain is `example.com`, + your `_redirects` file would look like: + + ```plaintext + /wardrobe.html /narnia.html 302 + ``` ## Files override redirects @@ -81,6 +77,132 @@ GitLab doesn't support Netlify's [force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) to change this behavior. +## HTTP status codes + +A default status code of `301` is applied if no status code is provided, but +you can explicitly set your own. The following HTTP codes are supported: + +- **301**: Permanent redirect. +- **302**: Temporary redirect. +- **200**: Standard response for successful HTTP requests. Pages + serves the content in the `to` rule if it exists, without changing the URL in + the address bar. + +## Redirects + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. +> - Enabled on GitLab.com. +> - Enabled by default in self-managed GitLab behind the [`FF_ENABLE_REDIRECTS` feature flag](#feature-flag-for-redirects). + +To create a redirect, add a rule that includes a `from` path, a `to` path, +and an [HTTP status code](#http-status-codes): + +```plaintext +# 301 permanent redirect +/old/file.html /new/file.html 301 + +# 302 temporary redirect +/old/another_file.html /new/another_file.html 302 +``` + +## Rewrites + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. +> - Enabled on GitLab.com. +> - Disabled by default in self-managed GitLab behind the [`FF_ENABLE_PLACEHOLDERS` feature flag](#feature-flag-for-rewrites). + +Provide a status code of `200` to serve the content of the `to` path when the +request matches the `from`: + +```plaintext +/old/file.html /new/file.html 200 +``` + +This status code can be used in combination with [splat rules](#splats) to dynamically +rewrite the URL. + +## Splats + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. + +A rule with an asterisk (`*`) in its `from` path, known as a splat, matches +anything at the start, middle, or end of the requested path. This example +matches anything after `/old/` and rewrites it to `/new/file.html`: + +```plaintext +/old/* /new/file.html 200 +``` + +### Splat placeholders + +The content matched by a `*` in a rule's `from` path can be injected into the +`to` path using the `:splat` placeholder: + +```plaintext +/old/* /new/:splat 200 +``` + +In this example, a request to `/old/file.html` serves the contents of `/new/file.html` +with a `200` status code. + +If a rule's `from` path includes multiple splats, the value of the first splat +match replaces any `:splat`s in the `to` path. + +### Splat matching behavior + +Splats are "greedy" and match as many characters as possible: + +```plaintext +/old/*/file /new/:splat/file 301 +``` + +In this example, the rule redirects `/old/a/b/c/file` to `/new/a/b/c/file`. + +Splats also match empty strings, so the previous rule redirects +`/old/file` to `/new/file`. + +### Rewrite all requests to a root `index.html` + +Single page applications (SPAs) often perform their own routing using +client-side routes. For these applications, it's important that _all_ requests +are rewritten to the root `index.html` so that the routing logic can be handled +by the JavaScript application. You can do this with a `_redirects` +rule like: + +```plaintext +/* /index.html 200 +``` + +## Placeholders + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. + +Use placeholders in rules to match portions of the requested URL and use these +matches when rewriting or redirecting to a new URL. + +A placehold is formatted as a `:` character followed by a string of letters +(`[a-zA-Z]+`) in both the `from` and `to` paths: + +```plaintext +/news/:year/:month/:date/:slug /blog/:year-:month-:date-:slug 200 +``` + +This rule instructs Pages to respond to a request for `/news/2021/08/12/file.html` by +serving the content of `/blog/2021-08-12-file.html` with a `200`. + +### Placeholder matching behavior + +Compared to [splats](#splats), placeholders are more limited in how much content +they match. Placeholders match text between forward slashes +(`/`), so use placeholders to match single path segments. + +In addition, placeholders do not match empty strings. A rule like the following +would **not** match a request URL like `/old/file`: + +```plaintext +/old/:path /new/:path +``` + ## Debug redirect rules If a redirect isn't working as expected, or you want to check your redirect syntax, visit @@ -103,8 +225,49 @@ rule 10: valid rule 11: valid ``` -## Disable redirects +## Differences from Netlify's implementation + +Most supported `_redirects` rules behave the same in both GitLab and Netlify. +However, there are some minor differences: + +- **All rule URLs must begin with a slash:** + + Netlify does not require URLs to begin with a forward slash: + + ```plaintext + # Valid in Netlify, invalid in GitLab + */path /new/path 200 + ``` + + GitLab validates that all URLs begin with a forward slash. A valid + equivalent of the previous example: + + ```plaintext + # Valid in both Netlify and GitLab + /old/path /new/path 200 + ``` +- **All placeholder values are populated:** + + Netlify only populates placeholder values that appear in the `to` path: + + ```plaintext + /old /new/:placeholder + ``` + + Given a request to `/old`: + + - Netlify redirects to `/new/:placeholder` (with a + literal `:placeholder`). + - GitLab redirects to `/new/`. + +## Features behind feature flags + +Some Pages features are behind feature flags. + +### Feature flag for redirects + +FLAG: Redirects in GitLab Pages is under development, and is deployed behind a feature flag that is **enabled by default**. @@ -126,3 +289,28 @@ For [source installations](../../../administration/pages/source.md), define the export FF_ENABLE_REDIRECTS="false" /path/to/pages/bin/gitlab-pages -config gitlab-pages.conf ``` + +### Feature flag for rewrites + +FLAG: +Rewrites in GitLab Pages is under development, and is deployed behind a feature flag +that is **disabled by default**. + +To enable rewrites, for [Omnibus installations](../../../administration/pages/index.md), define the +`FF_ENABLE_PLACEHOLDERS` environment variable in the +[global settings](../../../administration/pages/index.md#global-settings). +Add the following line to `/etc/gitlab/gitlab.rb` and +[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure): + +```ruby +gitlab_pages['env']['FF_ENABLE_PLACEHOLDERS'] = 'true' +``` + +For [source installations](../../../administration/pages/source.md), define the +`FF_ENABLE_PLACEHOLDERS` environment variable, then +[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): + +```shell +export FF_ENABLE_PLACEHOLDERS="true" +/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf +``` diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 683496b4a9b..52b59d70302 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -103,6 +103,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | | `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | | `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8003)| | `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | | `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | | `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | diff --git a/doc/user/project/releases/img/deploy_freeze_v13_10.png b/doc/user/project/releases/img/deploy_freeze_v13_10.png Binary files differdeleted file mode 100644 index 5c4b2d983dd..00000000000 --- a/doc/user/project/releases/img/deploy_freeze_v13_10.png +++ /dev/null diff --git a/doc/user/project/releases/img/deploy_freeze_v14_3.png b/doc/user/project/releases/img/deploy_freeze_v14_3.png Binary files differnew file mode 100644 index 00000000000..13580ac1576 --- /dev/null +++ b/doc/user/project/releases/img/deploy_freeze_v14_3.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 76b300bdd57..49b5ec2ca60 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -186,7 +186,8 @@ To subscribe to notifications for releases: ## Prevent unintentional releases by setting a deploy freeze -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. +> - The ability to delete freeze periods through the UI was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212451) in GitLab 14.3. Prevent unintended production releases during a period of time you specify by setting a [*deploy freeze* period](../../../ci/environments/deployment_safety.md). @@ -199,7 +200,7 @@ If the job that's executing is within a freeze period, GitLab CI/CD creates an e variable named `$CI_DEPLOY_FREEZE`. To prevent the deployment job from executing, create a `rules` entry in your -`gitlab-ci.yml`, for example: +`.gitlab-ci.yml`, for example: ```yaml deploy_to_production: @@ -219,11 +220,8 @@ To set a deploy freeze window in the UI, complete these steps: 1. Click **Add deploy freeze** to open the deploy freeze modal. 1. Enter the start time, end time, and timezone of the desired deploy freeze period. 1. Click **Add deploy freeze** in the modal. -1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**). -  - -WARNING: -To delete a deploy freeze, use the [Freeze Periods API](../../../api/freeze_periods.md). +1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**) and remove it by selecting the delete button (**{remove}**). +  If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the complete overlapping period. @@ -394,9 +392,9 @@ upload: - if: $CI_COMMIT_TAG script: - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} ${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY} + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}" - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} ${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY} + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}" release: # Caution, as of 2021-02-02 these assets links require a login, see: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 12fd7389f21..a1ea929bb49 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -37,7 +37,7 @@ the [Git commands you need](#update-the-default-branch-name-in-your-repository) To update the default branch name for an individual [project](../../index.md): -1. Sign in to GitLab as a user with the [Administrator](../../../permissions.md) role. +1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) role. 1. In the left navigation menu, go to **Settings > Repository**. 1. Expand **Default branch**, and select a new default branch. 1. (Optional) Select the **Auto-close referenced issues on default branch** checkbox to close @@ -63,8 +63,8 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Repository**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default initial branch name**. 1. Change the default initial branch to a custom name of your choice. 1. Select **Save changes**. @@ -77,7 +77,7 @@ overrides it. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6. -Administrators of groups and subgroups can configure the default branch name for a group: +Users with at least the Owner role of groups and subgroups can configure the default branch name for a group: 1. Go to the group **Settings > Repository**. 1. Expand **Default initial branch name**. @@ -128,8 +128,8 @@ renames a Git repository's (`example`) default branch. git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main ``` -1. Sign in to GitLab as an [administrator](../../../permissions.md) and follow - the instructions to +1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) + role and follow the instructions to [change the default branch for this project](#change-the-default-branch-name-for-a-project). Select `main` as your new default branch. 1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md). diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index c41b3ed8615..23d7aecc960 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -19,6 +19,11 @@ NOTE: The term GPG is used for all OpenPGP/PGP/GPG related material and implementations. +To view a user's public GPG key, you can: + +- Go to `https://gitlab.example.com/<username>.gpg`. +- Select **View public GPG keys** (**{key}**) in the top right of the user's profile. + GPG verified tags are not supported yet. See the [further reading](#further-reading) section for more details on GPG. @@ -150,7 +155,7 @@ You can add a GPG key in your user settings: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys**. 1. Paste your _public_ key in the **Key** text box.  @@ -248,7 +253,7 @@ To revoke a GPG key: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys**. 1. Select **Revoke** next to the GPG key you want to delete. ## Removing a GPG key @@ -262,7 +267,7 @@ To remove a GPG key from your account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys**. 1. Select the trash icon (**{remove}**) next to the GPG key you want to delete. ## Rejecting commits that are not signed **(PREMIUM)** diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index afdcf2a94fa..de7459e6278 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -34,7 +34,7 @@ You can [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recordin to a branch in the repository. When you use the command line, you can commit multiple times before you push. - **Commit message:** - A commit message identities what is being changed and why. + A commit message identifies what is being changed and why. In GitLab, you can add keywords to the commit message to perform one of the following actions: - **Trigger a GitLab CI/CD pipeline:** @@ -50,10 +50,10 @@ to a branch in the repository. When you use the command line, you can commit mul on their respective thread. - **Cherry-pick a commit:** In GitLab, you can - [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) + [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-pick-a-commit) from the UI. - **Revert a commit:** - [Revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) + [Revert a commit](../merge_requests/revert_changes.md#revert-a-commit) from the UI to a selected branch. - **Sign a commit:** Use GPG to [sign your commits](gpg_signed_commits/index.md). diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 76eae58b431..5a02a35fce1 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -223,13 +223,15 @@ If a repository you're interested in is located on a different server, and you w to browse its content and its activity using the GitLab interface, you can configure mirror pulling: -1. If you [configured two-factor authentication (2FA)](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa) - for GitHub, create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) - with the `read_repository` scope. If 2FA is enabled, this personal access +1. If your remote repository is on GitHub and you have + [two-factor authentication (2FA) configured](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa), + create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). + with the `repo` scope. If 2FA is enabled, this personal access token serves as your GitHub password. 1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. -1. In the **Git repository URL** field, enter a repository URL. +1. In the **Git repository URL** field, enter a repository URL. Include the username + in the URL if required: `https://MYUSERNAME@github.com/group/PROJECTNAME.git` 1. In the **Mirror direction** dropdown, select **Pull**. 1. In the **Authentication method** dropdown, select your authentication method. 1. Select from the following checkboxes, if needed: @@ -611,7 +613,7 @@ If you receive this error after creating a new project using Check if the repository owner is specified in the URL of your mirrored repository: 1. Go to your project. -1. In the left sidebar, select **Settings > Repository**. +1. On the left sidebar, select **Settings > Repository**. 1. Select **Mirroring repositories**. 1. If no repository owner is specified, delete and add the URL again in this format: diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 7c115734345..17031dd29af 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -5,72 +5,82 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Signing commits and tags with X.509 **(FREE)** +# Sign commits and tags with X.509 certificates **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17773) in GitLab 12.8. [X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). Personal X.509 certificates are used for authentication or signing purposes -such as SMIME, but Git also supports signing of commits and tags -with X.509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md). -The main difference is the trust anchor which is the PKI for X.509 certificates -instead of a web of trust with GPG. - -## How GitLab handles X.509 - -GitLab uses its own certificate store and therefore defines the trust chain. - +such as S/MIME (Secure/Multipurpose Internet Mail Extensions). +However, Git also supports signing of commits and tags with X.509 certificates in a +similar way as with [GPG (GnuPG, or GNU Privacy Guard)](../gpg_signed_commits/index.md). +The main difference is the way GitLab determines whether or not the developer's signature is trusted: + +- For X.509, a root certificate authority is added to the GitLab trust store. + (A trust store is a repository of trusted security certificates.) Combined with + any required intermediate certificates in the signature, the developer's certificate + can be chained back to a trusted root certificate. +- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#adding-a-gpg-key-to-your-account) + to their account. + +GitLab uses its own certificate store and therefore defines the +[trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/). For a commit or tag to be *verified* by GitLab: -- The signing certificate email must match a verified email address used by the committer in GitLab. -- The Certificate Authority has to be trusted by the GitLab instance, see also - [Omnibus install custom public certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -- The signing time has to be within the time range of the [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5) +- The signing certificate email must match a verified email address in GitLab. +- The GitLab instance must be able to establish a full [trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/) + from the certificate in the signature to a trusted certificate in the GitLab certificate store. + This chain may include intermediate certificates supplied in the signature. You may + need to add certificates, such as Certificate Authority root certificates, + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +- The signing time must be in the time range of the + [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5), which is usually up to three years. -- The signing time is equal or later than commit time. - -NOTE: -Certificate revocation lists are checked on a daily basis via background worker. +- The signing time is equal to, or later than, the commit time. -NOTE: -Self signed certificates without `authorityKeyIdentifier`, -`subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We -recommend using certificates from a PKI that are in line with -[RFC 5280](https://tools.ietf.org/html/rfc5280). +If a commit's status has already been determined and stored in the database, +use the Rake task [to re-check the status](../../../../raketasks/x509_signatures.md). +Refer to the [Troubleshooting section](#troubleshooting). +GitLab checks certificate revocation lists on a daily basis with a background worker. ## Limitations +- Self-signed certificates without `authorityKeyIdentifier`, + `subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We + recommend using certificates from a PKI that are in line with + [RFC 5280](https://tools.ietf.org/html/rfc5280). - If you have more than one email in the Subject Alternative Name list in your signing certificate, [only the first one is used to verify commits](https://gitlab.com/gitlab-org/gitlab/-/issues/336677). - The `X509v3 Subject Key Identifier` (SKI) in the issuer certificate and the signing certificate [must be 40 characters long](https://gitlab.com/gitlab-org/gitlab/-/issues/332503). - If your SKI is shorter, commits will not show as verified in GitLab, and + If your SKI is shorter, commits don't show as verified in GitLab, and short subject key identifiers may also [cause errors when accessing the project](https://gitlab.com/gitlab-org/gitlab/-/issues/332464), such as 'An error occurred while loading commit signatures' and `HTTP 422 Unprocessable Entity` errors. -## Obtaining an X.509 key pair +## Configure for signed commits -If your organization has Public Key Infrastructure (PKI), that PKI provides -an S/MIME key. +To sign your commits, tags, or both, you must: -If you do not have an S/MIME key pair from a PKI, you can either create your -own self-signed one, or purchase one. MozillaZine keeps a nice collection -of [S/MIME-capable signing authorities](http://kb.mozillazine.org/Getting_an_SMIME_certificate) -and some of them generate keys for free. +1. [Obtain an X.509 key pair](#obtain-an-x509-key-pair). +1. [Associate your X.509 certificate with Git](#associate-your-x509-certificate-with-git). +1. [Sign and verify commits](#sign-and-verify-commits). +1. [Sign and verify tags](#sign-and-verify-tags). -## Associating your X.509 certificate with Git +### Obtain an X.509 key pair -To take advantage of X.509 signing, you need Git 2.19.0 or later. You can -check your Git version with: +If your organization has Public Key Infrastructure (PKI), that PKI provides +an S/MIME key. If you do not have an S/MIME key pair from a PKI, you can either +create your own self-signed pair, or purchase a pair. -```shell -git --version -``` +### Associate your X.509 certificate with Git + +To take advantage of X.509 signing, you need Git 2.19.0 or later. You can +check your Git version with the command `git --version`. If you have the correct version, you can proceed to configure Git. @@ -84,71 +94,267 @@ git config --global user.signingkey $signingkey git config --global gpg.format x509 ``` -### Windows and MacOS +#### Windows and macOS -Install [S/MIME Sign](https://github.com/github/smimesign) by downloading the -installer or via `brew install smimesign` on MacOS. +To configure Windows or macOS: -Get the ID of your certificate with `smimesign --list-keys` and set your -signing key `git config --global user.signingkey ID`, then configure X.509: +1. Install [S/MIME Sign](https://github.com/github/smimesign) by either: + - Downloading the installer. + - Running `brew install smimesign` on macOS. +1. Get the ID of your certificate by running `smimesign --list-keys`. +1. Set your signing key by running `git config --global user.signingkey ID`. +1. Configure X.509 with this command: -```shell -git config --global gpg.x509.program smimesign -git config --global gpg.format x509 -``` + ```shell + git config --global gpg.x509.program smimesign + git config --global gpg.format x509 + ``` -## Signing commits +### Sign and verify commits -After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you -can start signing your commits: +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you +can sign your commits: -1. Commit like you used to, the only difference is the addition of the `-S` flag: +1. When you create a Git commit, add the `-S` flag: ```shell git commit -S -m "feat: x509 signed commits" ``` -1. Push to GitLab and check that your commits [are verified](#verifying-commits). +1. Push to GitLab, and check that your commits are verified with the `--show-signature` flag: -If you don't want to type the `-S` flag every time you commit, you can tell Git -to sign your commits automatically: - -```shell -git config --global commit.gpgsign true -``` - -## Verifying commits + ```shell + git log --show-signature + ``` -To verify that a commit is signed, you can use the `--show-signature` flag: +1. *If you don't want to type the `-S` flag every time you commit,* run this command + for Git to sign your commits every time: -```shell -git log --show-signature -``` + ```shell + git config --global commit.gpgsign true + ``` -## Signing tags +### Sign and verify tags -After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you can start signing your tags: -1. Tag like you used to, the only difference is the addition of the `-s` flag: +1. When you create a Git tag, add the `-s` flag: ```shell git tag -s v1.1.1 -m "My signed tag" ``` -1. Push to GitLab and check that your tags [are verified](#verifying-tags). +1. Push to GitLab and verify your tags are signed with this command: + + ```shell + git tag --verify v1.1.1 + ``` + +1. *If you don't want to type the `-s` flag every time you tag,* run this command + for Git to sign your tags each time: -If you don't want to type the `-s` flag every time you tag, you can tell Git -to sign your tags automatically: + ```shell + git config --global tag.gpgsign true + ``` -```shell -git config --global tag.gpgsign true -``` +## Resources -## Verifying tags +- [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) -To verify that a tag is signed, you can use the `--verify` flag: +## Troubleshooting + +### Re-verify commits + +GitLab stores the status of any checked commits in the database. You can use a +Rake task to [check the status of any previously checked commits](../../../../raketasks/x509_signatures.md). + +After you make any changes, run this command: ```shell -git tag --verify v1.1.1 +sudo gitlab-rake gitlab:x509:update_signatures ``` + +### Main verification checks + +The code performs +[these key checks](https://gitlab.com/gitlab-org/gitlab/-/blob/v14.1.0-ee/lib/gitlab/x509/signature.rb#L33), +which all must return `verified`: + +- `x509_certificate.nil?` should be false. +- `x509_certificate.revoked?` should be false. +- `verified_signature` should be true. +- `user.nil?` should be false. +- `user.verified_emails.include?(@email)` should be true. +- `certificate_email == @email` should be true. + +To investigate why a commit shows as `Unverified`: + +1. [Start a Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```shell + sudo gitlab-rails console + ``` + +1. Identify the project (either by path or ID) and full commit SHA that you're investigating. + Use this information to create `signature` to run other checks against: + + ```ruby + project = Project.find_by_full_path('group/subgroup/project') + project = Project.find_by_id('121') + commit = project.repository.commit_by(oid: '87fdbd0f9382781442053b0b76da729344e37653') + signedcommit=Gitlab::X509::Commit.new(commit) + signature=Gitlab::X509::Signature.new(signedcommit.signature_text, signedcommit.signed_text, commit.committer_email, commit.created_at) + ``` + + If you make changes to address issues identified running through the checks, restart the + Rails console and run though the checks again from the start. + +1. Check the certificate on the commit: + + ```ruby + signature.x509_certificate.nil? + signature.x509_certificate.revoked? + ``` + + Both checks should return `false`: + + ```ruby + > signature.x509_certificate.nil? + => false + > signature.x509_certificate.revoked? + => false + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/332503) causes + these checks to fail with `Validation failed: Subject key identifier is invalid`. + +1. Run a cryptographic check on the signature. The code must return `true`: + + ```ruby + signature.verified_signature + ``` + + If it returns `false` then [investigate this check further](#cryptographic-verification-checks). + +1. Confirm the email addresses match on the commit and the signature: + + - The Rails console displays the email addresses being compared. + - The final command must return `true`: + + ```ruby + sigemail=signature.__send__:certificate_email + commitemail=commit.committer_email + sigemail == commitemail + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336677) exists: + only the first email in the `Subject Alternative Name` list is compared. To + display the `Subject Alternative Name` list, run: + + ```ruby + signature.__send__ :get_certificate_extension,'subjectAltName' + ``` + + If the developer's email address is not the first one in the list, this check + fails, and the commit is marked `unverified`. + +1. The email address on the commit must be associated with an account in GitLab. + This check should return `false`: + + ```ruby + signature.user.nil? + ``` + +1. Check the email address is associated with a user in GitLab. This check should + return a user, such as `#<User id:1234 @user_handle>`: + + ```ruby + User.find_by_any_email(commit.committer_email) + ``` + + If it returns `nil`, the email address is not associated with a user, and the check fails. + +1. Confirm the developer's email address is verified. This check must return true: + + ```ruby + signature.user.verified_emails.include?(commit.committer_email) + ``` + + If the previous check returned `nil`, this command displays an error: + + ```plaintext + NoMethodError (undefined method `verified_emails' for nil:NilClass) + ``` + +1. The verification status is stored in the database. To display the database record: + + ```ruby + pp X509CommitSignature.by_commit_sha(commit.sha);nil + ``` + + If all the previous checks returned the correct values: + + - `verification_status: "unverified"` indicates the database record needs + updating. [Use the Rake task](#re-verify-commits). + + - `[]` indicates the database doesn't have a record yet. Locate the commit + in GitLab to check the signature and store the result. + +#### Cryptographic verification checks + +If GitLab determines that `verified_signature` is `false`, investigate the reason +in the Rails console. These checks require `signature` to exist. Refer to the `signature` +step of the previous [main verification checks](#main-verification-checks). + +1. Check the signature, without checking the issuer, returns `true`: + + ```ruby + signature.__send__ :valid_signature? + ``` + +1. Check the signing time and date. This check must return `true`: + + ```ruby + signature.__send__ :valid_signing_time? + ``` + + - The code allows for code signing certificates to expire. + - A commit must be signed during the validity period of the certificate, + and at or after the commit's datestamp. Display the commit time and + certificate details including `not_before`, `not_after` with: + + ```ruby + commit.created_at + pp signature.__send__ :cert; nil + ``` + +1. Check the signature, including that TLS trust can be established. This check must return `true`: + + ```ruby + signature.__send__(:p7).verify([], signature.__send__(:cert_store), signature.__send__(:signed_text)) + ``` + + 1. If this fails, add the missing certificate(s) required to establish trust + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). + + 1. After adding more certificates, (if these troubleshooting steps then pass) + run the Rake task to [re-verify commits](#re-verify-commits). + + 1. Display the certificates, including in the signature: + + ```ruby + pp signature.__send__(:p7).certificates ; nil + ``` + +Ensure any additional intermediate certificate(s) and the root certificate are added +to the certificate store. For consistency with how certificate chains are built on +web servers: + +- Git clients that are signing commits should include the certificate + and all intermediate certificates in the signature. +- The GitLab certificate store should only contain the root. + +If you remove a root certificate from the GitLab +trust store, such as when it expires, commit signatures which chain back to that +root display as `unverified`. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index d46e55ca005..fa5ef35418a 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -244,8 +244,8 @@ Graph API instead of IMAP. Follow the [documentation in the incoming email secti gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" gitlab_rails['service_desk_email_mailbox_name'] = "inbox" gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_inbox_options'] = { + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { 'tenant_id': '<YOUR-TENANT-ID>', 'client_id': '<YOUR-CLIENT-ID>', 'client_secret': '<YOUR-CLIENT-SECRET>', diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 52e064ef66e..662d7e70910 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -45,6 +45,8 @@ Note the following: a maintainer or administrator role in the group where the exported project lives. - Project members with the [Owner role](../../permissions.md) are imported as Maintainers. - Imported users can be mapped by their public email on self-managed instances, if an administrative user (not an owner) does the import. + Additionally, the user must be an existing member of the namespace, or the user can be added as a +member of the project for contributions to be mapped. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues are owned by the importer. - For project migration imports performed over GitLab.com Groups, preserving author information is @@ -217,7 +219,7 @@ GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) ## Troubleshooting -### Import workaround for large repositories +### Import workaround for large repositories [Maximum import size limitations](#import-the-project) can prevent an import from being successful. @@ -225,7 +227,7 @@ If changing the import limits is not possible, the following local workflow can be used to temporarily reduce the repository size for another import attempt. -1. Create a temporary working directory from the export: +1. Create a temporary working directory from the export: ```shell EXPORT=<filename-without-extension> @@ -238,9 +240,11 @@ reduce the repository size for another import attempt. # Prevent interference with recreating an importable file later mv project.bundle ../"$EXPORT"-original.bundle mv ../"$EXPORT".tar.gz ../"$EXPORT"-original.tar.gz + + git switch --create smaller-tmp-main ``` -1. To reduce the repository size, +1. To reduce the repository size, work on this `smaller-tmp-main` branch: [identify and remove large files](../repository/reducing_the_repo_size_using_git.md) or [interactively rebase and fixup](../../../topics/git/git_rebase.md#interactive-rebase) to reduce the number of commits. @@ -252,7 +256,7 @@ reduce the repository size for another import attempt. git gc --prune=now --aggressive # Prepare recreating an importable file - git bundle create ../project.bundle <default-branch-name> + git bundle create ../project.bundle smaller-tmp-main cd .. mv project/ ../"$EXPORT"-project cd .. @@ -268,5 +272,5 @@ reduce the repository size for another import attempt. 1. Update the imported repository's [branch protection rules](../protected_branches.md) and its [default branch](../repository/branches/default.md), and - delete the temporary, `smaller-…` branch, and + delete the temporary, `smaller-tmp-main` branch, and the local, temporary data. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 66fdace81ba..8b159a75451 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -87,59 +87,64 @@ Example `.compliance-gitlab-ci.yml` # Allows compliance team to control the ordering and interweaving of stages/jobs. # Stages without jobs defined will remain hidden. stages: -- pre-compliance -- build -- test -- pre-deploy-compliance -- deploy -- post-compliance - -variables: # can be overriden by a developer's local .gitlab-ci.yml + - pre-compliance + - build + - test + - pre-deploy-compliance + - deploy + - post-compliance + +variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml FOO: sast -sast: # none of these attributes can be overriden by a developer's local .gitlab-ci.yml +sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml variables: FOO: sast image: ruby:2.6 stage: pre-compliance rules: - - when: always + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success allow_failure: false before_script: - - "# No before scripts." + - "# No before scripts." script: - - echo "running $FOO" + - echo "running $FOO" after_script: - - "# No after scripts." + - "# No after scripts." sanity check: image: ruby:2.6 stage: pre-deploy-compliance rules: - - when: always + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success allow_failure: false before_script: - - "# No before scripts." + - "# No before scripts." script: - - echo "running $FOO" + - echo "running $FOO" after_script: - - "# No after scripts." - + - "# No after scripts." audit trail: image: ruby:2.6 stage: post-compliance rules: - - when: always + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success allow_failure: false before_script: - - "# No before scripts." + - "# No before scripts." script: - - echo "running $FOO" + - echo "running $FOO" after_script: - - "# No after scripts." + - "# No after scripts." -include: # Execute individual project's configuration +include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) project: '$CI_PROJECT_PATH' file: '$CI_CONFIG_PATH' ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch. @@ -174,7 +179,7 @@ cannot change them: - Explicitly set the container image file to run the job in. This ensures that your script steps execute in the correct environment. - Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/index.md#job-keywords). - This ensures that your job uses the settings you intend and that they are not overriden by + This ensures that your job uses the settings you intend and that they are not overridden by project-level pipelines. ### Sharing and permissions @@ -187,33 +192,34 @@ section. You can now change the [Project visibility](../../../public_access/public_access.md). If you set **Project Visibility** to public, you can limit access to some features to **Only Project Members**. In addition, you can select the option to -[Allow users to request access](../members/index.md#prevent-users-from-requesting-access-to-a-project). +[Allow users to request access](../members/index.md#request-access-to-a-project). Use the switches to enable or disable the following features: -| Option | More access limit options | Description | -|:----------------------------------|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Issues** | ✓ | Activates the GitLab issues tracker | -| **Repository** | ✓ | Enables [repository](../repository/) functionality | -| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | -| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality | -| **Pipelines** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality | -| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | -| **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | -| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality | -| **Analytics** | ✓ | Enables [analytics](../../analytics/) | -| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/) | -| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md) | -| **Pages** | ✓ | Allows you to [publish static websites](../pages/) | -| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md) -| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md) | -| **Operations Dashboard** | ✓ | Control access to [operations dashboard](../../../operations/index.md) +| Option | More access limit options | Description | +|:---------------------------------|:--------------------------|:--------------| +| **Issues** | ✓ | Activates the GitLab issues tracker. | +| **Repository** | ✓ | Enables [repository](../repository/) functionality | +| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings). | +| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | +| **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | +| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | +| **CI/CD** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality. | +| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images. | +| **Analytics** | ✓ | Enables [analytics](../../analytics/). | +| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | +| **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | +| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/). | +| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | +| **Pages** | ✓ | Allows you to [publish static websites](../pages/). | +| **Operations** | ✓ | Control access to [operations dashboard](../../../operations/index.md). | +| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | Some features depend on others: - If you disable the **Issues** option, GitLab also removes the following features: - - **Issue Boards** + - **issue boards** - [**Service Desk**](#service-desk) NOTE: @@ -227,7 +233,7 @@ Some features depend on others: - If you disable **Repository** functionality, GitLab also disables the following features for your project: - **Merge Requests** - - **Pipelines** + - **CI/CD** - **Container Registry** - **Git Large File Storage** - **Packages** @@ -247,7 +253,7 @@ setting **Enable CVE ID requests in the issue sidebar**. #### Disabling email notifications -Project owners can disable all [email notifications](../../profile/notifications.md#gitlab-notification-emails) +Project owners can disable all [email notifications](../../profile/notifications.md) related to the project by selecting the **Disable email notifications** checkbox. ### Merge request settings @@ -350,7 +356,7 @@ to transfer a project. You can transfer an existing project into a [group](../../group/index.md) if: -- You have at least the Maintainer** role in that group. +- You have at least **Maintainer** [role](../../permissions.md#project-members-permissions) in that group. - You're at least an **Owner** of the project to be transferred. - The group to which the project is being transferred to must allow creation of new projects. @@ -457,7 +463,7 @@ To do so: 1. Confirm the action by typing the project's path as instructed. NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +Only project owners have the [permissions](../../permissions.md#project-members-permissions) to remove a fork relationship. ## Monitor settings diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 643042cb96a..cae9276eafd 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -7,25 +7,30 @@ type: reference, howto # Project access tokens -NOTE: -Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). Self-managed Free instances should review their security and compliance policies with regards to [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups) and consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. - > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. > - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md) +except they are attached to a project rather than a user. They can be used to: + +- Authenticate with the [GitLab API](../../../api/index.md#personalproject-access-tokens). +- Authenticate with Git using HTTP Basic Authentication. If you are asked for a username when + authenticating, you can use any non-empty value because only the token is needed. -Project access tokens are scoped to a project and can be used to authenticate with the -[GitLab API](../../../api/index.md#personalproject-access-tokens). You can also use -project access tokens with Git to authenticate over HTTPS. If you are asked for a -username when authenticating over HTTPS, you can use any non-empty value because only -the token is needed. +Project access tokens: -Project access tokens expire on the date you define, at midnight UTC. +- Expire on the date you define, at midnight UTC. +- Are supported for self-managed instances on Free tier and above. Free self-managed instances + should: + - Review their security and compliance policies with regards to + [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). + - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to + lower potential abuse. +- Are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/).) -For examples of how you can use a project access token to authenticate with the API, see the following section from our [API Docs](../../../api/index.md#personalproject-access-tokens). +For examples of how you can use a project access token to authenticate with the API, see the +[relevant section from our API Docs](../../../api/index.md#personalproject-access-tokens). ## Creating a project access token @@ -60,10 +65,7 @@ API calls made with a project access token are associated with the corresponding These bot users are included in a project's **Project information > Members** list but cannot be modified. Also, a bot user cannot be added to any other project. -- The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. -- The username is set to `project_{project_id}_bot{bot_count}` for further access tokens, such as `project_123_bot1`. - -When the project access token is [revoked](#revoking-a-project-access-token) the bot user is deleted +When the project access token is [revoked](#revoking-a-project-access-token), the bot user is deleted and all records are moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 2b901ddc17b..8902bdc21c4 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -115,7 +115,7 @@ In GitLab self-managed instances, you can limit the display of time units to hours. To do so: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Localization**. 1. Under **Time tracking**, select the **Limit display of time tracking units to hours** checkbox. diff --git a/doc/user/project/web_ide/img/open_web_ide.png b/doc/user/project/web_ide/img/open_web_ide.png Binary files differdeleted file mode 100644 index 02a5a564472..00000000000 --- a/doc/user/project/web_ide/img/open_web_ide.png +++ /dev/null diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 160c2314ded..010a63b7957 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -16,9 +16,22 @@ projects by providing an advanced editor with commit staging. ## Open the Web IDE You can open the Web IDE when viewing a file, from the repository file list, -and from merge requests. - - +and from merge requests: + +- *When viewing a file, or the repository file list* - + 1. In the upper right corner of the page, select **Edit in Web IDE** if it is visible. + 1. If **Edit in Web IDE** is not visible: + 1. Select the **(angle-down)** next to **Edit** or **Gitpod**, depending on your configuration. + 1. Select **Edit in Web IDE** from the list to display it as the editing option. + 1. Select **Edit in Web IDE** to open the editor. +- *When viewing a merge request* - + 1. Go to your merge request, and select the **Overview** tab. + 1. Scroll to the widgets area, after the merge request description. + 1. Select **Edit in Web IDE** if it is visible. + 1. If **Edit in Web IDE** is not visible: + 1. Select the **(angle-down)** next to **Open in Gitpod**. + 1. Select **Open in Web IDE** from the list to display it as the editing option. + 1. Select **Open in Web IDE** to open the editor. ## File finder @@ -249,7 +262,7 @@ The image is uploaded to the same directory and is named `image.png` by default. If another file already exists with the same name, a numeric suffix is automatically added to the filename. -There are two ways to preview Markdown content in the Web IDE: +There are two ways to preview Markdown content in the Web IDE: 1. At the top of the file's tab, select **Preview Markdown** to preview the formatting in your file. You can't edit the file in this view. @@ -280,8 +293,8 @@ a `main` entry point inside the Web IDE. Live Preview is enabled for all projects on GitLab.com. If you are an administrator of a self-managed GitLab instance, and you want to enable Live Preview: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Scroll to **Web IDE** and select **Expand**:  1. Select **Enable Live Preview** and select **Save changes**. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 0507b6b78ca..d0a1f485fa8 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -46,13 +46,17 @@ for previously created wikis. ## Create the wiki home page -When a wiki is created, it is empty. On your first visit, create the landing page -users see when viewing the wiki: +When a wiki is created, it is empty. On your first visit, you can create the +home page users see when viewing the wiki. This page requires a specific title +to be used as your wiki's home page. To create it: 1. Go to your project or group and select **Wiki**. 1. Select **Create your first page**. +1. GitLab requires this first page be titled `home`. The page with this + title serves as the front page for your wiki. 1. Select a **Format** for styling your text. -1. Add a welcome message in the **Content** section. You can always edit it later. +1. Add a welcome message for your home page in the **Content** section. You can + always edit it later. 1. Add a **Commit message**. Git requires a commit message, so GitLab creates one if you don't enter one yourself. 1. Select **Create page**. @@ -105,7 +109,7 @@ Wiki pages are stored as files in a Git repository, so certain characters have a ### Length restrictions for file and directory names -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. Many common file systems have a [limit of 255 bytes](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits) for file and directory names. Git and GitLab both support paths exceeding @@ -123,7 +127,7 @@ may not be able to check out the wiki locally afterward. ## Edit a wiki page -You need the [Developer role](../../permissions.md) or higher to edit a wiki page: +You need at least the [Developer role](../../permissions.md) to edit a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to edit. @@ -138,7 +142,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). ## Delete a wiki page -You need the [Maintainer role](../../permissions.md) or higher to delete a wiki page: +You need at least the [Maintainer role](../../permissions.md) to delete a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to delete. @@ -148,7 +152,7 @@ You need the [Maintainer role](../../permissions.md) or higher to delete a wiki ## Move a wiki page -You need the [Developer role](../../permissions.md) or higher to move a wiki page: +You need at least the [Developer role](../../permissions.md) to move a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to move. @@ -175,7 +179,7 @@ From the history page you can see: ### View changes between page versions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. You can see the changes made in a version of a wiki page, similar to versioned diff file views: @@ -201,9 +205,9 @@ Commits to wikis are not counted in [repository analytics](../../analytics/repos ## Customize sidebar -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. -You need Developer [permissions](../../permissions.md) or higher to customize the wiki +You need at least the [Developer role](../../permissions.md) to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: @@ -238,7 +242,7 @@ Administrators for self-managed GitLab installs can ## Group wikis **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. Group wikis work the same way as project wikis. Their usage is similar to project wikis, with a few limitations: @@ -306,7 +310,7 @@ to disable the wiki but toggle it on (in blue). ## Content Editor **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. GitLab version 14.0 introduces a WYSIWYG editing experience for GitLab Flavored Markdown in Wikis through the [Content Editor](../../../development/fe_guide/content_editor.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 77dd44e5c7f..32bb202767a 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -334,6 +334,52 @@ git config --global url."https://${user}:${personal_access_token}@gitlab.example git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" ``` +### Fetch Go modules from Geo secondary sites + +As Go modules are stored in Git repositories, you can use the [Geo](../../administration/geo/index.md) +feature that allows Git repositories to be accessed on the secondary Geo servers. + +In the following examples, the primary's site domain name is `gitlab.example.com`, +and the secondary's is `gitlab-secondary.example.com`. + +`go get` will initially generate some HTTP traffic to the primary, but when the module +download commences, the `insteadOf` configuration sends the traffic to the secondary. + +#### Use SSH to access the Geo secondary + +To fetch Go modules from the secondary using SSH: + +1. Reconfigure Git on the client to send traffic for the primary to the secondary: + + ```plaintext + git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" + git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" + ``` + +1. Ensure the client is set up for SSH access to GitLab repositories. This can be tested on the primary, + and GitLab will replicate the public key to the secondary. + +#### Use HTTP to access the Geo secondary + +Using HTTP to fetch Go modules does not work with CI/CD job tokens, only with +persistent access tokens that are replicated to the secondary. + +To fetch Go modules from the secondary using HTTP: + +1. Put in place a Git `insteadOf` redirect on the client: + + ```plaintext + git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" + ``` + +1. Generate a [personal access token](../profile/personal_access_tokens.md) and + provide those credentials in the client's `~/.netrc` file: + + ```plaintext + machine gitlab.example.com login USERNAME password TOKEN + machine gitlab-secondary.example.com login USERNAME password TOKEN + ``` + ## Access project page with project ID > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index f29ac531d2e..f994539b9fc 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -119,3 +119,24 @@ You can search a specific issue or merge request by its ID with a special prefix - To search by issue ID, use prefix `#` followed by issue ID. For example, [#23456](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964) - To search by merge request ID, use prefix `!` followed by merge request ID. For example [!23456](https://gitlab.com/search?snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964) + +## Global search scopes **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68640) in GitLab 14.3. + +To improve the performance of your instance's global search, you can limit +the scope of the search. To do so, you can exclude global search scopes by disabling +[`ops` feature flags](../../development/feature_flags/index.md#ops-type). + +Global search has all its scopes **enabled** by default in GitLab SaaS and +self-managed instances. A GitLab administrator can disable the following `ops` +feature flags to limit the scope of your instance's global search and optimize +its performance: + +| Scope | Feature flag | Description | +|--|--|--| +| Code | `global_search_code_tab` | When enabled, the global search includes code as part of the search. | +| Commits | `global_search_commits_tab` | When enabled, the global search includes commits as part of the search. | +| Issues | `global_search_issues_tab` | When enabled, the global search includes issues as part of the search. | +| Merge Requests | `global_search_merge_requests_tab` | When enabled, the global search includes merge requests as part of the search. | +| Wiki | `global_search_wiki_tab` | When enabled, the global search includes wiki as part of the search. | diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 92d01e6a43e..7cf62f09303 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -27,8 +27,8 @@ When you click **Issues**, GitLab shows the opened issues assigned to you: You can search through **Open**, **Closed**, or **All** issues. -You can also filter the results using the search and filter field, as described below in -[Filtering issue and merge request lists](#filtering-issue-and-merge-request-lists). +You can also filter the results using the search and filter field, as described in +[Filter issue and merge request lists](#filter-issue-and-merge-request-lists). ### Issues and MRs assigned to you or created by you @@ -37,11 +37,11 @@ in the search field in the upper right corner:  -### Filtering issue and merge request lists +### Filter issue and merge request lists -> - Filtering by Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab Ultimate 12.9. -> - Filtering by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in GitLab Ultimate 13.0. -> - Filtering by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. Moved to GitLab Premium in 13.9. +> - Filter by Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab Ultimate 12.9. +> - Filter by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in GitLab Ultimate 13.0. +> - Filter by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. Moved to GitLab Premium in 13.9. Follow these steps to filter the **Issues** and **Merge Requests** list pages in projects and groups: @@ -64,12 +64,13 @@ groups: - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18059) in GitLab 12.7) 1. Enter the text to [filter the attribute by](#filters-autocomplete). 1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical - `AND`. + `AND`. For example, filtering by an Author and Milestone `!=` 12.6 filters for the issues where the + author matches your selection, and the milestone is not 12.6: -For example, filtering by Author `=` Jane and Milestone `!=` 12.6 filters for the issues where Jane -is the author and the milestone is not 12.6. +  - +GitLab displays the results on-screen, but you can also +[retrieve them as an RSS feed](#retrieve-search-results-as-feed). ### Filtering by **None** / **Any** @@ -96,6 +97,21 @@ You can filter issues and merge requests by specific terms included in titles or  +### Retrieve search results as feed + +> Feeds for merge requests were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66336) in GitLab 14.3. + +GitLab provides RSS feeds of search results for your project. To subscribe to the +RSS feed of search results: + +1. Go to your project's page. +1. On the left sidebar, select **Issues** or **Merge requests**. +1. Build your search query as described in [Filter issue and merge request lists](#filter-issue-and-merge-request-lists). +1. Select the feed symbol **{rss}** to display the results as an RSS feed in Atom format. + +The URL of the result contains both a feed token, and your search query. +You can add this URL to your feed reader. + ### Filtering by ID > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. @@ -217,12 +233,12 @@ filters them for you as you type. You can also **Explore** all public and internal groups available in GitLab.com, and sort them by **Last created**, **Oldest created**, **Last updated**, or **Oldest updated**. -## Issue Boards +## Issue boards -From an [Issue Board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. +From an [issue board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. You can also filter them by name (issue title), from the field **Filter by name**, which is loaded as you type. -To search for issues to add to lists present in your Issue Board, click +To search for issues to add to lists present in your issue board, click the button **Add issues** on the top-right of your screen, opening a modal window from which you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, and **Labels**, select multiple issues to add to a list of your choice: diff --git a/doc/user/workspace/img/hardware_settings.png b/doc/user/workspace/img/hardware_settings.png Binary files differindex ff460918f25..919ff46f8c8 100644 --- a/doc/user/workspace/img/hardware_settings.png +++ b/doc/user/workspace/img/hardware_settings.png diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index d9c9d19721b..2ce30c645d5 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -1,25 +1,25 @@ --- stage: Manage -group: Access +group: Workspace info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Workspace -Workspace will be the top [namespace](../group/index.md#namespaces) for you to manage -everything GitLab, including: +Workspace will be above the [top-level namespaces](../group/index.md#namespaces) for you to manage everything you can do as a GitLab administrator, including: - Defining and applying settings to all of your groups, subgroups, and projects. - Aggregating data from all your groups, subgroups, and projects. -Workspace will take many of the features from the -[Admin Area](../admin_area/index.md) and will: +The functionality in the [Admin Area](../admin_area/index.md) of self-managed installations will be split up and go to: -- Enable a top namespace for GitLab.com. -- Eventually replace the instance level for self-managed installations. +1. Groups (available in the Workspace, Top-level group namespaces, and Sub-groups) +1. Hardware Controls (for functionality that does not apply to groups) -Our goal is to reach feature parity between SaaS and self-managed installations, with one -exception: **Hardware Controls** will appear **only** on self-managed installations. +Our goal is to reach feature parity between SaaS and Self-Managed installations, with all [Admin Area settings](/ee/user/admin_area/settings/) moving to either: + +- Workspace (contains features relevant to both GitLab-managed and self-managed installations) with a dedicated Settings menu available within the left navigation bar. +- Hardware controls (only contains features relative to Self-Managed installations, with one per installation). NOTE: Workspace is currently in development. |
