diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-20 02:18:09 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-20 02:18:09 +0300 |
| commit | 6ed4ec3e0b1340f96b7c043ef51d1b33bbe85fde (patch) | |
| tree | dc4d20fe6064752c0bd323187252c77e0a89144b /doc/user | |
| parent | 9868dae7fc0655bd7ce4a6887d4e6d487690eeed (diff) | |
Add latest changes from gitlab-org/gitlab@15-4-stable-eev15.4.0-rc42
Diffstat (limited to 'doc/user')
313 files changed, 5202 insertions, 2629 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_reports.md b/doc/user/admin_area/analytics/dev_ops_reports.md index 2ad18d5f70e..b4471a4602a 100644 --- a/doc/user/admin_area/analytics/dev_ops_reports.md +++ b/doc/user/admin_area/analytics/dev_ops_reports.md @@ -12,7 +12,7 @@ from planning to monitoring. To see DevOps Reports: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Analytics > DevOps Reports**. ## DevOps Score diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 9315b926acc..9147a48aa8e 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -10,7 +10,7 @@ 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**. +1. On the top bar, select **Main 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 5f46908adb0..f21ee627f7f 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 data refreshes daily. To view Usage Trends: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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 4c3bdde223b..fbc2f8d1827 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -10,12 +10,12 @@ disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page. Several options are available for customizing the appearance of a self-managed instance of GitLab. To access these settings: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Appearance**. -## Navigation bar +## Top bar -By default, the navigation bar has the GitLab logo, but this can be customized with +By default, the **top bar** has the GitLab logo, but this can be customized with any image desired. It is optimized for images 28px high (any width), but any image can be used (less than 1 MB) and it is automatically resized. diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index a6e6a839912..b508b71ddac 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -57,7 +57,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**. +1. On the top bar, select **Main 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: @@ -83,7 +83,7 @@ If you must make changes to a broadcast message, you can edit it. To edit a broadcast message: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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**. @@ -97,7 +97,7 @@ You can delete a broadcast message while it's active. To delete a broadcast message: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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 4308b45df78..02c4cd05b23 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -31,7 +31,7 @@ You can also [revoke](#revoke-a-users-personal-access-token) and [delete](#delet To access the Credentials inventory: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Credentials**. ## Revoke a user's personal access token diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index c3c580a91c3..0c03652bfb5 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -34,7 +34,7 @@ To set project templates at the group level, see [Custom group-level project tem To select the group to use as the source for the project templates: -1. On the top bar, navigate to **Menu > Admin > Settings > Templates**. +1. On the top bar, navigate to **Main menu > Admin > Settings > Templates**. 1. Expand **Custom project templates**. 1. Select a group to use. 1. Select **Save changes**. diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index b50748ca97e..f646d9f95fd 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -33,7 +33,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for the diff limit. diff --git a/doc/user/admin_area/email_from_gitlab.md b/doc/user/admin_area/email_from_gitlab.md index 52f27ed48e0..09643fc290e 100644 --- a/doc/user/admin_area/email_from_gitlab.md +++ b/doc/user/admin_area/email_from_gitlab.md @@ -22,7 +22,7 @@ For information about email notifications originating from GitLab, read ## Sending emails to users from GitLab -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select **Send email to users**. diff --git a/doc/user/admin_area/geo_sites.md b/doc/user/admin_area/geo_sites.md index e577fdf60f1..fecc0e7c541 100644 --- a/doc/user/admin_area/geo_sites.md +++ b/doc/user/admin_area/geo_sites.md @@ -11,7 +11,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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Geo > Sites**. ## Common settings @@ -71,7 +71,7 @@ the primary uses the secondary's internal URL to contact it directly. The internal URL defaults to external URL. To change it: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Geo > Sites**. 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 c689d61ad68..207b7e6f2d8 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 administrator, you can access the Admin Ar 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**. +- GitLab versions 14.0 and later: on the top bar, select **Main 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**. +- On the top bar, select **Main 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,7 +71,7 @@ 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**. +1. On the top bar, select **Main 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. @@ -112,7 +112,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. To list users matching a specific criteria, select one of the following tabs on the **Users** page: @@ -157,7 +157,7 @@ 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**. + 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Impersonate**. @@ -175,7 +175,7 @@ By default, impersonation is enabled. GitLab can be configured to [disable imper When using authentication providers, administrators can see the identities for a user: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Identities**. @@ -221,7 +221,7 @@ GitLab billing is based on the number of [**Billable users**](../../subscription You must be an administrator to manually add emails to users: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users** (`/admin/users`). 1. Locate the user and select them. 1. Select **Edit**. @@ -237,7 +237,7 @@ The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and By default, users can create groups. To prevent a user from creating a top level group: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users** (`/admin/users`). 1. Locate the user and select them. 1. Select **Edit**. @@ -252,7 +252,7 @@ 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**. +1. On the top bar, select **Main 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, @@ -277,7 +277,7 @@ GitLab instance from the Admin Area's Topics page. To access the Topics page: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Topics**. For each topic, the page displays its name and the number of projects labeled with the topic. @@ -288,6 +288,8 @@ To edit a topic, select **Edit** in that topic's row. To remove a topic, select **Remove** in that topic's row. +To remove a topic and move all assigned projects to another topic, select **Merge topics**. + To search for topics by name, enter your criteria in the search box. The topic search is case insensitive and applies partial matching. @@ -302,7 +304,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Jobs**. All jobs are listed, in descending order of job ID. 1. Select the **All** tab to list all jobs. Select the **Pending**, **Running**, or **Finished** tab to list only jobs of that status. @@ -328,7 +330,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Runners**. #### Search and filter runners @@ -347,6 +349,22 @@ You can also filter runners by status, type, and tag. To filter:  +#### Bulk delete runners + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370241) in GitLab 15.4 [with a flag](../../administration/feature_flags.md) named `admin_runners_bulk_delete`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `admin_runners_bulk_delete`. On GitLab.com, this feature is not available but can be enabled by GitLab.com administrators. + +You can delete multiple runners at the same time. + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Overview > Runners**. +1. To the left of the runners you want to delete, select the checkbox. + To select all of the runners on the page, select the checkbox above + the list. +1. Select **Delete selected**. + #### Runner attributes For each runner, the following attributes are listed: @@ -369,7 +387,7 @@ page. For more details, see [Gitaly](../../administration/gitaly/index.md). To access the **Gitaly Servers** page: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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 ac5e5ded859..a5338aa35b8 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -28,7 +28,7 @@ To activate your instance with an activation code: - Your subscription confirmation email. - The [Customers Portal](https://customers.gitlab.com/customers/sign_in), on the **Manage Purchases** page. 1. Sign in to your GitLab self-managed instance. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Subscription**. 1. Paste the activation code in **Activation code**. 1. Read and accept the terms of service. diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md index 99669b2a4d3..352d79ee381 100644 --- a/doc/user/admin_area/license_file.md +++ b/doc/user/admin_area/license_file.md @@ -18,7 +18,7 @@ link to the **Add license** page should be displayed. Otherwise, to add your license: 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. In the **Add License** area, add a license by either uploading the file or entering the key. 1. Select the **Terms of Service** checkbox. @@ -79,7 +79,7 @@ To go back to Free features, [delete all expired licenses](#remove-a-license). To remove a license from a self-managed instance: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Subscription**. 1. Select **Remove license**. @@ -89,7 +89,7 @@ Repeat these steps to remove all licenses, including those applied in the past. To view your license details: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Subscription**. You can add and view more than one license, but only the latest license in diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index e090d4e7f88..38b177766cf 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -19,7 +19,7 @@ and can no longer be changed: To enable merge request approval settings for an instance: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request approvals**. 1. Choose the required options. 1. Select **Save changes**. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index ab581cd3aa8..6d632a6bdb6 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -40,7 +40,7 @@ sign in. To view user sign ups pending approval: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. @@ -50,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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. 1. Optional. Select a user. @@ -75,7 +75,7 @@ administrators can choose to block the user. Users can be blocked [via an abuse report](review_abuse_reports.md#blocking-users), by removing them in LDAP, or directly from the Admin Area. To do this: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. @@ -98,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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Blocked** tab. 1. Optional. Select a user. @@ -114,7 +114,7 @@ Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-us The unblock option may be unavailable for LDAP users. To enable the unblock option, the LDAP identity first needs to be deleted: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Blocked** tab. 1. Select a user. @@ -153,7 +153,7 @@ Users are notified about account deactivation if A user can be deactivated from the Admin Area. To do this: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. @@ -169,19 +169,21 @@ Users can also be deactivated using the [GitLab API](../../api/users.md#deactiva ### Automatically deactivate dormant users -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320875) in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320875) in GitLab 14.0. +> - Customizable time period [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336747) in GitLab 15.4 Administrators can enable automatic deactivation of users who either: - Were created more than a week ago and have not signed in. -- Have no activity in the last 90 days. +- Have no activity for a specified period of time (defaults to 90 days). To do this: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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**. +1. Under **Period of inactivity (days)**, enter a period of time before deactivation. 1. Select **Save changes**. When this feature is enabled, GitLab runs a job once a day to deactivate the dormant users. @@ -196,7 +198,7 @@ A deactivated user can be activated from the Admin Area. To do this: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Deactivated** tab. 1. Optional. Select a user. @@ -229,7 +231,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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. @@ -241,7 +243,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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Banned** tab. 1. Optional. Select a user. @@ -255,7 +257,7 @@ The user's state is set to active and they consume a Use the Admin Area to delete users. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Banned** tab. 1. Optional. Select a user. @@ -269,7 +271,7 @@ You can only delete a user if there are inherited or direct owners of a group. Y You can also delete a user and their contributions, such as merge requests, issues, and groups of which they are the only group owner. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index 87374849674..092a49dc7e9 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -59,7 +59,8 @@ Use the following database queries to see the state of the current batched backg ```sql SELECT - id job_class_name, + id, + job_class_name, table_name, column_name, job_arguments diff --git a/doc/user/admin_area/reporting/git_abuse_rate_limit.md b/doc/user/admin_area/reporting/git_abuse_rate_limit.md index ad3ecfa3a5a..11b0e2403aa 100644 --- a/doc/user/admin_area/reporting/git_abuse_rate_limit.md +++ b/doc/user/admin_area/reporting/git_abuse_rate_limit.md @@ -19,7 +19,7 @@ When both flags are enabled, the administrator receives an email when a user is ## Configure Git abuse rate limiting -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Reporting**. 1. Expand **Git abuse rate limit**. 1. Update the Git abuse rate limit settings: diff --git a/doc/user/admin_area/reporting/spamcheck.md b/doc/user/admin_area/reporting/spamcheck.md index 2360c1f2899..670b0521732 100644 --- a/doc/user/admin_area/reporting/spamcheck.md +++ b/doc/user/admin_area/reporting/spamcheck.md @@ -40,7 +40,7 @@ Spamcheck is only available for package-based installations: ## Configure GitLab to use Spamcheck -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Reporting**. 1. Expand **Spam and Anti-bot Protection**. 1. Update the Spam Check settings: diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index a5e7fcb1b8e..16295f340d8 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: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Reporting**. 1. Expand the **Abuse reports** section. 1. Provide an email address and select **Save changes**. @@ -26,14 +26,14 @@ The notification email address can also be set and retrieved ## Reporting abuse -To find out more about reporting abuse, see +To find out more about reporting abuse, see [abuse reports user documentation](../report_abuse.md). ## Resolving abuse reports To access abuse reports: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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 e33cf4a9082..e8f80cfb40f 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -16,7 +16,7 @@ the [project limits for existing users](#projects-limit-for-a-user). To configure the maximum number of projects in personal namespaces for new users: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease that **Default projects limit** value. @@ -28,7 +28,7 @@ in their users personal namespace. However, projects can still be created in a g You can edit a specific user, and change the maximum number of projects this user can create in their personal namespace: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview** > **Users**. 1. From the list of users, select a user. 1. Select **Edit**. @@ -39,7 +39,7 @@ can create in their personal namespace: The maximum file size for attachments in GitLab comments and replies is 10 MB. To change the maximum attachment size: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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)**. @@ -53,7 +53,7 @@ For GitLab.com repository size limits, read [accounts and limit settings](../../ You can change the maximum push size for your instance: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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)**. @@ -72,7 +72,7 @@ Use [Git LFS](../../../topics/git/lfs/index.md) to add large files to a reposito To modify the maximum file size for exports in GitLab: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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 export size (MB)**. @@ -82,7 +82,7 @@ To modify the maximum file size for exports in GitLab: To modify the maximum file size for imports in GitLab: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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)**. @@ -108,7 +108,7 @@ The default prefix is `glpat-` but administrators can change it. To change the default global prefix: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. @@ -154,7 +154,7 @@ These settings can be found in: 1. Fill in the **Repository size limit (MB)** field in the **Naming, visibility** section. 1. Select **Save changes**. - GitLab global settings: - 1. On the top bar, select **Menu > Admin**. + 1. On the top bar, select **Main 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. @@ -182,7 +182,7 @@ GitLab administrators can choose to customize the session duration (in minutes) To set a limit on how long these sessions are valid: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. @@ -209,7 +209,7 @@ there are no restrictions. To set a lifetime on how long SSH keys are valid: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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 SSH keys (days)** field. @@ -225,18 +225,6 @@ Once a lifetime for SSH keys is set, GitLab: NOTE: When a user's SSH key becomes invalid they can delete and re-add the same key again. -<!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> -## Allow expired SSH keys to be used (removed) **(ULTIMATE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250480) in GitLab 13.9. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320970) in GitLab 14.0. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 14.8. -> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 15.0. - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 14.8. -This feature was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 15.0. -<!--- end_remove --> - ## Limit the lifetime of access tokens **(ULTIMATE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. @@ -257,7 +245,7 @@ there are no restrictions. To set a lifetime on how long access tokens are valid: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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 access tokens (days)** field. @@ -291,7 +279,7 @@ To maintain integrity of user details in [Audit Events](../../../administration/ To do this: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 638b61f6197..dab3c78d9d1 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**. +1. On the top bar, select **Main 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) @@ -32,7 +32,7 @@ If you want to disable it for a specific project, you can do so in You can set all new projects to have the instance's shared runners available by default. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Select the **Enable shared runners for new projects** checkbox. @@ -48,7 +48,7 @@ limit on the number of [CI/CD minutes](../../../ci/pipelines/cicd_minutes.md) yo To enable a specific runner for one or more projects: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. From the left sidebar, select **Overview > Runners**. 1. Select the runner you want to edit. 1. In the top right, select **Edit** (**{pencil}**). @@ -61,7 +61,7 @@ To enable a specific runner for one or more projects: To display details about the instance's shared runners in all projects' runner settings: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Enter text, including Markdown if you want, in the **Shared runner details** field. For example: @@ -70,7 +70,7 @@ runner settings: To view the rendered details: -1. On the top bar, select **Menu > Project** and select any group or project. +1. On the top bar, select **Main menu > Projects** or **Main menu > Groups** and find your project or group. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Runners**. @@ -90,7 +90,7 @@ The value is in MB and the default is 100MB per job. To change it at the: - Instance level: - 1. On the top bar, select **Menu > Admin**. + 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD > Continuous Integration and Deployment**. 1. Change the value of **Maximum artifacts size (MB)**. 1. Select **Save changes** for the changes to take effect. @@ -117,7 +117,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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Change the value of default expiration time. 1. Select **Save changes** for the changes to take effect. @@ -148,7 +148,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**. +1. On the top bar, select **Main 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. @@ -168,7 +168,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**. +1. On the top bar, select **Main 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**. @@ -185,7 +185,7 @@ For the value set for GitLab.com, see [Scheduled job archiving](../../gitlab_com To set all new [CI/CD variables](../../../ci/variables/index.md) as [protected](../../../ci/variables/index.md#protected-cicd-variables) by default: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Select **Protect CI/CD variables by default**. @@ -196,7 +196,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**. +1. On the top bar, select **Main 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. @@ -210,7 +210,7 @@ It is also possible to specify a [custom CI/CD configuration file for a specific You can configure some [CI/CD limits](../../../administration/instance_limits.md#cicd-limits) from the Admin Area: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. In the **CI/CD limits** section, you can set the following limits: @@ -232,7 +232,7 @@ walkthrough on how to add one. To enable or disable the banner: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Select or clear the **Enable pipeline suggestion banner** checkbox. 1. Select **Save changes**. @@ -267,7 +267,7 @@ in the pipeline editor. To select a CI/CD template for the required pipeline configuration: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. @@ -275,13 +275,25 @@ To select a CI/CD template for the required pipeline configuration: ## Package Registry configuration +### Maven Forwarding **(PREMIUM SELF)** + +GitLab administrators can disable the forwarding of Maven requests to [Maven Central](https://search.maven.org/). + +To disable forwarding Maven requests: + +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 Maven package requests to the Maven Registry if the packages are not found in the GitLab Package Registry**. +1. Select **Save changes**. + ### npm Forwarding **(PREMIUM SELF)** GitLab administrators can disable the forwarding of npm requests to [npmjs.com](https://www.npmjs.com/). To disable it: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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**. @@ -293,7 +305,7 @@ GitLab administrators can disable the forwarding of PyPI requests to [pypi.org]( To disable it: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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**. @@ -305,7 +317,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**. +1. On the top bar, select **Main 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. @@ -325,7 +337,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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Runner registration**. 1. Clear the checkbox if you don't want to display runner registration diff --git a/doc/user/admin_area/settings/deprecated_api_rate_limits.md b/doc/user/admin_area/settings/deprecated_api_rate_limits.md index d651e445a95..7298d55b051 100644 --- a/doc/user/admin_area/settings/deprecated_api_rate_limits.md +++ b/doc/user/admin_area/settings/deprecated_api_rate_limits.md @@ -34,7 +34,7 @@ Prerequisites: To override the general user and IP rate limits for requests to deprecated API endpoints: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Deprecated API Rate Limits**. 1. Select the check boxes for the types of rate limits you want to enable: diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index e4fc3b6e6d4..96fab153e85 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -11,7 +11,7 @@ You can customize some of the content in emails sent from your GitLab instance. ## Custom logo -The logo in the header of some emails can be customized, see the [logo customization section](../appearance.md#navigation-bar). +The logo in the header of some emails can be customized, see the [logo customization section](../appearance.md#top-bar). ## Include author name in email notification email body **(PREMIUM SELF)** @@ -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**. +1. On the top bar, select **Main 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**. +1. On the top bar, select **Main 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**. +1. On the top bar, select **Main 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,7 +66,7 @@ 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**. +1. On the top bar, select **Main 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. @@ -78,7 +78,7 @@ GitLab sends email notifications to users when their account has been deactivate To disable these notifications: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index d6e6deb0274..9db85eb6ea8 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -47,7 +47,7 @@ Alternatively, learn where to install custom certificates by using The external authorization service can be enabled by an administrator: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **External authorization**. 1. Complete the fields. diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md index 544c81e0583..963bca096a4 100644 --- a/doc/user/admin_area/settings/files_api_rate_limits.md +++ b/doc/user/admin_area/settings/files_api_rate_limits.md @@ -30,7 +30,7 @@ Prerequisite: To override the general user and IP rate limits for requests to the Repository files API: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Files API Rate Limits**. 1. Select the check boxes for the types of rate limits you want to enable: diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index dccab461b85..b7d3d8bfa20 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -22,10 +22,10 @@ Permissions-Policy: interest-cohort=() To enable it: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. -1. Expand **Federated Learning of Cohorts**. -1. Check the box. +1. Expand **Federated Learning of Cohorts (FLoC)**. +1. Select the **Participate in FLoC** checkbox. 1. Select **Save changes**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md index c10300baeef..519bbbef4e4 100644 --- a/doc/user/admin_area/settings/git_lfs_rate_limits.md +++ b/doc/user/admin_area/settings/git_lfs_rate_limits.md @@ -21,7 +21,7 @@ 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 top bar, select **Main 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**. diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index 8866a044241..dcf7574136a 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -11,7 +11,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**. +1. On the top bar, select **Main 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 0bf5dc1d37a..38161d0607c 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**. +1. On the top bar, select **Main 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`. @@ -31,10 +31,9 @@ is restricted, `/help` is visible only to signed-in users. ## Add a help message to the sign-in page -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: +You can add a help message, which is shown on the GitLab sign-in page. The message appears on the sign-in page: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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 +46,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**. +1. On the top bar, select **Main 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 +59,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**. +1. On the top bar, select **Main 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. @@ -81,7 +80,7 @@ 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**. +1. On the top bar, select **Main 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. 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 7d5a928eedf..cfe4f49388e 100644 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ b/doc/user/admin_area/settings/import_export_rate_limits.md @@ -13,7 +13,7 @@ You can configure the rate limits for imports and exports of projects and groups To change a rate limit: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. diff --git a/doc/user/admin_area/settings/incident_management_rate_limits.md b/doc/user/admin_area/settings/incident_management_rate_limits.md index ed2d707af0a..f9e91d26db5 100644 --- a/doc/user/admin_area/settings/incident_management_rate_limits.md +++ b/doc/user/admin_area/settings/incident_management_rate_limits.md @@ -30,7 +30,7 @@ Requests that exceed the limit are logged into `auth.log`. To set inbound incident management alert limits: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Incident Management Limits**. 1. Select the **Enable Incident Management inbound alert limit** checkbox. diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 2e27b213f16..7a63f2059ba 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -19,7 +19,7 @@ read [GitLab.com settings](../../gitlab_com/index.md). To access the **Admin Area**: 1. Sign in to your GitLab instance as an administrator. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings**, and the group of settings to view: - [General](#general) - [Geo](#geo) @@ -197,6 +197,6 @@ The **Templates** settings contain: 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**. +1. On the top bar, select **Main 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 51695ef7fd2..0d63fe5db7f 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -20,7 +20,7 @@ while the project remains secure. To select a project to serve as the custom template repository: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Templates**. 1. Expand **Templates** 1. From the dropdown list, select the project to use as the template repository. 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 1aeb011d880..62cddd2781c 100644 --- a/doc/user/admin_area/settings/package_registry_rate_limits.md +++ b/doc/user/admin_area/settings/package_registry_rate_limits.md @@ -30,7 +30,7 @@ no difference in functionality compared to the general user and IP rate limits. To enable the unauthenticated request rate limit: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**, and expand **Package registry rate limits**. 1. Select **Enable unauthenticated request rate limit**. @@ -43,7 +43,7 @@ To enable the unauthenticated request rate limit: To enable the authenticated API request rate limit: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**, and expand **Package registry rate limits**. 1. Select **Enable authenticated API request rate limit**. diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 010ba6a12fc..58afc6a104c 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -22,7 +22,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Enter configuration details and select **Save changes**. @@ -54,7 +54,7 @@ integration on all non-configured groups and projects by default. ### Remove an instance-level default setting -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Select **Reset** and confirm. @@ -68,7 +68,7 @@ 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**. +1. On the top bar, select **Main 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 760ce96d987..cd982bb4aa3 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -26,7 +26,7 @@ the activity feed. To modify this setting: - In the Admin Area: - 1. On the top bar, select **Menu > Admin**. + 1. On the top bar, select **Main 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 6c0c15243da..8d08da8246a 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Issues Rate Limits**. 1. Under **Max requests per minute**, 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 0a07cf095ee..f55c2f3bd4a 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 @@ -13,7 +13,7 @@ You can configure the per-user rate limit for requests to the note creation endp To change the note creation rate limit: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Notes rate limit**. 1. In the **Maximum requests per minute** box, enter the new value. diff --git a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md index fce6179f5cf..ba383d74701 100644 --- a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can set a limit so that users and processes can't request more than a certain number of pipelines each minute. This limit can help save resources and improve stability. -For example, if you set a limit of `10`, and `11` requests are sent to the [trigger API](../../../ci/triggers/) within one minute, +For example, if you set a limit of `10`, and `11` requests are sent to the [trigger API](../../../ci/triggers/index.md) within one minute, the eleventh request is blocked. Access to the endpoint is allowed again after one minute. This limit is: @@ -26,7 +26,7 @@ Requests that exceed the limit are logged in the `application_json.log` file. To limit the number of pipeline requests: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Pipelines Rate Limits**. 1. Under **Max requests per minute**, enter a value greater than `0`. diff --git a/doc/user/admin_area/settings/rate_limit_on_users_api.md b/doc/user/admin_area/settings/rate_limit_on_users_api.md index 5eed989f73f..9792fd1000d 100644 --- a/doc/user/admin_area/settings/rate_limit_on_users_api.md +++ b/doc/user/admin_area/settings/rate_limit_on_users_api.md @@ -13,7 +13,7 @@ You can configure the per user rate limit for requests to [Users API](../../../a To change the rate limit: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Users API rate limit**. 1. In the **Maximum requests per 10 minutes** text box, enter the new value. 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 028d5e4c2f3..cb3ca0fe756 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,7 +11,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Performance optimization**. diff --git a/doc/user/admin_area/settings/sidekiq_job_limits.md b/doc/user/admin_area/settings/sidekiq_job_limits.md index 750665285b4..c1990572aee 100644 --- a/doc/user/admin_area/settings/sidekiq_job_limits.md +++ b/doc/user/admin_area/settings/sidekiq_job_limits.md @@ -17,7 +17,7 @@ Redis. To avoid excessive memory for Redis, we: To access Sidekiq job size limits: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Main menu > 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 diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 7316b1bdbb8..bdffe87b75c 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -12,7 +12,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Sign-in restrictions** section. @@ -26,7 +26,7 @@ You can restrict the password authentication for web interface and Git over HTTP - **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) or LDAP password must be used to authenticate. -In the event of an external authentication provider outage, use the [GitLab Rails console](../../../administration/operations/rails_console.md) to [re-enable the standard web sign-in form](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#re-enable-standard-web-sign-in-form). This configuration can also be changed over the [Application settings REST API](../../../api/settings.md#change-application-settings) while authenticating with an administrator account's personal access token. +In the event of an external authentication provider outage, use the [GitLab Rails console](../../../administration/operations/rails_console.md) to [re-enable the standard web sign-in form](#re-enable-standard-web-sign-in-form-in-rails-console). This configuration can also be changed over the [Application settings REST API](../../../api/settings.md#change-application-settings) while authenticating with an administrator account's personal access token. ## Admin Mode @@ -121,21 +121,21 @@ 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. On the top bar, select **Main menu > Admin**. 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 GitLab instance. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Re-enable standard web sign-in form in rails console -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +Re-enable the standard username and password-based sign-in form if it was disabled as a [Sign-in restriction](#password-authentication-enabled). + +You can use this method through the [rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) when a configured external authentication provider (through SSO or an LDAP configuration) is facing an outage and direct sign-in access to GitLab is required. + +```ruby +Gitlab::CurrentSettings.update!(password_authentication_enabled_for_web: true) +``` diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 56abb3d4701..a0ec964e8db 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -22,7 +22,7 @@ you do not expect public users to sign up for an account. To disable sign ups: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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**. @@ -38,7 +38,7 @@ 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**. +1. On the top bar, select **Main 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**. @@ -58,7 +58,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Select the **Send confirmation email on sign-up** checkbox, then select **Save changes**. @@ -76,7 +76,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Enter a number in **User cap**. @@ -86,7 +86,7 @@ New user sign ups are subject to the user cap restriction. ## Remove the user cap -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Remove the number from **User cap**. @@ -130,7 +130,7 @@ You can add additional complexity requirements. Changes to password complexity r Existing passwords are unaffected. To change password complexity requirements: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Under **Minimum password length (number of characters)**, select additional password complexity requirements. You can require numbers, uppercase letters, lowercase letters, @@ -159,7 +159,7 @@ 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**. +1. On the top bar, select **Main 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 870fa7ad18e..d26ace161bb 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -17,7 +17,7 @@ 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**. +1. On the top bar, select **Main 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. diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 04ec9ed652f..59c100dc016 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -18,7 +18,7 @@ questions when creating a group. To toggle the display of customer experience improvement content and third-party offers: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings**, and expand **Customer experience improvement & third-party offers**. 1. Select **Do not display content for customer experience improvement and 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 afb937494e0..ad018abf809 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -56,7 +56,7 @@ Registration is not yet required for participation, but may be added in a future ### Enable registration features 1. Sign in as a user with administrator access. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. 1. If not enabled, select the **Enable Service Ping** checkbox. @@ -113,7 +113,7 @@ 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**. +1. On the top bar, select **Main 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. @@ -165,7 +165,7 @@ the Admin Area: You can view the exact JSON payload sent to GitLab Inc. in the Admin Area. To view the payload: 1. Sign in as a user with administrator access. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. 1. Select **Preview payload**. @@ -183,7 +183,7 @@ or if the Service Ping [cron job](../../../development/service_ping/index.md#how To upload the payload manually: 1. Sign in as a user with administrator access. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Service** usage data. 1. Select **Download payload**. 1. Save the JSON file. 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 a35cbe5381a..86676e4a63e 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 @@ -31,7 +31,7 @@ counted as web traffic. To enable the unauthenticated request rate limit: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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**. @@ -44,7 +44,7 @@ To enable the unauthenticated request rate limit: To enable the unauthenticated request rate limit: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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**. @@ -57,7 +57,7 @@ To enable the unauthenticated request rate limit: To enable the authenticated API request rate limit: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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**. @@ -70,7 +70,7 @@ To enable the authenticated API request rate limit: To enable the unauthenticated request rate limit: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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**. @@ -88,7 +88,7 @@ plain-text body, which by default is `Retry later`. To use a custom response: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. 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 118d375da01..87c24f04a1c 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -13,7 +13,7 @@ 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 access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -24,7 +24,7 @@ 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 access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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: @@ -40,7 +40,7 @@ on the instance. To alter which roles have permission to create projects: By default both administrators and anyone with the **Owner** role can delete a project. To restrict project deletion to only administrators: 1. Sign in to GitLab as a user with administrator access. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to: @@ -78,7 +78,7 @@ deleted groups will remain restorable within a retention period. To configure delayed project deletion: 1. Sign in to GitLab as a user with administrator access. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to: @@ -112,7 +112,7 @@ Alternatively, projects that are marked for removal can be deleted immediately. To set the default [visibility levels for new projects](../../public_access.md): 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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: @@ -127,7 +127,7 @@ To set the default [visibility levels for new projects](../../public_access.md): To set the default visibility levels for new [snippets](../../snippets.md): 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. @@ -141,7 +141,7 @@ 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 access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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: @@ -158,7 +158,7 @@ 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 access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. @@ -177,7 +177,7 @@ 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 access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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. @@ -189,7 +189,7 @@ To enable the export of [projects and their data](../../project/settings/import_export.md#export-a-project-and-its-data): 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select **Project export enabled**. @@ -205,7 +205,7 @@ 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 access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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: @@ -277,13 +277,8 @@ work in every repository. They can only be re-enabled by an administrator user o ## Configure globally-allowed IP address ranges -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87579) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `group_ip_restrictions_allow_global`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available -per group, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) -named `group_ip_restrictions_allow_global`. -On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87579) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `group_ip_restrictions_allow_global`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) in GitLab 15.4. [Feature flag `group_ip_restrictions_allow_global`](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) removed. This setting allows you to set IP address ranges to be combined with group-level IP allowlists. It helps administrators prevent aspects of the GitLab installation from being blocked @@ -296,7 +291,7 @@ daemon to be unable to fetch artifacts from the pipeline runs. To add a IP address range to the group-level allowlist: 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In **Globally-allowed IP ranges**, provide a value. diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index 28376923810..816e629f496 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -10,7 +10,7 @@ You can analyze your users' GitLab activities over time. To view user cohorts: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the **Cohorts** tab. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index f4075c3420b..b92d68222f5 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -32,7 +32,7 @@ View pipeline duration history: To view CI/CD analytics: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > CI/CD Analytics**. ## View deployment frequency chart **(ULTIMATE)** @@ -50,7 +50,7 @@ The deployment frequency chart is available for groups and projects. To view the deployment frequency chart: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > CI/CD Analytics**. 1. Select the **Deployment frequency** tab. @@ -68,11 +68,11 @@ merge requests to be deployed to a production environment. This chart is availab - For time periods in which no merge requests were deployed, the charts render a red, dashed line. - lead time for changes is one of the four [DORA metrics](index.md#devops-research-and-assessment-dora-key-metrics) that DevOps teams use for measuring excellence in software delivery. + Lead time for changes is one of the four [DORA metrics](index.md#devops-research-and-assessment-dora-key-metrics) that DevOps teams use for measuring excellence in software delivery. To view the lead time for changes chart: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > CI/CD Analytics**. 1. Select the **Lead time** tab. @@ -88,7 +88,7 @@ Time to restore service is one of the four [DORA metrics](index.md#devops-resear To view the time to restore service chart: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > CI/CD Analytics**. 1. Select the **Time to restore service** tab. @@ -104,6 +104,6 @@ Change failure rate is one of the four [DORA metrics](index.md#devops-research-a To view the change failure rate chart: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > CI/CD Analytics**. 1. Select the **Change failure rate** tab. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index dc02512702a..dd985b6b090 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -6,53 +6,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- -# Code Review Analytics **(PREMIUM)** +# Code review analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38062) in GitLab 12.7. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. -Use Code Review Analytics to view the longest-running reviews among open merge -requests, and: +Use code review analytics to view review metrics per merge request and +make improvements to your code review process: -- Take action on individual merge requests. -- Reduce overall cycle time. +- A high number of comments or commits may indicate: + - The code is too complex. + - Authors who require more training. +- A long review time may indicate: + - Types of work that move slower than other types. + - Opportunities to accelerate your development cycle. +- Fewer comments and approvers may indicate staffing requirements. -Code Review Analytics is available to users with at least the Reporter role, and displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. +Code review analytics displays a table of open merge requests that have at least one non-author comment. +The review time is measured from when the first non-author comment was submitted. -NOTE: -Initially, no data appears. Data is populated as users comment on open merge requests. +## View code review analytics - +Prerequisite: -The table is sorted by: +- You must have at least the Reporter role. -- **Review time**: Helping you to quickly find the longest-running reviews which may need intervention - or to be broken down into smaller parts. -- Other columns: Display the author, approvers, comment count, and line change (-/+) counts. +To view code review analytics: -## View Code Review Analytics - -To view Code Review Analytics: - -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Code Review**. 1. Filter merge requests by milestone and label. - -## Use cases - -This feature is designed for [development team leaders](https://about.gitlab.com/handbook/product/personas/#delaney-development-team-lead) -and others who want to understand broad code review dynamics, and identify patterns to explain them. - -You can use Code Review Analytics to: - -- Expose your team's unique challenges with code review. -- Identify improvements that might substantially accelerate your development cycle. -- Your team agrees that code review is moving too slow. -- The [Value Stream Analytics feature](value_stream_analytics.md) shows that reviews are your team's most time-consuming step. -- Analyze the patterns and trends of different types of work that are moving slow. - -For example: - -- Lots of comments or commits? Maybe the code is too complex. -- A particular author is involved? Maybe more training is required. -- Few comments and approvers? Maybe your team is understaffed. diff --git a/doc/user/analytics/img/code_review_analytics_v13_11.png b/doc/user/analytics/img/code_review_analytics_v13_11.png Binary files differdeleted file mode 100644 index b559b934a89..00000000000 --- a/doc/user/analytics/img/code_review_analytics_v13_11.png +++ /dev/null diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 62fff443073..86ae45a02b8 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -15,7 +15,7 @@ prior. To access the chart: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main 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 038b2f0c97e..4f40575a4ef 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -28,7 +28,7 @@ You must have at least the Reporter role to view merge request analytics. To view merge request analytics: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Merge request**. ## View the number of merge requests in a date range @@ -38,7 +38,7 @@ To view merge request analytics: To view the number of merge requests merged during a specific date range: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Merge request**. 1. Optional. Filter results: 1. Select the filter bar. @@ -63,6 +63,6 @@ created and when it's merged. Closed and un-merged merge requests are not includ To view **Mean time to merge**: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Merge request**. The **Mean time to merge** number is shown on the dashboard. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index f8b28ead155..f0841dc979b 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -26,7 +26,7 @@ Prerequisite: - You must have at least the Reporter role for the group. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Productivity**. 1. Optional. Filter results: 1. Select a project from the dropdown list. @@ -44,7 +44,7 @@ Use the following charts in productivity analytics to view the velocity of your merge requests to merge after they were created. - **Trendline**: number of merge requests that were merged in a specific time period. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Productivity**. To filter time metrics: @@ -56,7 +56,7 @@ To filter time metrics: To view commit statistics for your group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Productivity**. 1. Under the **Trendline** scatterplot, view the commit statistics: - The left histogram shows the number of hours between commits, comments, and merges. diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 5fd4a567b58..7723da7397d 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -30,7 +30,7 @@ Commits in a project's [wiki](../project/wiki/index.md#track-wiki-events) are no To review repository analytics for a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Repository**. ## How repository analytics chart data is updated diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index a71136628cf..d5756c5f822 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -32,7 +32,7 @@ Value stream analytics is also available for [groups](../group/value_stream_anal To view value stream analytics for your project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Value stream**. 1. To view metrics for a particular stage, select a stage below the **Filter results** text box. 1. Optional. Filter the results: @@ -61,7 +61,7 @@ Value stream analytics shows the median time spent by issues or merge requests i To view the median time spent in each stage: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Value stream**. 1. Optional. Filter the results: 1. Select the **Filter results** text box. @@ -81,7 +81,7 @@ Value stream analytics shows the lead time and cycle time for issues in your pro To view the lead time and cycle time for issues: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Value stream**. 1. Optional. Filter the results: 1. Select the **Filter results** text box. @@ -101,7 +101,7 @@ Lead time for changes is the median duration between when a merge request is mer To view the lead time for changes for merge requests in your project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Value stream**. 1. Optional. Filter the results: 1. Select the **Filter results** text box. @@ -113,19 +113,26 @@ To view the lead time for changes for merge requests in your project: The **Lead Time for Changes** metrics display below the **Filter results** text box. -## View number of successful deployments **(PREMIUM)** +## View number of successful deployments **(FREE)** -To view deployment metrics, you must have a +Prerequisites: + +- To view deployment metrics, you must have a [production environment configured](../../ci/environments/index.md#deployment-tier-of-environments). -Value stream analytics shows the following deployment metrics for your project: +Value stream analytics shows the following deployment metrics for your project within the specified date range: - Deploys: The number of successful deployments in the date range. - Deployment Frequency: The average number of successful deployments per day in the date range. +If you have a GitLab Premium or Ultimate subscription: + +- The number of successful deployments is calculated with DORA data. +- The data is filtered based on environment and environment tier. + To view deployment metrics for your project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Value stream**. 1. Optional. Filter the results: 1. Select the **Filter results** text box. diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 80e4700c34c..8e371ed4dc6 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -39,6 +39,7 @@ or other scanners) during a scan could cause inaccurate results. You can run a Web API fuzzing scan using the following methods: - [OpenAPI Specification](#openapi-specification) - version 2, and 3. +- [GraphQL Schema](#graphql-schema) - [HTTP Archive](#http-archive-har) (HAR) - [Postman Collection](#postman-collection) - version 2.0 or 2.1 @@ -76,6 +77,7 @@ To enable Web API fuzzing: - For manual configuration instructions, see the respective section, depending on the API type: - [OpenAPI Specification](#openapi-specification) + - [GraphQL Schema](#graphql-schema) - [HTTP Archive (HAR)](#http-archive-har) - [Postman Collection](#postman-collection) - Otherwise, see [Web API fuzzing configuration form](#web-api-fuzzing-configuration-form). @@ -95,7 +97,7 @@ a YAML snippet that you can paste in your GitLab CI/CD configuration. To generate an API Fuzzing configuration snippet: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **API Fuzzing** row, select **Enable API Fuzzing**. 1. Complete the fields. For details see [Available CI/CD variables](#available-cicd-variables). @@ -262,7 +264,7 @@ Example `.gitlab-ci.yml` file using a HAR file: FUZZAPI_TARGET_URL: http://test-deployment/ ``` -This is a minimal configuration for API fuzzing. From here you can: +This example is a minimal configuration for API fuzzing. From here you can: - [Run your first scan](#running-your-first-scan). - [Add authentication](#authentication). @@ -270,6 +272,118 @@ This is a minimal configuration for API fuzzing. From here you can: For details of API fuzzing configuration options, see [Available CI/CD variables](#available-cicd-variables). +### GraphQL Schema + +> Support for GraphQL Schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. + +GraphQL is a query language for your API and an alternative to REST APIs. +API Fuzzing supports testing GraphQL endpoints multiple ways: + +- Test using the GraphQL Schema. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. +- Test using a recording (HAR) of GraphQL queries. +- Test using a Postman Collection containing GraphQL queries. + +This section documents how to test using a GraphQL schema. The GraphQL schema support in +API Fuzzing is able to query the schema from endpoints that support introspection. +Introspection is enabled by default to allow tools like GraphiQL to work. + +#### API Fuzzing scanning with a GraphQL endpoint URL + +The GraphQL support in API Fuzzing is able to query a GraphQL endpoint for the schema. + +NOTE: +The GraphQL endpoint must support introspection queries for this method to work correctly. + +To configure API Fuzzing to use an GraphQL endpoint URL that provides information about the target API to test: + +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) in your `.gitlab-ci.yml` file. + +1. Provide the GraphQL endpoint path, for example `/api/graphql`. Specify the path by adding the `FUZZAPI_GRAPHQL` variable. + +1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. See the [dynamic environment solutions](#dynamic-environment-solutions) section of our documentation for more information. + +Complete example configuration of using a GraphQL endpoint URL: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +apifuzzer_fuzz: + variables: + FUZZAPI_GRAPHQL: /api/graphql + FUZZAPI_TARGET_URL: http://test-deployment/ +``` + +This example is a minimal configuration for API Fuzzing. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + +#### API Fuzzing with a GraphQL Schema file + +To configure API Fuzzing to use a GraphQl schema file that provides information about the target API to test: + +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) in your `.gitlab-ci.yml` file. + +1. Provide the GraphQL endpoint path, for example `/api/graphql`. Specify the path by adding the `FUZZAPI_GRAPHQL` variable. + +1. Provide the location of the GraphQL schema file. You can provide the location as a file path + or URL. Specify the location by adding the `FUZZAPI_GRAPHQL_SCHEMA` variable. + +1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. See the [dynamic environment solutions](#dynamic-environment-solutions) section of our documentation for more information. + +Complete example configuration of using an GraphQL schema file: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +apifuzzer_fuzz: + variables: + FUZZAPI_GRAPHQL: /api/graphql + FUZZAPI_GRAPHQL_SCHEMA: test-api-graphql.schema + FUZZAPI_TARGET_URL: http://test-deployment/ +``` + +Complete example configuration of using an GraphQL schema file URL: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +apifuzzer_fuzz: + variables: + FUZZAPI_GRAPHQL: /api/graphql + FUZZAPI_GRAPHQL_SCHEMA: http://file-store/files/test-api-graphql.schema + FUZZAPI_TARGET_URL: http://test-deployment/ +``` + +This example is a minimal configuration for API Fuzzing. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + ### Postman Collection The [Postman API Client](https://www.postman.com/product/api-client/) is a popular tool that @@ -344,34 +458,264 @@ For details of API fuzzing configuration options, see [Available CI/CD variables #### Postman variables +> - Support for Postman Environment file format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. +> - Support for multiple variable files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. +> - Support for Postman variable scopes: Global and Environment was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. + +##### Variables in Postman Client + Postman allows the developer to define placeholders that can be used in different parts of the -requests. These placeholders are called variables, as explained in the Postman documentation, -[Using variables](https://learning.postman.com/docs/sending-requests/variables/). +requests. These placeholders are called variables, as explained in [using variables](https://learning.postman.com/docs/sending-requests/variables/). You can use variables to store and reuse values in your requests and scripts. For example, you can edit the collection to add variables to the document:  +Or alternatively, you can add variables in an environment: + + + You can then use the variables in sections such as URL, headers, and others:  -Variables can be defined at different [scopes](https://learning.postman.com/docs/sending-requests/variables/#variable-scopes) -(for example, Global, Collection, Environment, Local, and Data). In this example, they're defined at -the Environment scope: +Postman has grown from a basic client tool with a nice UX experience to a more complex ecosystem that allows testing APIs with scripts, creating complex collections that trigger secondary requests, and setting variables along the way. Not every feature in the Postman ecosystem is supported. For example, scripts are not supported. The main focus of the Postman support is to ingest Postman Collection definitions that are used by the Postman Client and their related variables defined in the workspace, environments, and the collections themselves. - +Postman allows creating variables in different scopes. Each scope has a different level of visibility in the Postman tools. For example, you can create a variable in a _global environment_ scope that is seen by every operation definition and workspace. You can also create a variable in a specific _environment_ scope that is only visible and used when that specific environment is selected for use. Some scopes are not always available, for example in the Postman ecosystem you can create requests in the Postman Client, these requests do not have a _local_ scope, but test scripts do. -When you export a Postman collection, only Postman collection variables are exported into the -Postman file. For example, Postman does not export environment-scoped variables into the Postman -file. +Variable scopes in Postman can be a daunting topic and not everyone is familiar with it. We strongly recommend that you read [Variable Scopes](https://learning.postman.com/docs/sending-requests/variables/#variable-scopes) from Postman documentation before moving forward. -By default, the API fuzzer uses the Postman file to resolve Postman variable values. If a JSON file -is set in a GitLab CI/CD variable `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`, then the JSON -file takes precedence to get Postman variable values. +As mentioned above, there are different variable scopes, and each of them has a purpose and can be used to provide more flexibility to your Postman document. There is an important note on how values for variables are computed, as per Postman documentation: -WARNING: -Although Postman can export environment variables into a JSON file, the format is not compatible with the JSON expected by `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. +> If a variable with the same name is declared in two different scopes, the value stored in the variable with narrowest scope is used. For example, if there is a global variable named `username` and a local variable named `username`, the local value is used when the request runs. + +The following is a summary of the variable scopes supported by the Postman Client and API Fuzzing: + +- **Global Environment (Global) scope** is a special pre-defined environment that is available throughout a workspace. We can also refer to the _global environment_ scope as the _global_ scope. The Postman Client allows exporting the global environment into a JSON file, which can be used with API Fuzzing. +- **Environment scope** is a named group of variables created by a user in the Postman Client. +The Postman Client supports a single active environment along with the global environment. The variables defined in an active user-created environment take precedence over variables defined in the global environment. The Postman Client allows exporting your environment into a JSON file, which can be used with API Fuzzing. +- **Collection scope** is a group of variables declared in a given collection. The collection variables are available to the collection where they have been declared and the nested requests or collections. Variables defined in the collection scope take precedence over the _global environment_ scope and also the _environment_ scope. +The Postman Client can export one or more collections into a JSON file, this JSON file contains selected collections, requests, and collection variables. +- **API Fuzzing Scope** is a new scope added by API Fuzzing to allow users to provide extra variables, or override variables defined in other supported scopes. This scope is not supported by Postman. The _API Fuzzing Scope_ variables are provided using a [custom JSON file format](#api-fuzzing-scope-custom-json-file-format). + - Override values defined in the environment or collection + - Defining variables from scripts + - Define a single row of data from the unsupported _data scope_ +- **Data scope** is a group of variables in which their name and values come from JSON or CSV files. A Postman collection runner like [Newman](https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/) or [Postman Collection Runner](https://learning.postman.com/docs/running-collections/intro-to-collection-runs/) executes the requests in a collection as many times as entries have the JSON or CSV file. A good use case for these variables is to automate tests using scripts in Postman. +API Fuzzing does **not** support reading data from a CSV or JSON file. +- **Local scope** are variables that are defined in Postman scripts. API Fuzzing does **not** support Postman scripts and by extension, variables defined in scripts. You can still provide values for the script-defined variables by defining them in one of the supported scopes, or our custom JSON format. + +Not all scopes are supported by API Fuzzing and variables defined in scripts are not supported. The following table is sorted by broadest scope to narrowest scope. + +| Scope |Postman | API Fuzzing | Comment | +| ------------------ |:---------:|:------------:| :--------| +| Global Environment | Yes | Yes | Special pre-defined environment | +| Environment | Yes | Yes | Named environments | +| Collection | Yes | Yes | Defined in your postman collection | +| API Fuzzing Scope | No | Yes | Custom scope added by API Fuzzing | +| Data | Yes | No | External files in CSV or JSON format | +| Local | Yes | No | Variables defined in scripts | + +For more details on how to define variables and export variables in different scopes, see: + +- [Defining collection variables](https://learning.postman.com/docs/sending-requests/variables/#defining-collection-variables) +- [Defining environment variables](https://learning.postman.com/docs/sending-requests/variables/#defining-environment-variables) +- [Defining global variables](https://learning.postman.com/docs/sending-requests/variables/#defining-global-variables) + +##### Exporting from Postman Client + +The Postman Client lets you export different file formats, for instance, you can export a Postman collection or a Postman environment. +The exported environment can be the global environment (which is always available) or can be any custom environment you previously have created. When you export a Postman Collection, it may contain only declarations for _collection_ and _local_ scoped variables; _environment_ scoped variables are not included. + +To get the declaration for _environment_ scoped variables, you have to export a given environment at the time. Each exported file only includes variables from the selected environment. + +For more details on exporting variables in different supported scopes, see: + +- [Exporting collections](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-collections) +- [Exporting environments](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) +- [Downloading global environments](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) + +##### API Fuzzing Scope, custom JSON file format + +Our custom JSON file format is a JSON object where each object property represents a variable name and the property value represents the variable value. This file can be created using your favorite text editor, or it can be produced by an earlier job in your pipeline. + +This example defines two variables `base_url` and `token` in the API Fuzzing scope: + +```json +{ + "base_url": "http://127.0.0.1/", + "token": "Token 84816165151" +} +``` + +##### Using scopes with API Fuzzing + +The scopes: _global_, _environment_, _collection_, and _GitLab API Fuzzing_ are supported in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/356312). GitLab 15.0 and earlier, supports only the _collection_, and _GitLab API Fuzzing_ scopes. + +The following table provides a quick reference for mapping scope files/URLs to API Fuzzing configuration variables: + +| Scope | How to Provide | +| ------------------ | --------------- | +| Global Environment | FUZZAPI_POSTMAN_COLLECTION_VARIABLES | +| Environment | FUZZAPI_POSTMAN_COLLECTION_VARIABLES | +| Collection | FUZZAPI_POSTMAN_COLLECTION | +| API Fuzzing Scope | FUZZAPI_POSTMAN_COLLECTION_VARIABLES | +| Data | Not supported | +| Local | Not supported | + +The Postman Collection document automatically includes any _collection_ scoped variables. The Postman Collection is provided with the configuration variable `FUZZAPI_POSTMAN_COLLECTION`. This variable can be set to a single [exported Postman collection](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-collections). + +Variables from other scopes are provided through the `FUZZAPI_POSTMAN_COLLECTION_VARIABLES` configuration variable. The configuration variable supports a comma (`,`) delimited file list in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/356312). GitLab 15.0 and earlier, supports only one single file. The order of the files provided is not important as the files provide the needed scope information. + +The configuration variable `FUZZAPI_POSTMAN_COLLECTION_VARIABLES` can be set to: + +- [Exported Global environment](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) +- [Exported environments](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) +- [API Fuzzing Custom JSON format](#api-fuzzing-scope-custom-json-file-format) + +##### Undefined Postman variables + +There is a chance that API Fuzzing engine does not find all variables references that your Postman collection file is using. Some cases can be: + +- You are using _data_ or _local_ scoped variables, and as stated previously these scopes are not supported by API Fuzzing. Thus, assuming the values for these variables have not been provided through [the API Fuzzing scope](#api-fuzzing-scope-custom-json-file-format), then the values of the _data_ and _local_ scoped variables are undefined. +- A variable name was typed incorrectly, and the name does not match the defined variable. +- Postman Client supports a new dynamic variable that is not supported by API Fuzzing. + +When possible, API Fuzzing follows the same behavior as the Postman Client does when dealing with undefined variables. The text of the variable reference remains the same, and there is no text substitution. The same behavior also applies to any unsupported dynamic variables. + +For example, if a request definition in the Postman Collection references the variable `{{full_url}}` and the variable is not found it is left unchanged with the value `{{full_url}}`. + +##### Dynamic Postman variables + +In addition to variables that a user can define at various scope levels, Postman has a set of pre-defined variables called _dynamic_ variables. The [_dynamic_ variables](https://learning.postman.com/docs/writing-scripts/script-references/variables-list/) are already defined and their name is prefixed with a dollar sign (`$`), for instance, `$guid`. _Dynamic_ variables can be used like any other variable, and in the Postman Client, they produce random values during the request/collection run. + +An important difference between API Fuzzing and Postman is that API Fuzzing returns the same value for each usage of the same dynamic variables. This differs from the Postman Client behavior which returns a random value on each use of the same dynamic variable. In other words, API Fuzzing uses static values for dynamic variables while Postman uses random values. + +The supported dynamic variables during the scanning process are: + +| Variable | Value | +| ----------- | ----------- | +| `$guid` | `611c2e81-2ccb-42d8-9ddc-2d0bfa65c1b4` | +| `$isoTimestamp` | `2020-06-09T21:10:36.177Z` | +| `$randomAbbreviation` | `PCI` | +| `$randomAbstractImage` | `http://no-a-valid-host/640/480/abstract` | +| `$randomAdjective` | `auxiliary` | +| `$randomAlphaNumeric` | `a` | +| `$randomAnimalsImage` | `http://no-a-valid-host/640/480/animals` | +| `$randomAvatarImage` | `https://no-a-valid-host/path/to/some/image.jpg` | +| `$randomBankAccount` | `09454073` | +| `$randomBankAccountBic` | `EZIAUGJ1` | +| `$randomBankAccountIban` | `MU20ZPUN3039684000618086155TKZ` | +| `$randomBankAccountName` | `Home Loan Account` | +| `$randomBitcoin` | `3VB8JGT7Y4Z63U68KGGKDXMLLH5` | +| `$randomBoolean` | `true` | +| `$randomBs` | `killer leverage schemas` | +| `$randomBsAdjective` | `viral` | +| `$randomBsBuzz` | `repurpose` | +| `$randomBsNoun` | `markets` | +| `$randomBusinessImage` | `http://no-a-valid-host/640/480/business` | +| `$randomCatchPhrase` | `Future-proofed heuristic open architecture` | +| `$randomCatchPhraseAdjective` | `Business-focused` | +| `$randomCatchPhraseDescriptor` | `bandwidth-monitored` | +| `$randomCatchPhraseNoun` | `superstructure` | +| `$randomCatsImage` | `http://no-a-valid-host/640/480/cats` | +| `$randomCity` | `Spinkahaven` | +| `$randomCityImage` | `http://no-a-valid-host/640/480/city` | +| `$randomColor` | `fuchsia` | +| `$randomCommonFileExt` | `wav` | +| `$randomCommonFileName` | `well_modulated.mpg4` | +| `$randomCommonFileType` | `audio` | +| `$randomCompanyName` | `Grady LLC` | +| `$randomCompanySuffix` | `Inc` | +| `$randomCountry` | `Kazakhstan` | +| `$randomCountryCode` | `MD` | +| `$randomCreditCardMask` | `3622` | +| `$randomCurrencyCode` | `ZMK` | +| `$randomCurrencyName` | `Pound Sterling` | +| `$randomCurrencySymbol` | `£` | +| `$randomDatabaseCollation` | `utf8_general_ci` | +| `$randomDatabaseColumn` | `updatedAt` | +| `$randomDatabaseEngine` | `Memory` | +| `$randomDatabaseType` | `text` | +| `$randomDateFuture` | `Tue Mar 17 2020 13:11:50 GMT+0530 (India Standard Time)` | +| `$randomDatePast` | `Sat Mar 02 2019 09:09:26 GMT+0530 (India Standard Time)` | +| `$randomDateRecent` | `Tue Jul 09 2019 23:12:37 GMT+0530 (India Standard Time)` | +| `$randomDepartment` | `Electronics` | +| `$randomDirectoryPath` | `/usr/local/bin` | +| `$randomDomainName` | `trevor.info` | +| `$randomDomainSuffix` | `org` | +| `$randomDomainWord` | `jaden` | +| `$randomEmail` | `Iva.Kovacek61@no-a-valid-host.com` | +| `$randomExampleEmail` | `non-a-valid-user@example.net` | +| `$randomFashionImage` | `http://no-a-valid-host/640/480/fashion` | +| `$randomFileExt` | `war` | +| `$randomFileName` | `neural_sri_lanka_rupee_gloves.gdoc` | +| `$randomFilePath` | `/home/programming_chicken.cpio` | +| `$randomFileType` | `application` | +| `$randomFirstName` | `Chandler` | +| `$randomFoodImage` | `http://no-a-valid-host/640/480/food` | +| `$randomFullName` | `Connie Runolfsdottir` | +| `$randomHexColor` | `#47594a` | +| `$randomImageDataUri` | `data:image/svg+xml;charset=UTF-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20version%3D%221.1%22%20baseProfile%3D%22full%22%20width%3D%22undefined%22%20height%3D%22undefined%22%3E%20%3Crect%20width%3D%22100%25%22%20height%3D%22100%25%22%20fill%3D%22grey%22%2F%3E%20%20%3Ctext%20x%3D%220%22%20y%3D%2220%22%20font-size%3D%2220%22%20text-anchor%3D%22start%22%20fill%3D%22white%22%3Eundefinedxundefined%3C%2Ftext%3E%20%3C%2Fsvg%3E` | +| `$randomImageUrl` | `http://no-a-valid-host/640/480` | +| `$randomIngverb` | `navigating` | +| `$randomInt` | `494` | +| `$randomIP` | `241.102.234.100` | +| `$randomIPV6` | `dbe2:7ae6:119b:c161:1560:6dda:3a9b:90a9` | +| `$randomJobArea` | `Mobility` | +| `$randomJobDescriptor` | `Senior` | +| `$randomJobTitle` | `International Creative Liaison` | +| `$randomJobType` | `Supervisor` | +| `$randomLastName` | `Schneider` | +| `$randomLatitude` | `55.2099` | +| `$randomLocale` | `ny` | +| `$randomLongitude` | `40.6609` | +| `$randomLoremLines` | `Ducimus in ut mollitia.\nA itaque non.\nHarum temporibus nihil voluptas.\nIste in sed et nesciunt in quaerat sed.` | +| `$randomLoremParagraph` | `Ab aliquid odio iste quo voluptas voluptatem dignissimos velit. Recusandae facilis qui commodi ea magnam enim nostrum quia quis. Nihil est suscipit assumenda ut voluptatem sed. Esse ab voluptas odit qui molestiae. Rem est nesciunt est quis ipsam expedita consequuntur.` | +| `$randomLoremParagraphs` | `Voluptatem rem magnam aliquam ab id aut quaerat. Placeat provident possimus voluptatibus dicta velit non aut quasi. Mollitia et aliquam expedita sunt dolores nam consequuntur. Nam dolorum delectus ipsam repudiandae et ipsam ut voluptatum totam. Nobis labore labore recusandae ipsam quo.` | +| `$randomLoremSentence` | `Molestias consequuntur nisi non quod.` | +| `$randomLoremSentences` | `Et sint voluptas similique iure amet perspiciatis vero sequi atque. Ut porro sit et hic. Neque aspernatur vitae fugiat ut dolore et veritatis. Ab iusto ex delectus animi. Voluptates nisi iusto. Impedit quod quae voluptate qui.` | +| `$randomLoremSlug` | `eos-aperiam-accusamus, beatae-id-molestiae, qui-est-repellat` | +| `$randomLoremText` | `Quisquam asperiores exercitationem ut ipsum. Aut eius nesciunt. Et reiciendis aut alias eaque. Nihil amet laboriosam pariatur eligendi. Sunt ullam ut sint natus ducimus. Voluptas harum aspernatur soluta rem nam.` | +| `$randomLoremWord` | `est` | +| `$randomLoremWords` | `vel repellat nobis` | +| `$randomMACAddress` | `33:d4:68:5f:b4:c7` | +| `$randomMimeType` | `audio/vnd.vmx.cvsd` | +| `$randomMonth` | `February` | +| `$randomNamePrefix` | `Dr.` | +| `$randomNameSuffix` | `MD` | +| `$randomNatureImage` | `http://no-a-valid-host/640/480/nature` | +| `$randomNightlifeImage` | `http://no-a-valid-host/640/480/nightlife` | +| `$randomNoun` | `bus` | +| `$randomPassword` | `t9iXe7COoDKv8k3` | +| `$randomPeopleImage` | `http://no-a-valid-host/640/480/people` | +| `$randomPhoneNumber` | `700-008-5275` | +| `$randomPhoneNumberExt` | `27-199-983-3864` | +| `$randomPhrase` | `You can't program the monitor without navigating the mobile XML program!` | +| `$randomPrice` | `531.55` | +| `$randomProduct` | `Pizza` | +| `$randomProductAdjective` | `Unbranded` | +| `$randomProductMaterial` | `Steel` | +| `$randomProductName` | `Handmade Concrete Tuna` | +| `$randomProtocol` | `https` | +| `$randomSemver` | `7.0.5` | +| `$randomSportsImage` | `http://no-a-valid-host/640/480/sports` | +| `$randomStreetAddress` | `5742 Harvey Streets` | +| `$randomStreetName` | `Kuhic Island` | +| `$randomTransactionType` | `payment` | +| `$randomTransportImage` | `http://no-a-valid-host/640/480/transport` | +| `$randomUrl` | `https://no-a-valid-host.net` | +| `$randomUserAgent` | `Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.9.8; rv:15.6) Gecko/20100101 Firefox/15.6.6` | +| `$randomUserName` | `Jarrell.Gutkowski` | +| `$randomUUID` | `6929bb52-3ab2-448a-9796-d6480ecad36b` | +| `$randomVerb` | `navigate` | +| `$randomWeekday` | `Thursday` | +| `$randomWord` | `withdrawal` | +| `$randomWords` | `Samoa Synergistic sticky copying Grocery` | +| `$timestamp` | `1562757107` | + +##### Example: Global Scope + +In this example, [the _global_ scope is exported](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) from the Postman Client as `global-scope.json` and provided to API Fuzzing through the `FUZZAPI_POSTMAN_COLLECTION_VARIABLES` configuration variable. Here is an example of using `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`: @@ -384,21 +728,171 @@ include: variables: FUZZAPI_PROFILE: Quick-10 - FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + FUZZAPI_POSTMAN_COLLECTION: postman-collection.json + FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json + FUZZAPI_TARGET_URL: http://test-deployment/ +``` + +##### Example: Environment Scope + +In this example, [the _environment_ scope is exported](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) from the Postman Client as `environment-scope.json` and provided to API Fuzzing through the `FUZZAPI_POSTMAN_COLLECTION_VARIABLES` configuration variable. + +Here is an example of using `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_POSTMAN_COLLECTION: postman-collection.json + FUZZAPI_POSTMAN_COLLECTION_VARIABLES: environment-scope.json + FUZZAPI_TARGET_URL: http://test-deployment/ +``` + +##### Example: Collection Scope + +The _collection_ scope variables are included in the exported Postman Collection file and provided through the `FUZZAPI_POSTMAN_COLLECTION` configuration variable. + +Here is an example of using `FUZZAPI_POSTMAN_COLLECTION`: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_POSTMAN_COLLECTION: postman-collection.json FUZZAPI_TARGET_URL: http://test-deployment/ FUZZAPI_POSTMAN_COLLECTION_VARIABLES: variable-collection-dictionary.json ``` -The file `variable-collection-dictionary.json` is a JSON document. This JSON is an object with -key-value pairs for properties. The keys are the variables' names, and the values are the variables' +##### Example: API Fuzzing Scope + +The API Fuzzing Scope is used for two main purposes, defining _data_ and _local_ scope variables that are not supported by API Fuzzing, and changing the value of an existing variable defined in another scope. The API Fuzzing Scope is provided through the `FUZZAPI_POSTMAN_COLLECTION_VARIABLES` configuration variable. + +Here is an example of using `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_POSTMAN_COLLECTION: postman-collection.json + FUZZAPI_POSTMAN_COLLECTION_VARIABLES: api-fuzzing-scope.json + FUZZAPI_TARGET_URL: http://test-deployment/ +``` + +The file `api-fuzzing-scope.json` uses our [custom JSON file format](#api-fuzzing-scope-custom-json-file-format). This JSON is an object with key-value pairs for properties. The keys are the variables' names, and the values are the variables' values. For example: - ```json - { - "base_url": "http://127.0.0.1/", - "token": "Token 84816165151" - } - ``` +```json +{ + "base_url": "http://127.0.0.1/", + "token": "Token 84816165151" +} +``` + +##### Example: Multiple Scopes + +In this example, a _global_ scope, _environment_ scope, and _collection_ scope are configured. The first step is to export our various scopes. + +- [Export the _global_ scope](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) as `global-scope.json` +- [Export the _environment_ scope](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) as `environment-scope.json` +- Export the Postman Collection which includes the _collection_ scope as `postman-collection.json` + +The Postman Collection is provided using the `FUZZAPI_POSTMAN_COLLECTION` variable, while the other scopes are provided using the `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. API Fuzzing can identify which scope the provided files match using data provided in each file. + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_POSTMAN_COLLECTION: postman-collection.json + FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json + FUZZAPI_TARGET_URL: http://test-deployment/ +``` + +##### Example: Changing a Variables Value + +When using exported scopes, it's often the case that the value of a variable must be changed for use with API Fuzzing. For example, a _collection_ scoped variable might contain a variable named `api_version` with a value of `v2`, while your test needs a value of `v1`. Instead of modifying the exported collection to change the value, the API Fuzzing scope can be used to change its value. This works because the _API Fuzzing_ scope takes precedence over all other scopes. + +The _collection_ scope variables are included in the exported Postman Collection file and provided through the `FUZZAPI_POSTMAN_COLLECTION` configuration variable. + +The API Fuzzing Scope is provided through the `FUZZAPI_POSTMAN_COLLECTION_VARIABLES` configuration variable, but first, we must create the file. +The file `api-fuzzing-scope.json` uses our [custom JSON file format](#api-fuzzing-scope-custom-json-file-format). This JSON is an object with key-value pairs for properties. The keys are the variables' names, and the values are the variables' +values. For example: + +```json +{ + "api_version": "v1" +} +``` + +Our CI definition: + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_POSTMAN_COLLECTION: postman-collection.json + FUZZAPI_POSTMAN_COLLECTION_VARIABLES: api-fuzzing-scope.json + FUZZAPI_TARGET_URL: http://test-deployment/ +``` + +##### Example: Changing a Variables Value with Multiple Scopes + +When using exported scopes, it's often the case that the value of a variable must be changed for use with API Fuzzing. For example, an _environment_ scope might contain a variable named `api_version` with a value of `v2`, while your test needs a value of `v1`. Instead of modifying the exported file to change the value, the API Fuzzing scope can be used. This works because the _API Fuzzing_ scope takes precedence over all other scopes. + +In this example, a _global_ scope, _environment_ scope, _collection_ scope, and _API Fuzzing_ scope are configured. The first step is to export and create our various scopes. + +- [Export the _global_ scope](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) as `global-scope.json` +- [Export the _environment_ scope](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) as `environment-scope.json` +- Export the Postman Collection which includes the _collection_ scope as `postman-collection.json` + +The API Fuzzing scope is used by creating a file `api-fuzzing-scope.json` using our [custom JSON file format](#api-fuzzing-scope-custom-json-file-format). This JSON is an object with key-value pairs for properties. The keys are the variables' names, and the values are the variables' +values. For example: + +```json +{ + "api_version": "v1" +} +``` + +The Postman Collection is provided using the `FUZZAPI_POSTMAN_COLLECTION` variable, while the other scopes are provided using the `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. API Fuzzing can identify which scope the provided files match using data provided in each file. + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_POSTMAN_COLLECTION: postman-collection.json + FUZZAPI_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json,api-fuzzing-scope.json + FUZZAPI_TARGET_URL: http://test-deployment/ +``` ## API fuzzing configuration @@ -420,21 +914,23 @@ provide a script that performs an authentication flow or calculates the token. #### HTTP Basic Authentication [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) -is an authentication method built in to the HTTP protocol and used in conjunction with +is an authentication method built into the HTTP protocol and used in conjunction with [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). -To use HTTP basic authentication, two CI/CD variables are added to your `.gitlab-ci.yml` file: -- `FUZZAPI_HTTP_USERNAME`: The username for authentication. -- `FUZZAPI_HTTP_PASSWORD`: The password for authentication. +We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables) +for the password (for example, `TEST_API_PASSWORD`), and set it to be masked. You can create CI/CD +variables from the GitLab project's page at **Settings > CI/CD**, in the **Variables** section. +Because of the [limitations on masked variables](../../../ci/variables/index.md#mask-a-cicd-variable), +you should Base64-encode the password before adding it as a variable. -For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables) -(for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the -GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Use that variable -as the value for `FUZZAPI_HTTP_PASSWORD`: +Finally, add two CI/CD variables to your `.gitlab-ci.yml` file: + +- `FUZZAPI_HTTP_USERNAME`: The username for authentication. +- `FUZZAPI_HTTP_PASSWORD_BASE64`: The Base64-encoded password for authentication. ```yaml stages: - - fuzz + - fuzz include: - template: API-Fuzzing.gitlab-ci.yml @@ -444,9 +940,13 @@ variables: FUZZAPI_HAR: test-api-recording.har FUZZAPI_TARGET_URL: http://test-deployment/ FUZZAPI_HTTP_USERNAME: testuser - FUZZAPI_HTTP_PASSWORD: $TEST_API_PASSWORD + FUZZAPI_HTTP_PASSWORD_BASE64: $TEST_API_PASSWORD ``` +#### Raw password + +If you do not want to Base64-encode the password (or if you are using GitLab 15.3 or earlier) you can provide the raw password `FUZZAPI_HTTP_PASSWORD`, instead of using `FUZZAPI_HTTP_PASSWORD_BASE64`. + #### Bearer Tokens Bearer tokens are used by several different authentication mechanisms, including OAuth2 and JSON Web @@ -493,7 +993,7 @@ Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: ##### Token generated at test runtime If the bearer token must be generated and doesn't expire during testing, you can provide to API -fuzzing a file containing the token. A prior stage and job, or part of the API fuzzing job, can +fuzzing with a file containing the token. A prior stage and job, or part of the API fuzzing job, can generate this file. API fuzzing expects to receive a JSON file with the following structure: @@ -605,7 +1105,10 @@ profile increases as the number of tests increases. |[`FUZZAPI_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`FUZZAPI_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | +|[`FUZZAPI_GRAPHQL`](#graphql-schema) | Path to GraphQL endpoint, for example `/api/graphql`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. | +|[`FUZZAPI_GRAPHQL_SCHEMA`](#graphql-schema) | A URL or filename for a GraphQL schema in JSON format. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | +|[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. The support for comma-separated (`,`) files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. | |[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. | |[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | |[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | @@ -616,6 +1119,7 @@ profile increases as the number of tests increases. |[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | |[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | |[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | +|[`FUZZAPI_HTTP_PASSWORD_BASE64`](#http-basic-authentication) | Password for HTTP authentication, Base64-encoded. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing-src/-/merge_requests/702) in GitLab 15.4. | ### Overrides @@ -1062,21 +1566,21 @@ This example excludes the `/auth` resource. This does not exclude child resource ```yaml variables: - FUZZAPI_EXCLUDE_PATHS=/auth + FUZZAPI_EXCLUDE_PATHS: /auth ``` To exclude `/auth`, and child resources (`/auth/child`), we use a wildcard. ```yaml variables: - FUZZAPI_EXCLUDE_PATHS=/auth* + FUZZAPI_EXCLUDE_PATHS: /auth* ``` To exclude multiple paths we can use the `;` character. In this example we exclude `/auth*` and `/v1/*`. ```yaml variables: - FUZZAPI_EXCLUDE_PATHS=/auth*;/v1/* + FUZZAPI_EXCLUDE_PATHS: /auth*;/v1/* ``` ### Exclude parameters @@ -1336,7 +1840,15 @@ Each value in `FUZZAPI_EXCLUDE_URLS` is a regular expression. Characters such as The following example excludes the URL `http://target/api/auth` and its child resources. ```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + variables: + FUZZAPI_TARGET_URL: http://target/ + FUZZAPI_OPENAPI: test-api-specification.json FUZZAPI_EXCLUDE_URLS: http://target/api/auth ``` @@ -1345,7 +1857,15 @@ variables: To exclude the URLs `http://target/api/buy` and `http://target/api/sell` but allowing to scan their child resources, for instance: `http://target/api/buy/toy` or `http://target/api/sell/chair`. You could use the value `http://target/api/buy/$,http://target/api/sell/$`. This value is using two regular expressions, each of them separated by a `,` character. Hence, it contains `http://target/api/buy$` and `http://target/api/sell$`. In each regular expression, the trailing `$` character points out where the matching URL should end. ```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + variables: + FUZZAPI_TARGET_URL: http://target/ + FUZZAPI_OPENAPI: test-api-specification.json FUZZAPI_EXCLUDE_URLS: http://target/api/buy/$,http://target/api/sell/$ ``` @@ -1354,7 +1874,15 @@ variables: In order to exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: ```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + variables: + FUZZAPI_TARGET_URL: http://target/ + FUZZAPI_OPENAPI: test-api-specification.json FUZZAPI_EXCLUDE_URLS: http://target/api/buy,http://target/api/sell ``` @@ -1363,7 +1891,15 @@ variables: In order to exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. ```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + variables: + FUZZAPI_TARGET_URL: http://target/ + FUZZAPI_OPENAPI: test-api-specification.json FUZZAPI_EXCLUDE_URLS: https://target/api/v.*/user/create$ ``` @@ -1679,11 +2215,11 @@ For more information, see [Offline environments](../offline_deployments/index.md ### `Error waiting for API Security 'http://127.0.0.1:5000' to become available` -A bug exists in versions of the API Fuzzing analyzer prior to v1.6.196 that can cause a background process to fail under certain conditions. The solution is to update to a newer version of the DAST API analyzer. +A bug exists in versions of the API Fuzzing analyzer prior to v1.6.196 that can cause a background process to fail under certain conditions. The solution is to update to a newer version of the API Fuzzing analyzer. The version information can be found in the job details for the `apifuzzer_fuzz` job. -If the issue is occurring with versions v1.6.196 or greater, please contact Support and provide the following information: +If the issue is occurring with versions v1.6.196 or greater, contact Support and provide the following information: 1. Reference this troubleshooting section and ask for the issue to be escalated to the Dynamic Analysis Team. 1. The full console output of the job. @@ -1750,12 +2286,15 @@ This solution is for pipelines in which the target API URL doesn't change (is st For environments where the target API remains the same, we recommend you specify the target URL by using the `FUZZAPI_TARGET_URL` environment variable. In your `.gitlab-ci.yml` file, add a variable `FUZZAPI_TARGET_URL`. The variable must be set to the base URL of API testing target. For example: ```yaml +stages: + - fuzz + include: - - template: API-Fuzzing.gitlab-ci.yml + - template: API-Fuzzing.gitlab-ci.yml - variables: - FUZZAPI_TARGET_URL: http://test-deployment/ - FUZZAPI_OPENAPI: test-api-specification.json +variables: + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OPENAPI: test-api-specification.json ``` #### Dynamic environment solutions @@ -1793,7 +2332,7 @@ TODO ### Use OpenAPI with an invalid schema -There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. +There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Fuzzing is able to perform a relaxed validation by setting the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. #### Edit a non-compliant OpenAPI file @@ -1810,25 +2349,25 @@ If your OpenAPI document is generated manually, load your document in the editor Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema. -API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION` to any value, for example: +API Fuzzing can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Fuzzing analyzer to perform a relaxed validation, set the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION` to any value, for example: ```yaml - stages: - - fuzz +stages: + - fuzz - include: - - template: API-Fuzzing.gitlab-ci.yml +include: + - template: API-Fuzzing.gitlab-ci.yml - variables: - FUZZAPI_PROFILE: Quick-10 - FUZZAPI_TARGET_URL: http://test-deployment/ - FUZZAPI_OPENAPI: test-api-specification.json - FUZZAPI_OPENAPI_RELAXED_VALIDATION: On +variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_OPENAPI_RELAXED_VALIDATION: 'On' ``` ### `No operation in the OpenAPI document is consuming any supported media type` -API Security uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. +API Fuzzing uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. **Error message** diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 9ca1a6f125f..32a523a1871 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -29,7 +29,7 @@ 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 top bar, select **Main 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. @@ -56,7 +56,7 @@ You can configure the following security controls: - Can be configured by adding a configuration block to your agent configuration. For more details, read [Operational Container Scanning](../../clusters/agent/vulnerabilities.md#enable-operational-container-scanning). - [Secret Detection](../secret_detection/index.md) - Select **Configure with a merge request** to create a merge request with the changes required to - 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). + enable Secret Detection. For more details, read [Enable Secret Detection using a merge request](../secret_detection/index.md#enable-secret-detection-using-a-merge-request). - [API Fuzzing](../api_fuzzing/index.md) - 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](../coverage_fuzzing/index.md) diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 7bb3cb4f64c..961ccf6b563 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,7 +1,7 @@ --- type: reference, howto -stage: Protect -group: Container Security +stage: Secure +group: Composition Analysis 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 --- @@ -14,6 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Integration with Grype as an alternative scanner [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326279) in GitLab 14.0. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86092) the major analyzer version from `4` to `5` in GitLab 15.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86783) from GitLab Ultimate to GitLab Free in 15.0. +> - Container Scanning variables that reference Docker [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/357264) in GitLab 15.4. Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra Container Scanning job in your pipeline that scans for those @@ -68,7 +69,7 @@ information directly in the merge request. | [Solutions for vulnerabilities (auto-remediation)](#solutions-for-vulnerabilities-auto-remediation) | No | Yes | | Support for the [vulnerability allow list](#vulnerability-allowlisting) | No | Yes | | [Access to Security Dashboard page](#security-dashboard) | No | Yes | -| [Access to Dependency List page](../dependency_list/) | No | Yes | +| [Access to Dependency List page](../dependency_list/index.md) | No | Yes | ## Requirements @@ -83,7 +84,7 @@ To enable container scanning in your pipeline, you need the following: - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) the Docker image to your project's container registry. - If you're using a third-party container registry, you might need to provide authentication - credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). + credentials through the `CS_REGISTRY_USER` and `CS_REGISTRY_PASSWORD` [configuration variables](#available-cicd-variables). For more details on how to use these variables, see [authenticate to a remote registry](#authenticate-to-a-remote-registry). ## Configuration @@ -157,13 +158,13 @@ include: container_scanning: variables: - DOCKER_IMAGE: example.com/user/image:tag + CS_IMAGE: example.com/user/image:tag ``` ##### Authenticate to a remote registry -Scanning an image in a private registry requires authentication. Provide the username in the `DOCKER_USER` -variable, and the password in the `DOCKER_PASSWORD` configuration variable. +Scanning an image in a private registry requires authentication. Provide the username in the `CS_REGISTRY_USER` +variable, and the password in the `CS_REGISTRY_PASSWORD` configuration variable. For example, to scan an image from AWS Elastic Container Registry: @@ -178,9 +179,9 @@ container_scanning: include: - template: Security/Container-Scanning.gitlab-ci.yml - DOCKER_IMAGE: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<image>:<tag> - DOCKER_USER: AWS - DOCKER_PASSWORD: "$AWS_ECR_PASSWORD" + CS_IMAGE: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<image>:<tag> + CS_REGISTRY_USER: AWS + CS_REGISTRY_PASSWORD: "$AWS_ECR_PASSWORD" ``` Authenticating to a remote registry is not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. @@ -190,7 +191,7 @@ Authenticating to a remote registry is not supported when [FIPS mode](../../../d > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. The `CS_DISABLE_DEPENDENCY_LIST` CI/CD variable controls whether the scan creates a -[Dependency List](../dependency_list/) +[Dependency List](../dependency_list/index.md) report. This variable is currently only supported when the `trivy` analyzer is used. The variable's default setting of `"false"` causes the scan to create the report. To disable the report, set the variable to `"true"`: @@ -230,10 +231,10 @@ container_scanning: ``` When you enable this feature, you may see [duplicate findings](../terminology/index.md#duplicate-finding) -in the [Vulnerability Report](../vulnerability_report/) -if [Dependency Scanning](../dependency_scanning/) +in the [Vulnerability Report](../vulnerability_report/index.md) +if [Dependency Scanning](../dependency_scanning/index.md) is enabled for your project. This happens because GitLab can't automatically deduplicate findings -across different types of scanning tools. Please reference [this comparison](../dependency_scanning/#dependency-scanning-compared-to-container-scanning) +across different types of scanning tools. Please reference [this comparison](../dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning) between GitLab Dependency Scanning and Container Scanning for more details on which types of dependencies are likely to be duplicated. #### Available CI/CD variables @@ -251,7 +252,7 @@ including a large number of false positives. | `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | All | | `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:5` | Docker image of the analyzer. | All | -| `CS_DEFAULT_BRANCH_IMAGE` | `""` | The name of the `DOCKER_IMAGE` on the default branch. See [Setting the default branch image](#setting-the-default-branch-image) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338877) in GitLab 14.5. | All | +| `CS_DEFAULT_BRANCH_IMAGE` | `""` | The name of the `CS_IMAGE` on the default branch. See [Setting the default branch image](#setting-the-default-branch-image) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338877) in GitLab 14.5. | All | | `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | Disable Dependency Scanning for packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | @@ -259,10 +260,14 @@ including a large number of false positives. | `CS_IGNORE_UNFIXED` | `"false"` | Ignore vulnerabilities that are not fixed. | All | | `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). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | -| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$DOCKER_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | -| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | +| <!-- start_remove The following content will be removed on remove_date: '2023-08-22' --> `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | **Deprecated** will be removed in GitLab 16.0. Replaced by `CS_IMAGE`. 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` | **Deprecated** will be removed in GitLab 16.0. Replaced by `CS_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). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | +| `DOCKER_USER` | `$CI_REGISTRY_USER` | **Deprecated** will be removed in GitLab 16.0. Replaced by `CS_REGISTRY_USER`. Username for accessing a Docker registry requiring authentication. The default is only set if `$DOCKER_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | +| `DOCKERFILE_PATH` | `Dockerfile` | **Deprecated** will be removed in GitLab 16.0. Replaced by `CS_DOCKERFILE_PATH`. The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All <!-- end_remove --> | +| `CS_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 | +| `CS_REGISTRY_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | +| `CS_REGISTRY_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | +| `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | All | ### Supported distributions @@ -309,7 +314,7 @@ Starting with GitLab 14.10, `-fips` is automatically added to `CS_ANALYZER_IMAGE enabled in the GitLab instance. Container scanning of images in authenticated registries is not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) -is enabled. When `CI_GITLAB_FIPS_MODE` is `"true"`, and `DOCKER_USER` or `DOCKER_PASSWORD` is set, +is enabled. When `CI_GITLAB_FIPS_MODE` is `"true"`, and `CS_REGISTRY_USER` or `CS_REGISTRY_PASSWORD` is set, the analyzer exits with an error and does not perform the scan. ### Enable Container Scanning through an automatic merge request @@ -426,14 +431,14 @@ container_scanning: variables: CS_DEFAULT_BRANCH_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA before_script: - - export DOCKER_IMAGE="$CI_REGISTRY_IMAGE/$CI_COMMIT_BRANCH:$CI_COMMIT_SHA" + - export CS_IMAGE="$CI_REGISTRY_IMAGE/$CI_COMMIT_BRANCH:$CI_COMMIT_SHA" - | if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then - export DOCKER_IMAGE="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" + export CS_IMAGE="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" fi ``` -`CS_DEFAULT_BRANCH_IMAGE` should remain the same for a given `DOCKER_IMAGE`. If it changes, then a +`CS_DEFAULT_BRANCH_IMAGE` should remain the same for a given `CS_IMAGE`. If it changes, then a duplicate set of vulnerabilities are created, which must be manually dismissed. When using [Auto DevOps](../../../topics/autodevops/index.md), `CS_DEFAULT_BRANCH_IMAGE` is @@ -500,7 +505,7 @@ This example excludes from `gl-container-scanning-report.json`: - `generalallowlist` block allows you to specify CVE IDs globally. All vulnerabilities with matching CVE IDs are excluded from the scan report. -- `images` block allows you to specify CVE IDs for each container image independently. All vulnerabilities from the given image with matching CVE IDs are excluded from the scan report. The image name is retrieved from one of the environment variables used to specify the Docker image to be scanned, such as `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` or `DOCKER_IMAGE`. The image provided in this block **must** match this value and **must not** include the tag value. For example, if you specify the image to be scanned using `DOCKER_IMAGE=alpine:3.7`, then you would use `alpine` in the `images` block, but you cannot use `alpine:3.7`. +- `images` block allows you to specify CVE IDs for each container image independently. All vulnerabilities from the given image with matching CVE IDs are excluded from the scan report. The image name is retrieved from one of the environment variables used to specify the Docker image to be scanned, such as `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` or `CS_IMAGE`. The image provided in this block **must** match this value and **must not** include the tag value. For example, if you specify the image to be scanned using `CS_IMAGE=alpine:3.7`, then you would use `alpine` in the `images` block, but you cannot use `alpine:3.7`. You can specify container image in multiple ways: @@ -649,8 +654,8 @@ you're using a non-GitLab Docker registry, you must change the `$CI_REGISTRY` va To scan an image in an external private registry, you must configure access credentials so the container scanning analyzer can authenticate itself before attempting to access the image to scan. -If you use the GitLab [Container Registry](../../packages/container_registry/), -the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables) +If you use the GitLab [Container Registry](../../packages/container_registry/index.md), +the `CS_REGISTRY_USER` and `CS_REGISTRY_PASSWORD` [configuration variables](#available-cicd-variables) are set automatically and you can skip this configuration. This example shows the configuration needed to scan images in a private [Google Container Registry](https://cloud.google.com/container-registry/): @@ -661,12 +666,12 @@ include: container_scanning: variables: - DOCKER_USER: _json_key - DOCKER_PASSWORD: "$GCP_CREDENTIALS" - DOCKER_IMAGE: "gcr.io/path-to-you-registry/image:tag" + CS_REGISTRY_USER: _json_key + CS_REGISTRY_PASSWORD: "$GCP_CREDENTIALS" + CS_IMAGE: "gcr.io/path-to-you-registry/image:tag" ``` -Before you commit this configuration, [add a CI/CD variable](../../../ci/variables/#add-a-cicd-variable-to-a-project) +Before you commit this configuration, [add a CI/CD variable](../../../ci/variables/index.md#add-a-cicd-variable-to-a-project) for `GCP_CREDENTIALS` containing the JSON key, as described in the [Google Cloud Platform Container Registry documentation](https://cloud.google.com/container-registry/docs/advanced-authentication#json-key). Also: @@ -706,12 +711,12 @@ The results are stored in `gl-container-scanning-report.json`. ## Reports JSON format The container scanning tool emits JSON reports which the [GitLab Runner](https://docs.gitlab.com/runner/) -recognizes through the [`artifacts:reports`](../../../ci/yaml/#artifactsreports) +recognizes through the [`artifacts:reports`](../../../ci/yaml/index.md#artifactsreports) keyword in the CI configuration file. Once the CI job finishes, the Runner uploads these reports to GitLab, which are then available in the CI Job artifacts. In GitLab Ultimate, these reports can be viewed in the corresponding [pipeline](../vulnerability_report/pipeline.md) -and become part of the [Vulnerability Report](../vulnerability_report/). +and become part of the [Vulnerability Report](../vulnerability_report/index.md). These reports must follow a format defined in the [security report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/). See: @@ -772,7 +777,7 @@ Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. To enable remediation support, the scanning tool _must_ have access to the `Dockerfile` specified by -the [`DOCKERFILE_PATH`](#available-cicd-variables) CI/CD variable. To ensure that the scanning tool +the [`CS_DOCKERFILE_PATH`](#available-cicd-variables) CI/CD variable. To ensure that the scanning tool has access to this file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/configure_runners.md#git-strategy) in your `.gitlab-ci.yml` file by following the instructions described in this document's diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 154884c16e7..bec242a0426 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -53,7 +53,7 @@ You can use the following fuzzing engines to test the specified languages. To confirm the status of coverage-guided fuzz testing: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Coverage Fuzzing** section the status is: - **Not configured** @@ -174,7 +174,7 @@ artifacts files you can download from the CI/CD pipeline. To view details of the corpus registry: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Coverage Fuzzing** section, select **Manage corpus**. @@ -202,7 +202,7 @@ provided by the `COVFUZZ_CORPUS_NAME` variable. The corpus is updated on every p To upload an existing corpus file: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Coverage Fuzzing** section, select **Manage corpus**. 1. Select **New corpus**. @@ -277,7 +277,7 @@ For a complete example, read the [Go coverage-guided fuzzing example](https://gi It's also possible to run the coverage-guided fuzzing jobs longer and without blocking your main pipeline. This configuration uses the GitLab -[parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md). +[parent-child pipelines](../../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines). The suggested workflow in this scenario is to have long-running, asynchronous fuzzing jobs on the main or development branch, and short synchronous fuzzing jobs on all other branches and MRs. This @@ -376,4 +376,4 @@ corpus file extracts into a folder named `corpus`. If you see this error message when running the fuzzing job with `COVFUZZ_USE_REGISTRY` set to `true`, ensure that duplicates are allowed. For more details, see -[duplicate Generic packages](../../packages/generic_packages/#do-not-allow-duplicate-generic-packages). +[duplicate Generic packages](../../packages/generic_packages/index.md#do-not-allow-duplicate-generic-packages). diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index 5ffd47527c5..6f076bbe3f9 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -1,6 +1,6 @@ --- type: tutorial -stage: Secure +stage: Govern group: Threat Insights 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 --- diff --git a/doc/user/application_security/dast/checks/16.7.md b/doc/user/application_security/dast/checks/16.7.md index 2e6607575db..a052149ee4d 100644 --- a/doc/user/application_security/dast/checks/16.7.md +++ b/doc/user/application_security/dast/checks/16.7.md @@ -25,7 +25,7 @@ Only three directives are applicable for the `Strict-Transport-Security` header. Note that invalid directives, or the `Strict-Transport-Security` header appearing more than once (if the values are different) is considered invalid. -Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org +Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org [Deployment Recommendations](https://hstspreload.org/#deployment-recommendations). ## Details diff --git a/doc/user/application_security/dast/checks/209.1.md b/doc/user/application_security/dast/checks/209.1.md index 2e4163bdec0..f2713a70afd 100644 --- a/doc/user/application_security/dast/checks/209.1.md +++ b/doc/user/application_security/dast/checks/209.1.md @@ -9,17 +9,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description The application was found to return error data such as stack traces. Depending on the data contained within the error message, -this information could be used by an attacker to conduct further attacks. While stack traces are helpful during development -and debugging, they should not be presented to users when an error occurs. +this information could be used by an attacker to conduct further attacks. While stack traces are helpful during development +and debugging, they should not be presented to users when an error occurs. ## Remediation Applications should handle exception conditions internally and map known failure types to error codes that can be displayed to a user. These error codes should be customized to the application and returned along with the relevant HTTP error code. -When an error occurs, the application identifies the error type or class, and displays a numerical value to the -user. Requests should also be tracked so when a user is presented with an error code, it has a corresponding request ID. -Support teams can then correlate the HTTP error, the customized error code, and the request ID in the log files to +When an error occurs, the application identifies the error type or class, and displays a numerical value to the +user. Requests should also be tracked so when a user is presented with an error code, it has a corresponding request ID. +Support teams can then correlate the HTTP error, the customized error code, and the request ID in the log files to determine the root cause of the error without leaking details to the end user. Example of returning customized errors: diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 0c7a9806c72..4e87f1898cc 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Dynamic Application Security Testing (DAST) Troubleshooting **(ULTIMATE)** +# Troubleshooting Dynamic Application Security Testing (DAST) **(ULTIMATE)** The following troubleshooting scenarios have been collected from customer support cases. If you experience a problem not addressed here, or the information here does not fix your problem, create a diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index a49dd8fd646..0f446ddee3e 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -280,7 +280,7 @@ page. You can enable or configure DAST settings using the UI. The generated settings are formatted so they can be conveniently pasted into the `.gitlab-ci.yml` file. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Enable DAST** or **Configure DAST**. @@ -357,13 +357,9 @@ variables: #### Import API specification from a file If your API specification file is in your repository, you can provide its filename as the target. -The API specification file must be in the `/zap/wrk` directory. ```yaml dast: - before_script: - - mkdir -p /zap/wrk - - cp api-specification.yml /zap/wrk/api-specification.yml variables: GIT_STRATEGY: fetch DAST_API_SPECIFICATION: api-specification.yml @@ -1075,7 +1071,7 @@ The on-demand DAST scan runs and the project's dashboard shows the results. To run a saved on-demand scan: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > On-demand Scans**. 1. Select the **Scan library** tab. 1. In the scan's row, select **Run scan**. @@ -1094,7 +1090,7 @@ The on-demand DAST scan runs, and the project's dashboard shows the results. To schedule a scan: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > On-demand Scans**. 1. Select **New scan**. 1. Complete the **Scan name** and **Description** text boxes. @@ -1143,14 +1139,16 @@ To delete an on-demand scan: 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. 1. Select **Delete** to confirm the deletion. -### Site profile +## Site profile -A site profile describes the attributes of a web site to scan on demand with DAST. A site profile is -required for an on-demand DAST scan. +A site profile defines the attributes and configuration details of the deployed application, +website, or API to be scanned by DAST. A site profile can be referenced in `.gitlab-ci.yml` and +on-demand scans. -A site profile contains the following: +A site profile contains: -- **Profile name**: A name you assign to the site to be scanned. +- **Profile name**: A name you assign to the site to be scanned. While a site profile is referenced + in either `.gitlab-ci.yml` or an on-demand scan, it **cannot** be renamed. - **Site type**: The type of target to be scanned, either website or API scan. - **Target URL**: The URL that DAST runs against. - **Excluded URLs**: A comma-separated list of URLs to exclude from the scan. @@ -1168,7 +1166,7 @@ When an API site type is selected, a [host override](#host-override) is used to When configured, request headers and password fields are encrypted using [`aes-256-gcm`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) before being stored in the database. This data can only be read and decrypted with a valid secrets file. -#### Site profile validation +### Site profile validation > - Site profile validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. > - Meta tag validation [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2. @@ -1192,7 +1190,7 @@ All these methods are equivalent in functionality. Use whichever is feasible. In [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/324990), site profile validation happens in a CI job using the [GitLab Runner](../../../ci/runners/index.md). -#### Create a site profile +### Create a site profile To create a site profile: @@ -1203,7 +1201,7 @@ To create a site profile: The site profile is created. -#### Edit a site profile +### Edit a site profile If a site profile is linked to a security policy, a user cannot edit the profile from this page. See [Scan execution policies](../policies/scan-execution-policies.md) @@ -1220,7 +1218,7 @@ To edit a site profile: 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. 1. Edit the fields then select **Save profile**. -#### Delete a site profile +### Delete a site profile If a site profile is linked to a security policy, a user cannot delete the profile from this page. See [Scan execution policies](../policies/scan-execution-policies.md) @@ -1234,13 +1232,13 @@ To delete a site profile: 1. In the profile's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. 1. Select **Delete** to confirm the deletion. -#### Validate a site profile +### Validate a site profile Validating a site is required to run an active scan. To validate a site profile: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. @@ -1266,7 +1264,7 @@ To validate a site profile: The site is validated and an active scan can run against it. A site profile's validation status is revoked only when it's revoked manually, or its file, header, or meta tag is edited. -#### Retry a failed validation +### Retry a failed validation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. > - [Deployed behind the `dast_failed_site_validations` flag](../../../administration/feature_flags.md), enabled by default. @@ -1277,13 +1275,13 @@ page. To retry a site profile's failed validation: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. 1. In the profile's row, select **Retry validation**. -#### Revoke a site profile's validation status +### Revoke a site profile's validation status WARNING: When a site profile's validation status is revoked, all site profiles that share the same URL also @@ -1297,12 +1295,12 @@ To revoke a site profile's validation status: The site profile's validation status is revoked. -#### Validated site profile headers +### Validated site profile headers The following are code samples of how you can provide the required site profile header in your application. -##### Ruby on Rails example for on-demand scan +#### Ruby on Rails example for on-demand scan Here's how you can add a custom header in a Ruby on Rails application: @@ -1315,7 +1313,7 @@ class DastWebsiteTargetController < ActionController::Base end ``` -##### Django example for on-demand scan +#### Django example for on-demand scan Here's how you can add a [custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields): @@ -1329,7 +1327,7 @@ class DastWebsiteTargetView(View): return response ``` -##### Node (with Express) example for on-demand scan +#### Node (with Express) example for on-demand scan Here's how you can add a [custom header in Node (with Express)](https://expressjs.com/en/5x/api.html#res.append): @@ -1341,22 +1339,26 @@ app.get('/dast-website-target', function(req, res) { }) ``` -### Scanner profile +## Scanner profile > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222767) in GitLab 13.4. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/225804) in GitLab 13.5: scan mode, AJAX spider, debug messages. -A scanner profile defines the scanner settings used to run an on-demand scan: +A scanner profile defines the configuration details of a security scanner. A scanner profile can be +referenced in `.gitlab-ci.yml` and on-demand scans. -- **Profile name:** A name you give the scanner profile. For example, "Spider_15". +A scanner profile contains: + +- **Profile name:** A name you give the scanner profile. For example, "Spider_15". While a scanner + profile is referenced in either `.gitlab-ci.yml` or an on-demand scan, it **cannot** be renamed. - **Scan mode:** A passive scan monitors all HTTP messages (requests and responses) sent to the target. An active scan attacks the target to find potential vulnerabilities. - **Spider timeout:** The maximum number of minutes allowed for the spider to traverse the site. - **Target timeout:** The maximum number of seconds DAST waits for the site to be available before starting the scan. -- **AJAX spider:** Run the AJAX spider, in addition to the traditional spider, to crawl the target site. +- **AJAX spider:** Run the AJAX spider, in addition to the traditional spider, to crawl the target site. - **Debug messages:** Include debug messages in the DAST console output. -#### Create a scanner profile +### Create a scanner profile To create a scanner profile: @@ -1366,7 +1368,7 @@ To create a scanner profile: 1. Complete the form. For details of each field, see [Scanner profile](#scanner-profile). 1. Select **Save profile**. -#### Edit a scanner profile +### Edit a scanner profile If a scanner profile is linked to a security policy, a user cannot edit the profile from this page. See [Scan execution policies](../policies/scan-execution-policies.md) @@ -1381,7 +1383,7 @@ To edit a scanner profile: 1. Edit the form. 1. Select **Save profile**. -#### Delete a scanner profile +### Delete a scanner profile If a scanner profile is linked to a security policy, a user cannot delete the profile from this page. See [Scan execution policies](../policies/scan-execution-policies.md) diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 1f86f2ffa49..f15dce37123 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -55,6 +55,7 @@ The following projects demonstrate DAST API scanning: You can specify the API you want to scan by using: - [OpenAPI v2 or v3 Specification](#openapi-specification) +- [GraphQL Schema](#graphql-schema) - [HTTP Archive (HAR)](#http-archive-har) - [Postman Collection v2.0 or v2.1](#postman-collection) @@ -199,7 +200,119 @@ variables: DAST_API_TARGET_URL: http://test-deployment/ ``` -This is a minimal configuration for DAST API. From here you can: +This example is a minimal configuration for DAST API. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + +### GraphQL Schema + +> Support for GraphQL Schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. + +GraphQL is a query language for your API and an alternative to REST APIs. +DAST API supports testing GraphQL endpoints multiple ways: + +- Test using the GraphQL Schema. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. +- Test using a recording (HAR) of GraphQL queries. +- Test using a Postman Collection containing GraphQL queries. + +This section documents how to test using a GraphQL schema. The GraphQL schema support in +DAST API is able to query the schema from endpoints that support introspection. +Introspection is enabled by default to allow tools like GraphiQL to work. + +#### DAST API scanning with a GraphQL endpoint URL + +The GraphQL support in DAST API is able to query a GraphQL endpoint for the schema. + +NOTE: +The GraphQL endpoint must support introspection queries for this method to work correctly. + +To configure DAST API to use a GraphQL endpoint URL that provides information about the target API to test: + +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) in your `.gitlab-ci.yml` file. + +1. Provide the path to the GraphQL endpoint, for example `/api/graphql`. Specify the location by adding the `DAST_API_GRAPHQL` variable. + +1. The target API instance's base URL is also required. Provide it by using the `DAST_API_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. See the [dynamic environment solutions](#dynamic-environment-solutions) section of our documentation for more information. + +Complete example configuration of using a GraphQL endpoint path: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +dast_api: + variables: + DAST_API_GRAPHQL: /api/graphql + DAST_API_TARGET_URL: http://test-deployment/ +``` + +This example is a minimal configuration for DAST API. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + +#### DAST API scanning with a GraphQL Schema file + +To configure DAST API to use a GraphQL schema file that provides information about the target API to test: + +1. [Include](../../../ci/yaml/index.md#includetemplate) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) in your `.gitlab-ci.yml` file. + +1. Provide the GraphQL endpoint path, for example `/api/graphql`. Specify the path by adding the `DAST_API_GRAPHQL` variable. + +1. Provide the location of the GraphQL schema file. You can provide the location as a file path + or URL. Specify the location by adding the `DAST_API_GRAPHQL_SCHEMA` variable. + +1. The target API instance's base URL is also required. Provide it by using the `DAST_API_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. See the [dynamic environment solutions](#dynamic-environment-solutions) section of our documentation for more information. + +Complete example configuration of using an GraphQL schema file: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +dast_api: + variables: + DAST_API_GRAPHQL: /api/graphql + DAST_API_GRAPHQL_SCHEMA: test-api-graphql.schema + DAST_API_TARGET_URL: http://test-deployment/ +``` + +Complete example configuration of using an GraphQL schema file URL: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +dast_api: + variables: + DAST_API_GRAPHQL: /api/graphql + DAST_API_GRAPHQL_SCHEMA: http://file-store/files/test-api-graphql.schema + DAST_API_TARGET_URL: http://test-deployment/ +``` + +This example is a minimal configuration for DAST API. From here you can: - [Run your first scan](#running-your-first-scan). - [Add authentication](#authentication). @@ -267,35 +380,266 @@ This is a minimal configuration for DAST API. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -##### Postman variables +#### Postman variables + +> - Support for Postman Environment file format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. +> - Support for multiple variable files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. +> - Support for Postman variable scopes: Global and Environment was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. + +##### Variables in Postman Client Postman allows the developer to define placeholders that can be used in different parts of the -requests. These placeholders are called variables, as explained in [Using variables](https://learning.postman.com/docs/sending-requests/variables/). +requests. These placeholders are called variables, as explained in [using variables](https://learning.postman.com/docs/sending-requests/variables/). You can use variables to store and reuse values in your requests and scripts. For example, you can edit the collection to add variables to the document:  +Or alternatively, you can add variables in an environment: + + + You can then use the variables in sections such as URL, headers, and others:  -Variables can be defined at different [scopes](https://learning.postman.com/docs/sending-requests/variables/#variable-scopes) -(for example, Global, Collection, Environment, Local, and Data). In this example, they're defined at -the Environment scope: +Postman has grown from a basic client tool with a nice UX experience to a more complex ecosystem that allows testing APIs with scripts, creating complex collections that trigger secondary requests, and setting variables along the way. Not every feature in the Postman ecosystem is supported. For example, scripts are not supported. The main focus of the Postman support is to ingest Postman Collection definitions that are used by the Postman Client and their related variables defined in the workspace, environments, and the collections themselves. - +Postman allows creating variables in different scopes. Each scope has a different level of visibility in the Postman tools. For example, you can create a variable in a _global environment_ scope that is seen by every operation definition and workspace. You can also create a variable in a specific _environment_ scope that is only visible and used when that specific environment is selected for use. Some scopes are not always available, for example in the Postman ecosystem you can create requests in the Postman Client, these requests do not have a _local_ scope, but test scripts do. -When you export a Postman collection, only Postman collection variables are exported into the -Postman file. For example, Postman does not export environment-scoped variables into the Postman -file. +Variable scopes in Postman can be a daunting topic and not everyone is familiar with it. We strongly recommend that you read [Variable Scopes](https://learning.postman.com/docs/sending-requests/variables/#variable-scopes) from Postman documentation before moving forward. -By default, the DAST API scanner uses the Postman file to resolve Postman variable values. If a JSON file -is set in a GitLab CI/CD environment variable `DAST_API_POSTMAN_COLLECTION_VARIABLES`, then the JSON -file takes precedence to get Postman variable values. +As mentioned above, there are different variable scopes, and each of them has a purpose and can be used to provide more flexibility to your Postman document. There is an important note on how values for variables are computed, as per Postman documentation: -WARNING: -Although Postman can export environment variables into a JSON file, the format is not compatible with the JSON expected by `DAST_API_POSTMAN_COLLECTION_VARIABLES`. +> If a variable with the same name is declared in two different scopes, the value stored in the variable with narrowest scope is used. For example, if there is a global variable named `username` and a local variable named `username`, the local value is used when the request runs. + +The following is a summary of the variable scopes supported by the Postman Client and DAST API: + +- **Global Environment (Global) scope** is a special pre-defined environment that is available throughout a workspace. We can also refer to the _global environment_ scope as the _global_ scope. The Postman Client allows exporting the global environment into a JSON file, which can be used with DAST API. +- **Environment scope** is a named group of variables created by a user in the Postman Client. +The Postman Client supports a single active environment along with the global environment. The variables defined in an active user-created environment take precedence over variables defined in the global environment. The Postman Client allows exporting your environment into a JSON file, which can be used with DAST API. +- **Collection scope** is a group of variables declared in a given collection. The collection variables are available to the collection where they have been declared and the nested requests or collections. Variables defined in the collection scope take precedence over the _global environment_ scope and also the _environment_ scope. +The Postman Client can export one or more collections into a JSON file, this JSON file contains selected collections, requests, and collection variables. +- **DAST API Scope** is a new scope added by DAST API to allow users to provide extra variables, or override variables defined in other supported scopes. This scope is not supported by Postman. The _DAST API Scope_ variables are provided using a [custom JSON file format](#dast-api-scope-custom-json-file-format). + - Override values defined in the environment or collection + - Defining variables from scripts + - Define a single row of data from the unsupported _data scope_ +- **Data scope** is a group of variables in which their name and values come from JSON or CSV files. A Postman collection runner like [Newman](https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/) or [Postman Collection Runner](https://learning.postman.com/docs/running-collections/intro-to-collection-runs/) executes the requests in a collection as many times as entries have the JSON or CSV file. A good use case for these variables is to automate tests using scripts in Postman. +DAST API does **not** support reading data from a CSV or JSON file. +- **Local scope** are variables that are defined in Postman scripts. DAST API does **not** support Postman scripts and by extension, variables defined in scripts. You can still provide values for the script-defined variables by defining them in one of the supported scopes, or our custom JSON format. + +Not all scopes are supported by DAST API and variables defined in scripts are not supported. The following table is sorted by broadest scope to narrowest scope. + +| Scope |Postman | DAST API | Comment | +| ------------------ |:---------:|:------------:| :--------| +| Global Environment | Yes | Yes | Special pre-defined environment | +| Environment | Yes | Yes | Named environments | +| Collection | Yes | Yes | Defined in your postman collection | +| DAST API Scope | No | Yes | Custom scope added by DAST API | +| Data | Yes | No | External files in CSV or JSON format | +| Local | Yes | No | Variables defined in scripts | + +For more details on how to define variables and export variables in different scopes, see: + +- [Defining collection variables](https://learning.postman.com/docs/sending-requests/variables/#defining-collection-variables) +- [Defining environment variables](https://learning.postman.com/docs/sending-requests/variables/#defining-environment-variables) +- [Defining global variables](https://learning.postman.com/docs/sending-requests/variables/#defining-global-variables) + +##### Exporting from Postman Client + +The Postman Client lets you export different file formats, for instance, you can export a Postman collection or a Postman environment. +The exported environment can be the global environment (which is always available) or can be any custom environment you previously have created. When you export a Postman Collection, it may contain only declarations for _collection_ and _local_ scoped variables; _environment_ scoped variables are not included. + +To get the declaration for _environment_ scoped variables, you have to export a given environment at the time. Each exported file only includes variables from the selected environment. + +For more details on exporting variables in different supported scopes, see: + +- [Exporting collections](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-collections) +- [Exporting environments](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) +- [Downloading global environments](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) + +##### DAST API Scope, custom JSON file format + +Our custom JSON file format is a JSON object where each object property represents a variable name and the property value represents the variable value. This file can be created using your favorite text editor, or it can be produced by an earlier job in your pipeline. + +This example defines two variables `base_url` and `token` in the DAST API scope: + +```json +{ + "base_url": "http://127.0.0.1/", + "token": "Token 84816165151" +} +``` + +##### Using scopes with DAST API + +The scopes: _global_, _environment_, _collection_, and _GitLab DAST API_ are supported in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/356312). GitLab 15.0 and earlier, supports only the _collection_, and _GitLab DAST API_ scopes. + +The following table provides a quick reference for mapping scope files/URLs to DAST API configuration variables: + +| Scope | How to Provide | +| ------------------ | --------------- | +| Global Environment | DAST_API_POSTMAN_COLLECTION_VARIABLES | +| Environment | DAST_API_POSTMAN_COLLECTION_VARIABLES | +| Collection | DAST_API_POSTMAN_COLLECTION | +| DAST API Scope | DAST_API_POSTMAN_COLLECTION_VARIABLES | +| Data | Not supported | +| Local | Not supported | + +The Postman Collection document automatically includes any _collection_ scoped variables. The Postman Collection is provided with the configuration variable `DAST_API_POSTMAN_COLLECTION`. This variable can be set to a single [exported Postman collection](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-collections). + +Variables from other scopes are provided through the `DAST_API_POSTMAN_COLLECTION_VARIABLES` configuration variable. The configuration variable supports a comma (`,`) delimited file list in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/356312). GitLab 15.0 and earlier, supports only one single file. The order of the files provided is not important as the files provide the needed scope information. + +The configuration variable `DAST_API_POSTMAN_COLLECTION_VARIABLES` can be set to: + +- [Exported Global environment](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) +- [Exported environments](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) +- [DAST API Custom JSON format](#dast-api-scope-custom-json-file-format) + +##### Undefined Postman variables + +There is a chance that DAST API engine does not find all variables references that your Postman collection file is using. Some cases can be: + +- You are using _data_ or _local_ scoped variables, and as stated previously these scopes are not supported by DAST API. Thus, assuming the values for these variables have not been provided through [the DAST API scope](#dast-api-scope-custom-json-file-format), then the values of the _data_ and _local_ scoped variables are undefined. +- A variable name was typed incorrectly, and the name does not match the defined variable. +- Postman Client supports a new dynamic variable that is not supported by DAST API. + +When possible, DAST API follows the same behavior as the Postman Client does when dealing with undefined variables. The text of the variable reference remains the same, and there is no text substitution. The same behavior also applies to any unsupported dynamic variables. + +For example, if a request definition in the Postman Collection references the variable `{{full_url}}` and the variable is not found it is left unchanged with the value `{{full_url}}`. + +##### Dynamic Postman variables + +In addition to variables that a user can define at various scope levels, Postman has a set of pre-defined variables called _dynamic_ variables. The [_dynamic_ variables](https://learning.postman.com/docs/writing-scripts/script-references/variables-list/) are already defined and their name is prefixed with a dollar sign (`$`), for instance, `$guid`. _Dynamic_ variables can be used like any other variable, and in the Postman Client, they produce random values during the request/collection run. + +An important difference between DAST API and Postman is that DAST API returns the same value for each usage of the same dynamic variables. This differs from the Postman Client behavior which returns a random value on each use of the same dynamic variable. In other words, DAST API uses static values for dynamic variables while Postman uses random values. + +The supported dynamic variables during the scanning process are: + +| Variable | Value | +| ----------- | ----------- | +| `$guid` | `611c2e81-2ccb-42d8-9ddc-2d0bfa65c1b4` | +| `$isoTimestamp` | `2020-06-09T21:10:36.177Z` | +| `$randomAbbreviation` | `PCI` | +| `$randomAbstractImage` | `http://no-a-valid-host/640/480/abstract` | +| `$randomAdjective` | `auxiliary` | +| `$randomAlphaNumeric` | `a` | +| `$randomAnimalsImage` | `http://no-a-valid-host/640/480/animals` | +| `$randomAvatarImage` | `https://no-a-valid-host/path/to/some/image.jpg` | +| `$randomBankAccount` | `09454073` | +| `$randomBankAccountBic` | `EZIAUGJ1` | +| `$randomBankAccountIban` | `MU20ZPUN3039684000618086155TKZ` | +| `$randomBankAccountName` | `Home Loan Account` | +| `$randomBitcoin` | `3VB8JGT7Y4Z63U68KGGKDXMLLH5` | +| `$randomBoolean` | `true` | +| `$randomBs` | `killer leverage schemas` | +| `$randomBsAdjective` | `viral` | +| `$randomBsBuzz` | `repurpose` | +| `$randomBsNoun` | `markets` | +| `$randomBusinessImage` | `http://no-a-valid-host/640/480/business` | +| `$randomCatchPhrase` | `Future-proofed heuristic open architecture` | +| `$randomCatchPhraseAdjective` | `Business-focused` | +| `$randomCatchPhraseDescriptor` | `bandwidth-monitored` | +| `$randomCatchPhraseNoun` | `superstructure` | +| `$randomCatsImage` | `http://no-a-valid-host/640/480/cats` | +| `$randomCity` | `Spinkahaven` | +| `$randomCityImage` | `http://no-a-valid-host/640/480/city` | +| `$randomColor` | `fuchsia` | +| `$randomCommonFileExt` | `wav` | +| `$randomCommonFileName` | `well_modulated.mpg4` | +| `$randomCommonFileType` | `audio` | +| `$randomCompanyName` | `Grady LLC` | +| `$randomCompanySuffix` | `Inc` | +| `$randomCountry` | `Kazakhstan` | +| `$randomCountryCode` | `MD` | +| `$randomCreditCardMask` | `3622` | +| `$randomCurrencyCode` | `ZMK` | +| `$randomCurrencyName` | `Pound Sterling` | +| `$randomCurrencySymbol` | `£` | +| `$randomDatabaseCollation` | `utf8_general_ci` | +| `$randomDatabaseColumn` | `updatedAt` | +| `$randomDatabaseEngine` | `Memory` | +| `$randomDatabaseType` | `text` | +| `$randomDateFuture` | `Tue Mar 17 2020 13:11:50 GMT+0530 (India Standard Time)` | +| `$randomDatePast` | `Sat Mar 02 2019 09:09:26 GMT+0530 (India Standard Time)` | +| `$randomDateRecent` | `Tue Jul 09 2019 23:12:37 GMT+0530 (India Standard Time)` | +| `$randomDepartment` | `Electronics` | +| `$randomDirectoryPath` | `/usr/local/bin` | +| `$randomDomainName` | `trevor.info` | +| `$randomDomainSuffix` | `org` | +| `$randomDomainWord` | `jaden` | +| `$randomEmail` | `Iva.Kovacek61@no-a-valid-host.com` | +| `$randomExampleEmail` | `non-a-valid-user@example.net` | +| `$randomFashionImage` | `http://no-a-valid-host/640/480/fashion` | +| `$randomFileExt` | `war` | +| `$randomFileName` | `neural_sri_lanka_rupee_gloves.gdoc` | +| `$randomFilePath` | `/home/programming_chicken.cpio` | +| `$randomFileType` | `application` | +| `$randomFirstName` | `Chandler` | +| `$randomFoodImage` | `http://no-a-valid-host/640/480/food` | +| `$randomFullName` | `Connie Runolfsdottir` | +| `$randomHexColor` | `#47594a` | +| `$randomImageDataUri` | `data:image/svg+xml;charset=UTF-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20version%3D%221.1%22%20baseProfile%3D%22full%22%20width%3D%22undefined%22%20height%3D%22undefined%22%3E%20%3Crect%20width%3D%22100%25%22%20height%3D%22100%25%22%20fill%3D%22grey%22%2F%3E%20%20%3Ctext%20x%3D%220%22%20y%3D%2220%22%20font-size%3D%2220%22%20text-anchor%3D%22start%22%20fill%3D%22white%22%3Eundefinedxundefined%3C%2Ftext%3E%20%3C%2Fsvg%3E` | +| `$randomImageUrl` | `http://no-a-valid-host/640/480` | +| `$randomIngverb` | `navigating` | +| `$randomInt` | `494` | +| `$randomIP` | `241.102.234.100` | +| `$randomIPV6` | `dbe2:7ae6:119b:c161:1560:6dda:3a9b:90a9` | +| `$randomJobArea` | `Mobility` | +| `$randomJobDescriptor` | `Senior` | +| `$randomJobTitle` | `International Creative Liaison` | +| `$randomJobType` | `Supervisor` | +| `$randomLastName` | `Schneider` | +| `$randomLatitude` | `55.2099` | +| `$randomLocale` | `ny` | +| `$randomLongitude` | `40.6609` | +| `$randomLoremLines` | `Ducimus in ut mollitia.\nA itaque non.\nHarum temporibus nihil voluptas.\nIste in sed et nesciunt in quaerat sed.` | +| `$randomLoremParagraph` | `Ab aliquid odio iste quo voluptas voluptatem dignissimos velit. Recusandae facilis qui commodi ea magnam enim nostrum quia quis. Nihil est suscipit assumenda ut voluptatem sed. Esse ab voluptas odit qui molestiae. Rem est nesciunt est quis ipsam expedita consequuntur.` | +| `$randomLoremParagraphs` | `Voluptatem rem magnam aliquam ab id aut quaerat. Placeat provident possimus voluptatibus dicta velit non aut quasi. Mollitia et aliquam expedita sunt dolores nam consequuntur. Nam dolorum delectus ipsam repudiandae et ipsam ut voluptatum totam. Nobis labore labore recusandae ipsam quo.` | +| `$randomLoremSentence` | `Molestias consequuntur nisi non quod.` | +| `$randomLoremSentences` | `Et sint voluptas similique iure amet perspiciatis vero sequi atque. Ut porro sit et hic. Neque aspernatur vitae fugiat ut dolore et veritatis. Ab iusto ex delectus animi. Voluptates nisi iusto. Impedit quod quae voluptate qui.` | +| `$randomLoremSlug` | `eos-aperiam-accusamus, beatae-id-molestiae, qui-est-repellat` | +| `$randomLoremText` | `Quisquam asperiores exercitationem ut ipsum. Aut eius nesciunt. Et reiciendis aut alias eaque. Nihil amet laboriosam pariatur eligendi. Sunt ullam ut sint natus ducimus. Voluptas harum aspernatur soluta rem nam.` | +| `$randomLoremWord` | `est` | +| `$randomLoremWords` | `vel repellat nobis` | +| `$randomMACAddress` | `33:d4:68:5f:b4:c7` | +| `$randomMimeType` | `audio/vnd.vmx.cvsd` | +| `$randomMonth` | `February` | +| `$randomNamePrefix` | `Dr.` | +| `$randomNameSuffix` | `MD` | +| `$randomNatureImage` | `http://no-a-valid-host/640/480/nature` | +| `$randomNightlifeImage` | `http://no-a-valid-host/640/480/nightlife` | +| `$randomNoun` | `bus` | +| `$randomPassword` | `t9iXe7COoDKv8k3` | +| `$randomPeopleImage` | `http://no-a-valid-host/640/480/people` | +| `$randomPhoneNumber` | `700-008-5275` | +| `$randomPhoneNumberExt` | `27-199-983-3864` | +| `$randomPhrase` | `You can't program the monitor without navigating the mobile XML program!` | +| `$randomPrice` | `531.55` | +| `$randomProduct` | `Pizza` | +| `$randomProductAdjective` | `Unbranded` | +| `$randomProductMaterial` | `Steel` | +| `$randomProductName` | `Handmade Concrete Tuna` | +| `$randomProtocol` | `https` | +| `$randomSemver` | `7.0.5` | +| `$randomSportsImage` | `http://no-a-valid-host/640/480/sports` | +| `$randomStreetAddress` | `5742 Harvey Streets` | +| `$randomStreetName` | `Kuhic Island` | +| `$randomTransactionType` | `payment` | +| `$randomTransportImage` | `http://no-a-valid-host/640/480/transport` | +| `$randomUrl` | `https://no-a-valid-host.net` | +| `$randomUserAgent` | `Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.9.8; rv:15.6) Gecko/20100101 Firefox/15.6.6` | +| `$randomUserName` | `Jarrell.Gutkowski` | +| `$randomUUID` | `6929bb52-3ab2-448a-9796-d6480ecad36b` | +| `$randomVerb` | `navigate` | +| `$randomWeekday` | `Thursday` | +| `$randomWord` | `withdrawal` | +| `$randomWords` | `Samoa Synergistic sticky copying Grocery` | +| `$timestamp` | `1562757107` | + +##### Example: Global Scope + +In this example, [the _global_ scope is exported](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) from the Postman Client as `global-scope.json` and provided to DAST API through the `DAST_API_POSTMAN_COLLECTION_VARIABLES` configuration variable. Here is an example of using `DAST_API_POSTMAN_COLLECTION_VARIABLES`: @@ -308,21 +652,170 @@ include: variables: DAST_API_PROFILE: Quick - DAST_API_POSTMAN_COLLECTION: postman-collection_serviceA.json - DAST_API_POSTMAN_COLLECTION_VARIABLES: variable-collection-dictionary.json + DAST_API_POSTMAN_COLLECTION: postman-collection.json + DAST_API_POSTMAN_COLLECTION_VARIABLES: global-scope.json + DAST_API_TARGET_URL: http://test-deployment/ +``` + +##### Example: Environment Scope + +In this example, [the _environment_ scope is exported](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) from the Postman Client as `environment-scope.json` and provided to DAST API through the `DAST_API_POSTMAN_COLLECTION_VARIABLES` configuration variable. + +Here is an example of using `DAST_API_POSTMAN_COLLECTION_VARIABLES`: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection.json + DAST_API_POSTMAN_COLLECTION_VARIABLES: environment-scope.json DAST_API_TARGET_URL: http://test-deployment/ ``` -The file `variable-collection-dictionary.json` is a JSON document. This JSON is an object with -key-value pairs for properties. The keys are the variables' names, and the values are the variables' +##### Example: Collection Scope + +The _collection_ scope variables are included in the exported Postman Collection file and provided through the `DAST_API_POSTMAN_COLLECTION` configuration variable. + +Here is an example of using `DAST_API_POSTMAN_COLLECTION`: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection.json + DAST_API_TARGET_URL: http://test-deployment/ +``` + +##### Example: DAST API Scope + +The DAST API Scope is used for two main purposes, defining _data_ and _local_ scope variables that are not supported by DAST API, and changing the value of an existing variable defined in another scope. The DAST API Scope is provided through the `DAST_API_POSTMAN_COLLECTION_VARIABLES` configuration variable. + +Here is an example of using `DAST_API_POSTMAN_COLLECTION_VARIABLES`: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection.json + DAST_API_POSTMAN_COLLECTION_VARIABLES: dast-api-scope.json + DAST_API_TARGET_URL: http://test-deployment/ +``` + +The file `dast-api-scope.json` uses our [custom JSON file format](#dast-api-scope-custom-json-file-format). This JSON is an object with key-value pairs for properties. The keys are the variables' names, and the values are the variables' values. For example: - ```json - { - "base_url": "http://127.0.0.1/", - "token": "Token 84816165151" - } - ``` +```json +{ + "base_url": "http://127.0.0.1/", + "token": "Token 84816165151" +} +``` + +##### Example: Multiple Scopes + +In this example, a _global_ scope, _environment_ scope, and _collection_ scope are configured. The first step is to export our various scopes. + +- [Export the _global_ scope](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) as `global-scope.json` +- [Export the _environment_ scope](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) as `environment-scope.json` +- Export the Postman Collection which includes the _collection_ scope as `postman-collection.json` + +The Postman Collection is provided using the `DAST_API_POSTMAN_COLLECTION` variable, while the other scopes are provided using the `DAST_API_POSTMAN_COLLECTION_VARIABLES`. DAST API can identify which scope the provided files match using data provided in each file. + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection.json + DAST_API_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json + DAST_API_TARGET_URL: http://test-deployment/ +``` + +##### Example: Changing a Variables Value + +When using exported scopes, it's often the case that the value of a variable must be changed for use with DAST API. For example, a _collection_ scoped variable might contain a variable named `api_version` with a value of `v2`, while your test needs a value of `v1`. Instead of modifying the exported collection to change the value, the DAST API scope can be used to change its value. This works because the _DAST API_ scope takes precedence over all other scopes. + +The _collection_ scope variables are included in the exported Postman Collection file and provided through the `DAST_API_POSTMAN_COLLECTION` configuration variable. + +The DAST API Scope is provided through the `DAST_API_POSTMAN_COLLECTION_VARIABLES` configuration variable, but first, we must create the file. +The file `dast-api-scope.json` uses our [custom JSON file format](#dast-api-scope-custom-json-file-format). This JSON is an object with key-value pairs for properties. The keys are the variables' names, and the values are the variables' +values. For example: + +```json +{ + "api_version": "v1" +} +``` + +Our CI definition: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection.json + DAST_API_POSTMAN_COLLECTION_VARIABLES: dast-api-scope.json + DAST_API_TARGET_URL: http://test-deployment/ +``` + +##### Example: Changing a Variables Value with Multiple Scopes + +When using exported scopes, it's often the case that the value of a variable must be changed for use with DAST API. For example, an _environment_ scope might contain a variable named `api_version` with a value of `v2`, while your test needs a value of `v1`. Instead of modifying the exported file to change the value, the DAST API scope can be used. This works because the _DAST API_ scope takes precedence over all other scopes. + +In this example, a _global_ scope, _environment_ scope, _collection_ scope, and _DAST API_ scope are configured. The first step is to export and create our various scopes. + +- [Export the _global_ scope](https://learning.postman.com/docs/sending-requests/variables/#downloading-global-environments) as `global-scope.json` +- [Export the _environment_ scope](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments) as `environment-scope.json` +- Export the Postman Collection which includes the _collection_ scope as `postman-collection.json` + +The DAST API scope is used by creating a file `dast-api-scope.json` using our [custom JSON file format](#dast-api-scope-custom-json-file-format). This JSON is an object with key-value pairs for properties. The keys are the variables' names, and the values are the variables' +values. For example: + +```json +{ + "api_version": "v1" +} +``` + +The Postman Collection is provided using the `DAST_API_POSTMAN_COLLECTION` variable, while the other scopes are provided using the `DAST_API_POSTMAN_COLLECTION_VARIABLES`. DAST API can identify which scope the provided files match using data provided in each file. + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection.json + DAST_API_POSTMAN_COLLECTION_VARIABLES: global-scope.json,environment-scope.json,dast-api-scope.json + DAST_API_TARGET_URL: http://test-deployment/ +``` ## Authentication @@ -332,17 +825,19 @@ provide a script that performs an authentication flow or calculates the token. ### HTTP Basic Authentication [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) -is an authentication method built in to the HTTP protocol and used in conjunction with +is an authentication method built into the HTTP protocol and used in conjunction with [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). -To use HTTP basic authentication, two CI/CD variables are added to your `.gitlab-ci.yml` file: -- `DAST_API_HTTP_USERNAME`: The username for authentication. -- `DAST_API_HTTP_PASSWORD`: The password for authentication. +We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables) +for the password (for example, `TEST_API_PASSWORD`), and set it to be masked. You can create CI/CD +variables from the GitLab project's page at **Settings > CI/CD**, in the **Variables** section. +Because of the [limitations on masked variables](../../../ci/variables/index.md#mask-a-cicd-variable), +you should Base64-encode the password before adding it as a variable. -For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables) -(for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the -GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Use that variable -as the value for `DAST_API_HTTP_PASSWORD`: +Finally, add two CI/CD variables to your `.gitlab-ci.yml` file: + +- `DAST_API_HTTP_USERNAME`: The username for authentication. +- `DAST_API_HTTP_PASSWORD_BASE64`: The Base64-encoded password for authentication. ```yaml stages: @@ -356,9 +851,13 @@ variables: DAST_API_HAR: test-api-recording.har DAST_API_TARGET_URL: http://test-deployment/ DAST_API_HTTP_USERNAME: testuser - DAST_API_HTTP_PASSWORD: $TEST_API_PASSWORD + DAST_API_HTTP_PASSWORD_BASE64: $TEST_API_PASSWORD ``` +#### Raw password + +If you do not want to Base64-encode the password (or if you are using GitLab 15.3 or earlier) you can provide the raw password `DAST_API_HTTP_PASSWORD`, instead of using `DAST_API_HTTP_PASSWORD_BASE64`. + ### Bearer tokens Bearer tokens are used by several different authentication mechanisms, including OAuth2 and JSON Web @@ -383,7 +882,7 @@ Follow these steps to provide the Bearer token with `DAST_API_OVERRIDES_ENV`: can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Due to the format of `TEST_API_BEARERAUTH` it's not possible to mask the variable. - To mask the token's value, you can create a second variable with the token value's, and define + To mask the token's value, you can create a second variable with the token values, and define `TEST_API_BEARERAUTH` with the value `{"headers":{"Authorization":"Bearer $MASKED_VARIABLE"}}`. 1. In your `.gitlab-ci.yml` file, set `DAST_API_OVERRIDES_ENV` to the variable you just created: @@ -402,12 +901,12 @@ Follow these steps to provide the Bearer token with `DAST_API_OVERRIDES_ENV`: DAST_API_OVERRIDES_ENV: $TEST_API_BEARERAUTH ``` -1. To validate that authentication is working, run an DAST API test and review the job logs +1. To validate that authentication is working, run a DAST API test and review the job logs and the test API's application logs. #### Token generated at test runtime -If the Bearer token must be generated and doesn't expire during testing, you can provide DAST API a file that has the token. A prior stage and job, or part of the DAST API job, can +If the Bearer token must be generated and doesn't expire during testing, you can provide DAST API with a file that has the token. A prior stage and job, or part of the DAST API job, can generate this file. DAST API expects to receive a JSON file with the following structure: @@ -439,7 +938,7 @@ variables: DAST_API_OVERRIDES_FILE: dast-api-overrides.json ``` -To validate that authentication is working, run an DAST API test and review the job logs and +To validate that authentication is working, run a DAST API test and review the job logs and the test API's application logs. #### Token has short expiration @@ -552,8 +1051,10 @@ can be added, removed, and modified by creating a custom configuration. |[`DAST_API_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`DAST_API_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | +|[`DAST_API_GRAPHQL`](#graphql-schema) | Path to GraphQL endpoint, for example `/api/graphql`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. | +|[`DAST_API_GRAPHQL_SCHEMA`](#graphql-schema) | A URL or filename for a GraphQL schema in JSON format. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | -|[`DAST_API_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract postman variable values. | +|[`DAST_API_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. The support for comma-separated (`,`) files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. | |[`DAST_API_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | |[`DAST_API_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | |[`DAST_API_OVERRIDES_CMD`](#overrides) | Overrides command. | @@ -562,7 +1063,8 @@ can be added, removed, and modified by creating a custom configuration. |`DAST_API_POST_SCRIPT` | Run user command or script after scan session has finished. | |[`DAST_API_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | |[`DAST_API_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | -|[`DAST_API_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | +|[`DAST_API_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. Consider using `DAST_API_HTTP_PASSWORD_BASE64` instead. | +|[`DAST_API_HTTP_PASSWORD_BASE64`](#http-basic-authentication) | Password for HTTP authentication, base64-encoded. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing-src/-/merge_requests/702) in GitLab 15.4. | |`DAST_API_SERVICE_START_TIMEOUT` | How long to wait for target API to become available in seconds. Default is 300 seconds. | |`DAST_API_TIMEOUT` | How long to wait for API responses in seconds. Default is 30 seconds. | @@ -1010,21 +1512,21 @@ This example excludes the `/auth` resource. This does not exclude child resource ```yaml variables: - DAST_API_EXCLUDE_PATHS=/auth + DAST_API_EXCLUDE_PATHS: /auth ``` To exclude `/auth`, and child resources (`/auth/child`), we use a wildcard. ```yaml variables: - DAST_API_EXCLUDE_PATHS=/auth* + DAST_API_EXCLUDE_PATHS: /auth* ``` To exclude multiple paths we use the `;` character. In this example we exclude `/auth*` and `/v1/*`. ```yaml variables: - DAST_API_EXCLUDE_PATHS=/auth*;/v1/* + DAST_API_EXCLUDE_PATHS: /auth*;/v1/* ``` To exclude one or more nested levels within a path we use `**`. In this example we are testing API endpoints. We are testing `/api/v1/` and `/api/v2/` of a data query requesting `mass`, `brightness` and `coordinates` data for `planet`, `moon`, `star`, and `satellite` objects. Example paths that could be scanned include, but are not limited to: @@ -1037,7 +1539,7 @@ In this example we test the `brightness` endpoint only: ```yaml variables: - DAST_API_EXCLUDE_PATHS=/api/**/mass;/api/**/coordinates + DAST_API_EXCLUDE_PATHS: /api/**/mass;/api/**/coordinates ``` ### Exclude parameters @@ -1297,7 +1799,15 @@ Each value in `DAST_API_EXCLUDE_URLS` is a regular expression. Characters such a The following example excludes the URL `http://target/api/auth` and its child resources. ```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + variables: + DAST_API_TARGET_URL: http://target/ + DAST_API_OPENAPI: test-api-specification.json DAST_API_EXCLUDE_URLS: http://target/api/auth ``` @@ -1306,7 +1816,15 @@ variables: To exclude the URLs `http://target/api/buy` and `http://target/api/sell` but allowing to scan their child resources, for instance: `http://target/api/buy/toy` or `http://target/api/sell/chair`. You could use the value `http://target/api/buy/$,http://target/api/sell/$`. This value is using two regular expressions, each of them separated by a `,` character. Hence, it contains `http://target/api/buy$` and `http://target/api/sell$`. In each regular expression, the trailing `$` character points out where the matching URL should end. ```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + variables: + DAST_API_TARGET_URL: http://target/ + DAST_API_OPENAPI: test-api-specification.json DAST_API_EXCLUDE_URLS: http://target/api/buy/$,http://target/api/sell/$ ``` @@ -1315,7 +1833,15 @@ variables: In order to exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: ```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + variables: + DAST_API_TARGET_URL: http://target/ + DAST_API_OPENAPI: test-api-specification.json DAST_API_EXCLUDE_URLS: http://target/api/buy,http://target/api/sell ``` @@ -1324,7 +1850,15 @@ variables: In order to exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. ```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + variables: + DAST_API_TARGET_URL: http://target/ + DAST_API_OPENAPI: test-api-specification.json DAST_API_EXCLUDE_URLS: https://target/api/v.*/user/create$ ``` @@ -1544,7 +2078,7 @@ The DAST API engine outputs an error message when it cannot establish a connecti **Error message** - In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/323939), `Failed to start scanner session (version header not found).` -- In GitLab 13.10 and earlier, `API Security version header not found. Are you sure that you are connecting to the API Security server?`. +- In GitLab 13.10 and earlier, `API Security version header not found. Are you sure that you are connecting to the DAST API server?`. **Solution** @@ -1568,12 +2102,15 @@ This solution is for pipelines in which the target API URL doesn't change (is st For environments where the target API remains the same, we recommend you specify the target URL by using the `DAST_API_TARGET_URL` environment variable. In your `.gitlab-ci.yml`, add a variable `DAST_API_TARGET_URL`. The variable must be set to the base URL of API testing target. For example: ```yaml +stages: + - dast + include: - - template: DAST-API.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml - variables: - DAST_API_TARGET_URL: http://test-deployment/ - DAST_API_OPENAPI: test-api-specification.json +variables: + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OPENAPI: test-api-specification.json ``` #### Dynamic environment solutions @@ -1603,7 +2140,7 @@ deploy-test-target: ### Use OpenAPI with an invalid schema -There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `DAST_API_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. +There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the DAST API is able to perform a relaxed validation by setting the variable `DAST_API_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. #### Edit a non-compliant OpenAPI file @@ -1620,25 +2157,25 @@ If your OpenAPI document is generated manually, load your document in the editor Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema. -API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `DAST_API_OPENAPI_RELAXED_VALIDATION` to any value, for example: +DAST API can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct DAST API to perform a relaxed validation, set the variable `DAST_API_OPENAPI_RELAXED_VALIDATION` to any value, for example: ```yaml - stages: - - dast +stages: + - dast - include: - - template: DAST-API.gitlab-ci.yml +include: + - template: DAST-API.gitlab-ci.yml - variables: - DAST_API_PROFILE: Quick - DAST_API_TARGET_URL: http://test-deployment/ - DAST_API_OPENAPI: test-api-specification.json - DAST_API_OPENAPI_RELAXED_VALIDATION: On +variables: + DAST_API_PROFILE: Quick + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OPENAPI: test-api-specification.json + DAST_API_OPENAPI_RELAXED_VALIDATION: 'On' ``` ### `No operation in the OpenAPI document is consuming any supported media type` -API Security uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. +DAST API uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. **Error message** diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index acbc94cba47..a59399f7e8d 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -32,14 +32,6 @@ The Dependency Scanning analyzers' current major version number is 2. Dependency Scanning is pre-configured with a set of **default images** that are maintained by GitLab, but users can also integrate their own **custom images**. -<!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> - -The [`bundler-audit`](https://gitlab.com/gitlab-org/gitlab/-/issues/289832) and [`retire.js`](https://gitlab.com/gitlab-org/gitlab/-/issues/350510) analyzers were deprecated -in GitLab 14.8 and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86704) in 15.0. -Use Gemnasium instead. - -<!--- end_remove --> - ## Official default analyzers Any custom change to the official analyzers can be achieved by using a diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 521bb6adbf0..7aabbdd3194 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -50,12 +50,12 @@ possible, we encourage you to use all of our security scanning tools: declared software dependencies (and those installed as a sub-dependency). Dependency Scanning can not detect software dependencies that are pre-bundled into the container's base image. To identify pre-bundled dependencies, enable - [Container Scanning](../container_scanning/) language scanning using the - [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/#report-language-specific-findings). -- [Container Scanning](../container_scanning/) analyzes your containers and tells + [Container Scanning](../container_scanning/index.md) language scanning using the + [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/index.md#report-language-specific-findings). +- [Container Scanning](../container_scanning/index.md) analyzes your containers and tells you about known risks in the operating system's (OS) packages. You can configure it to also report on software and language dependencies, if you enable it and use - the [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/#report-language-specific-findings). + the [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/index.md#report-language-specific-findings). Turning this variable on can result in some duplicate findings, as we do not yet de-duplicate results between Container Scanning and Dependency Scanning. For more details, efforts to de-duplicate these findings can be tracked in @@ -304,7 +304,7 @@ table.supported-languages ul { <li> <a id="notes-regarding-supported-languages-and-package-managers-3"></a> <p> - npm is only supported when `lockfileVersion = 1` or `lockfileVersion = 2`. Work to add support for `lockfileVersion = 3` is being tracked in issue <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">GitLab#365176</a>. + npm is only supported when <code>lockfileVersion = 1</code> or <code>lockfileVersion = 2</code>. Work to add support for <code>lockfileVersion = 3</code> is being tracked in issue <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">GitLab#365176</a>. </p> </li> <li> @@ -452,8 +452,8 @@ We only execute one build in the directory where a build file has been detected. multiple Gradle, Maven, or sbt builds, or any combination of these, `gemnasium-maven` only analyzes dependencies for the first build file that is detected. Build files are searched for in the following order: -1. `build.gradle` or `build.gradle.kts` for single or [multi-project](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) Gradle builds. 1. `pom.xml` for single or [multi-module](https://maven.apache.org/pom.html#Aggregation) Maven projects. +1. `build.gradle` or `build.gradle.kts` for single or [multi-project](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) Gradle builds. 1. `build.sbt` for single or [multi-project](https://www.scala-sbt.org/1.x/docs/Multi-Project.html) sbt builds. The search begins with the root directory and then continues with subdirectories if no builds are found in the root directory. Consequently an sbt build file in the root directory would be detected before a Gradle build file in a subdirectory. @@ -521,7 +521,7 @@ always take the latest dependency scanning artifact available. To enable Dependency Scanning in a project, you can create a merge request: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Dependency Scanning** row, select **Configure with a merge request**. 1. Review and merge the merge request to enable Dependency Scanning. @@ -627,7 +627,7 @@ The following variables are used for configuring specific analyzers (used for a The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they will work. This is a large list, many of which we may be unaware of, and as such is not documented. For example, to pass the non-GitLab environment variable `HTTPS_PROXY` to all Dependency Scanning jobs, -set it as a [custom CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) +set it as a [custom CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) file like this: ```yaml diff --git a/doc/user/application_security/generate_test_vulnerabilities/index.md b/doc/user/application_security/generate_test_vulnerabilities/index.md index aafbebb91cd..4d424acf9c3 100644 --- a/doc/user/application_security/generate_test_vulnerabilities/index.md +++ b/doc/user/application_security/generate_test_vulnerabilities/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Secure +stage: Govern group: Threat Insights 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 --- diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md index 4c2b971b5fa..ee7864b5ce9 100644 --- a/doc/user/application_security/get-started-security.md +++ b/doc/user/application_security/get-started-security.md @@ -6,25 +6,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Get started with GitLab application security **(ULTIMATE)** -Complete the following steps to get the most from GitLab application security tools. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Adopting GitLab application security](https://www.youtube.com/watch?v=5QlxkiKR04k). -1. Enable [Secret Detection](secret_detection/index.md) scanning for your default branch. -1. Enable [Dependency Scanning](dependency_scanning/index.md) for your default branch so you can start identifying existing +The following steps will help you get the most from GitLab application security tools. These steps are a recommended order of operations. You can choose to implement capabilities in a different order or omit features that do not apply to your specific needs. + +1. Enable [Secret Detection](secret_detection/index.md) and [Dependency Scanning](dependency_scanning/index.md) + to identify any leaked secrets and vulnerable packages in your codebase. + + - For all security scanners, enable them by updating your `[.gitlab-ci.yml](../../ci/yaml/gitlab_ci_yaml.md)` directly on your `default` branch. This creates a baseline scan of your `default` branch, which is necessary for + feature branch scans to be compared against. This allows [merge requests](../project/merge_requests/index.md) + to display only newly-introduced vulnerabilities. Otherwise, merge requests will display every + vulnerability in the branch, regardless of whether it was introduced by a change in the branch. + - If you are after simplicity, enable only Secret Detection first. It only has one analyzer, + no build requirements, and relatively simple findings: is this a secret or not? + - It is good practice to enable Dependency Scanning early so you can start identifying existing vulnerable packages in your codebase. -1. Add security scans to feature branch pipelines. The same scans should be enabled as are running - on your default branch. Subsequent scans will show only new vulnerabilities by comparing the feature branch to the default branch results. 1. Let your team get comfortable with [vulnerability reports](vulnerability_report/index.md) and establish a vulnerability triage workflow. 1. Consider creating [labels](../project/labels.md) and [issue boards](../project/issue_board.md) to help manage issues created from vulnerabilities. Issue boards allow all stakeholders to have a - common view of all issues. + common view of all issues and track remediation progress. +1. Use [scheduled pipelines](../../ci/pipelines/schedules.md#scheduled-pipelines) to regularly scan important branches such as `default` or those used for maintenance releases. + - Running regular dependency and [container scans](container_scanning/index.md) will surface newly-discovered vulnerabilities that already exist in your repository. + - Scheduled scans are most useful for projects or important branches with low development activity where pipeline scans are infrequent. 1. Create a [scan result policy](policies/index.md) to limit new vulnerabilities from being merged - into your default branch. + into your `default` branch. 1. Monitor the [Security Dashboard](security_dashboard/index.md) trends to gauge success in remediating existing vulnerabilities and preventing the introduction of new ones. 1. Enable other scan types such as [SAST](sast/index.md), [DAST](dast/index.md), [Fuzz testing](coverage_fuzzing/index.md), or [Container Scanning](container_scanning/index.md). - Be sure to add the same scan types to both feature pipelines and default branch pipelines. 1. Use [Compliance Pipelines](../../user/project/settings/index.md#compliance-pipeline-configuration) or [Scan Execution Policies](policies/scan-execution-policies.md) to enforce required scan types and ensure separation of duties between security and engineering. diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 16f08de738b..1b9cdb11ea3 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -116,7 +116,7 @@ that you can download and analyze. To enable IaC Scanning in a project, you can create a merge request: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure with a merge request**. 1. Review and merge the merge request to enable IaC Scanning. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 7c7d5380a24..fbd617351da 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -98,7 +98,7 @@ approach. ## Security scanning with Auto DevOps To enable all GitLab Security scanning tools, with default settings, enable -[Auto DevOps](../../topics/autodevops/): +[Auto DevOps](../../topics/autodevops/index.md): - [Auto SAST](../../topics/autodevops/stages.md#auto-sast) - [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) @@ -361,7 +361,7 @@ Learn more on overriding security jobs: - [Overriding SAST jobs](sast/index.md#overriding-sast-jobs). - [Overriding Dependency Scanning jobs](dependency_scanning/index.md#overriding-dependency-scanning-jobs). - [Overriding Container Scanning jobs](container_scanning/index.md#overriding-the-container-scanning-template). -- [Overriding Secret Detection jobs](secret_detection/index.md#customizing-settings). +- [Overriding Secret Detection jobs](secret_detection/index.md#configure-scan-settings). - [Overriding DAST jobs](dast/index.md#customize-dast-settings). - [Overriding License Compliance jobs](../compliance/license_compliance/index.md#overriding-the-template). @@ -397,15 +397,6 @@ Validation depends on the schema version declared in the security report artifac You can always find supported and deprecated schema versions in the [source code](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/parsers/security/validators/schema_validator.rb). -<!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> - -### Enable security report validation (removed) - - This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/354928) in GitLab 14.9 - and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85400) in GitLab 15.0. - - <!--- end_remove --> - ## Interact with findings and vulnerabilities You can interact with the results of the security scanning tools in several locations: @@ -414,7 +405,7 @@ You can interact with the results of the security scanning tools in several loca - [Project Security Dashboard](security_dashboard/index.md) - [Security pipeline tab](security_dashboard/index.md) - [Group Security Dashboard](security_dashboard/index.md) -- [Security Center](security_dashboard/#security-center) +- [Security Center](security_dashboard/index.md#security-center) - [Vulnerability Report](vulnerability_report/index.md) - [Vulnerability Pages](vulnerabilities/index.md) - [Dependency List](dependency_list/index.md) @@ -455,7 +446,7 @@ Security and compliance teams must ensure that security scans: GitLab provides two methods of accomplishing this, each with advantages and disadvantages. -- [Compliance framework pipelines](../project/settings/#compliance-pipeline-configuration) +- [Compliance framework pipelines](../project/settings/index.md#compliance-pipeline-configuration) are recommended when: - Scan execution enforcement is required for any scanner that uses a GitLab template, such as SAST IaC, DAST, Dependency Scanning, @@ -497,6 +488,11 @@ Feedback is welcome on our vision for [unifying the user experience for these tw --> ### Secure job failing with exit code 1 +WARNING: +Debug logging can be a serious security risk. The output may contain the content of +environment variables and other secrets available to the job. The output is uploaded +to the GitLab server and visible in job logs. + 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. @@ -534,6 +530,11 @@ Select **new pipeline** to run a new pipeline. ### Getting warning messages `… report.json: no matching files` +WARNING: +Debug logging can be a serious security risk. The output may contain the content of +environment variables and other secrets available to the job. The output is uploaded +to the GitLab server and visible in job logs. + This message is often followed by the [error `No files to upload`](../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload), and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Check the entire job log for such messages. If you don't find these messages, retry the failed job after diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 7aeb094093c..7344695886a 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -87,9 +87,9 @@ above. You can find more information at each of the pages below: - [Container scanning offline directions](../container_scanning/index.md#running-container-scanning-in-an-offline-environment) - [SAST offline directions](../sast/index.md#running-sast-in-an-offline-environment) -- [Secret Detection offline directions](../secret_detection/#running-secret-detection-in-an-offline-environment) +- [Secret Detection offline directions](../secret_detection/index.md#running-secret-detection-in-an-offline-environment) - [DAST offline directions](../dast/run_dast_offline.md#run-dast-in-an-offline-environment) -- [API Fuzzing offline directions](../api_fuzzing/#running-api-fuzzing-in-an-offline-environment) +- [API Fuzzing offline directions](../api_fuzzing/index.md#running-api-fuzzing-in-an-offline-environment) - [License Compliance offline directions](../../compliance/license_compliance/index.md#running-license-compliance-in-an-offline-environment) - [Dependency Scanning offline directions](../dependency_scanning/index.md#running-dependency-scanning-in-an-offline-environment) @@ -236,4 +236,4 @@ an offline environment. Note that these steps are specific to GitLab Secure with AutoDevOps. Using other stages with AutoDevOps may require other steps covered in the -[Auto DevOps documentation](../../../topics/autodevops/). +[Auto DevOps documentation](../../../topics/autodevops/index.md). diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 53f9c400259..9b86ef7316a 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -1,6 +1,6 @@ --- -stage: Protect -group: Container Security +stage: Govern +group: Security Policies 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 --- @@ -54,7 +54,7 @@ to select, edit, and unlink a security policy project. As a project owner, take the following steps to create or edit an association between your current project and a project that you would like to designate as the security policy project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main 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. @@ -78,7 +78,7 @@ policies for all available environments. You can check a policy's information (for example, description or enforcement status), and create and edit deployed policies: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Policies**.  @@ -89,7 +89,7 @@ status), and create and edit deployed policies: 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 top bar, select **Main 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. You can then select which type of policy to create. @@ -144,6 +144,6 @@ for more information on the product direction of security policies within GitLab When you create a new security policy or change an existing policy, a new branch is automatically created with the branch name following the pattern `update-policy-<timestamp>`. For example: `update-policy-1659094451`. -If you have group or instance push rules that do not allow branch name patterns that contain the text `update-policy-<timestamp>`, you will get an error that states `Branch name does not follow the pattern 'update-policy-<timestamp>'`. +If you have group or instance push rules that do not allow branch name patterns that contain the text `update-policy-<timestamp>`, you will get an error that states `Branch name does not follow the pattern 'update-policy-<timestamp>'`. The workaround is to amend your group or instance push rules to allow branches following the pattern `update-policy-` followed by an integer timestamp. diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index eb1f9a7c7b8..f2fc52a2de8 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -1,12 +1,13 @@ --- -stage: Protect -group: Container Security +stage: Govern +group: Security Policies 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 --- # Scan execution policies **(ULTIMATE)** -> Group-level security policies were [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `group_level_security_policies`. Enabled by default. +> - Group-level security policies were [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2. +> - Group-level security policies were [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4. Group, sub-group, or project owners can use scan execution policies to require that security scans run on a specified schedule or with the project (or multiple projects if the policy is defined at a group or sub-group level) pipeline. Required scans are injected into the CI pipeline as new jobs @@ -14,10 +15,10 @@ with a long, random job name. In the unlikely event of a job name collision, the any pre-existing job in the pipeline. If a policy is created at the group-level, it will apply to every child project or sub-group. A group-level policy cannot be edited from a child project or sub-group. -This feature has some overlap with [compliance framework pipelines](../../project/settings/#compliance-pipeline-configuration), +This feature has some overlap with [compliance framework pipelines](../../project/settings/index.md#compliance-pipeline-configuration), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on the similarities and differences between these features, see -[Enforce scan execution](../#enforce-scan-execution). +[Enforce scan execution](../index.md#enforce-scan-execution). NOTE: Policy jobs are created in the `test` stage of the pipeline. If you modify the default pipeline @@ -88,8 +89,7 @@ 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. <!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> | -| `clusters` (removed) | `object` | | This field was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/356465) in 15.0. The cluster where the given policy enforces 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 are scanned. <!--- end_remove --> | +| `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | GitLab supports the following types of CRON syntax for the `cadence` field: @@ -98,23 +98,6 @@ GitLab supports the following types of CRON syntax for the `cadence` field: It is possible that other elements of the CRON syntax will work in the cadence field, however, GitLab does not officially test or support them. -<!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> - -### `cluster` schema (removed) - -This schema was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/356465) in 15.0. - -Use this schema to define `clusters` objects in the [`schedule` rule type](#schedule-rule-type). - -| Field | Type | Possible values | Description | -|--------------|---------------------|--------------------------|-------------| -| `containers` | `array` of `string` | | The container name that is scanned (only the first value is currently supported). | -| `resources` | `array` of `string` | | The resource name that is scanned (only the first value is currently supported). | -| `namespaces` | `array` of `string` | | The namespace that is 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). | - -<!--- end_remove --> - ## `scan` action type This action executes the selected `scan` with additional parameters when conditions for at least one @@ -146,7 +129,7 @@ Note the following: - A container scanning and cluster image scanning scans configured for the `pipeline` rule type ignores the cluster defined in the `clusters` object. They use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. A cluster with a name provided in the `clusters` object must be created and configured for the project. -- The SAST scan uses the default template and runs in a [child pipeline](../../../ci/pipelines/parent_child_pipelines.md). +- The SAST scan uses the default template and runs in a [child pipeline](../../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines). ## Example security policies project diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 3eee4957e2f..78a97b36e92 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -1,6 +1,6 @@ --- -stage: Protect -group: Container Security +stage: Govern +group: Security Policies 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 --- diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index cbd64e278c8..ec8e8e6fd93 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. Static Application Security Testing (SAST) uses analyzers -to detect vulnerabilities in source code. Each analyzer is a wrapper around a [scanner](../terminology/#scanner), a third-party code analysis tool. +to detect vulnerabilities in source code. Each analyzer is a wrapper around a [scanner](../terminology/index.md#scanner), a third-party code analysis tool. The analyzers are published as Docker images that SAST uses to launch dedicated containers for each analysis. @@ -20,7 +20,7 @@ For each scanner, an analyzer: - Exposes its detection logic. - Handles its execution. -- Converts its output to a [standard format](../terminology/#secure-report-format). +- Converts its output to a [standard format](../terminology/index.md#secure-report-format). ## SAST analyzers @@ -77,7 +77,7 @@ You can choose to disable the other analyzers early and use Semgrep-based scanni - You'll enjoy significantly faster scanning, reduced CI minutes usage, and more customizable scanning rules. - However, vulnerabilities previously reported by language-specific analyzers will be reported again under certain conditions, including if you've dismissed the vulnerabilities before. The system behavior depends on: - whether you've excluded the Semgrep-based analyzer from running in the past. - - which analyzer first discovered the vulnerabilities shown in the project's [Vulnerability Report](../vulnerability_report/). + - which analyzer first discovered the vulnerabilities shown in the project's [Vulnerability Report](../vulnerability_report/index.md). ### Vulnerability translation @@ -103,7 +103,7 @@ You can choose to use Semgrep-based scanning instead of language-specific analyz We recommend taking this approach if any of these cases applies: -- You haven't used SAST before on a project, so you don't already have SAST vulnerabilities in your [Vulnerability Report](../vulnerability_report/). +- You haven't used SAST before on a project, so you don't already have SAST vulnerabilities in your [Vulnerability Report](../vulnerability_report/index.md). - You're having trouble configuring one of the analyzers whose coverage overlaps with Semgrep-based coverage. For example, you might have trouble setting up the SpotBugs-based analyzer to compile your code. - You've already seen and dismissed vulnerabilities created by ESLint, Gosec, or Flawfinder scanning, and you've kept the re-created vulnerabilities created by Semgrep. @@ -120,6 +120,36 @@ To switch to Semgrep-based scanning early, you can: 1. Merge the MR and wait for the default-branch pipeline to run. 1. Use the Vulnerability Report to dismiss the findings that are no longer detected by the language-specific analyzers. +#### Preview Semgrep-based scanning + +You can see how Semgrep-based scanning will work in your projects before the GitLab-managed Stable CI/CD template for SAST is updated. +We recommend that you test this change in a merge request but continue using the Stable template in your default branch pipeline configuration. + +In GitLab 15.3, we [activated a feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/362179) to migrate security findings on the default branch from other analyzers to Semgrep. +We plan to [plan to remove the deprecated analyzers](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) from the Stable CI/CD template in GitLab 15.4. + +To preview the upcoming changes to the CI/CD configuration: + +1. Open an MR to switch from the Stable CI/CD template, `SAST.gitlab-ci.yaml`, to [the Latest template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.latest.gitlab-ci.yml), `SAST.latest.gitlab-ci.yaml`. + - On GitLab.com, use the latest template directly: + + ```yaml + include: + template: 'SAST.latest.gitlab-ci.yaml' + ``` + + - On a Self-Managed instance, download the template from GitLab.com: + + ```yaml + include: + remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/2851f4d5/lib/gitlab/ci/templates/Jobs/SAST.latest.gitlab-ci.yml' + ``` + +1. Verify that scanning jobs succeed in the MR. You'll notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) +1. Close the MR. + +To learn more about Stable and Latest templates, see documentation on [CI/CD template versioning](../../../development/cicd/templates.md#versioning). + ## Customize analyzers Use [CI/CD variables](index.md#available-cicd-variables) diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index d4b0d5b972c..c9bfecffecc 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -78,16 +78,17 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu |------------------------------------------------|-----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| | .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | | .NET Framework<sup>1</sup> | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | +| .NET (all versions, C# only) | [Semgrep](https://semgrep.dev) | 15.4 | | Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | | C | [Semgrep](https://semgrep.dev) | 14.2 | | C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | | Go | [Gosec](https://github.com/securego/gosec) | 10.7 | | Go | [Semgrep](https://semgrep.dev) | 14.4 | -| Groovy<sup>2</sup> | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | +| Groovy<sup>2</sup> | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Maven, SBT) | | Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | | Java (any build system) | [Semgrep](https://semgrep.dev) | 14.10 | -| Java<sup>2</sup> | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | +| Java<sup>2</sup> | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (SBT) | | Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | | JavaScript | [Semgrep](https://semgrep.dev) | 13.10 | @@ -103,16 +104,16 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | React | [Semgrep](https://semgrep.dev) | 13.10 | | Ruby | [brakeman](https://brakemanscanner.org) | 13.9 | | Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | -| Scala<sup>2</sup> | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | +| Scala<sup>2</sup> | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | | TypeScript | [Semgrep](https://semgrep.dev) | 13.10 | -1. .NET 4 support is limited. The analyzer runs in a Linux container and does not have access to Windows-specific libraries or features. We currently plan to [migrate C# coverage to Semgrep-based scanning](https://gitlab.com/gitlab-org/gitlab/-/issues/347258) to make it easier to scan C# projects. -1. The SpotBugs-based analyzer supports [Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/). It can also be used with variants like the +1. .NET 4 support is limited. The analyzer runs in a Linux container and does not have access to Windows-specific libraries or features. Use the Semgrep-based scanner if you need .NET 4 support. +1. The SpotBugs-based analyzer supports [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/). It can also be used with variants like the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), [Grails](https://grails.org/), -and the [Maven wrapper](https://github.com/takari/maven-wrapper). +and the [Maven wrapper](https://github.com/takari/maven-wrapper). However, SpotBugs has [limitations](https://gitlab.com/gitlab-org/gitlab/-/issues/350801) when used against [Ant](https://ant.apache.org/)-based projects. We recommend using the Semgrep-based analyzer for Ant-based Java projects. ### Multi-project support @@ -242,7 +243,7 @@ successfully, and an error may occur. To enable and configure SAST with default settings: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance** > **Configuration**. 1. In the SAST section, select **Configure with a merge request**. 1. Review and merge the merge request to enable SAST. @@ -262,7 +263,7 @@ successfully, and an error may occur. To enable and configure SAST with customizations: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. If the project does not have a `.gitlab-ci.yml` file, select **Enable SAST** in the Static Application Security Testing (SAST) row, otherwise select **Configure SAST**. @@ -337,7 +338,7 @@ False positive detection is available in a subset of the [supported languages](# > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5144) in GitLab 14.2. Source code is volatile; as developers make changes, source code may move within files or between files. -Security analyzers may have already reported vulnerabilities that are being tracked in the [Vulnerability Report](../vulnerability_report/). +Security analyzers may have already reported vulnerabilities that are being tracked in the [Vulnerability Report](../vulnerability_report/index.md). These vulnerabilities are linked to specific problematic code fragments so that they can be found and fixed. If the code fragments are not tracked reliably as they move, vulnerability management is harder because the same vulnerability could be reported again. @@ -550,8 +551,8 @@ Some analyzers can be customized with CI/CD variables. | `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | | `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | | `COMPILE` | Gosec, SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced for `SpotBugs`](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) analyzer in GitLab 13.1 and [`Gosec`](https://gitlab.com/gitlab-org/gitlab/-/issues/330678) analyzer in GitLab 14.0. | -| `ANT_HOME` | SpotBugs | The `ANT_HOME` variable. | -| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | +| `ANT_HOME` | SpotBugs | The `ANT_HOME` variable. | +| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | | `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | | `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. | | `JAVA_PATH` | SpotBugs | Path to the `java` executable. | @@ -565,6 +566,22 @@ Some analyzers can be customized with CI/CD variables. | `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | | `SAST_DISABLE_BABEL` | NodeJsScan | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64025)** in GitLab 13.5 | | `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://r2c.dev/). Default: `true`. Introduced in GitLab 14.0 from the [confidential issue](../../project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab/-/issues/330565`. | +| `SAST_SCANNER_ALLOWED_CLI_OPTS` | Semgrep | CLI options (arguments with value, or flags) that are passed to the underlying security scanner when running scan operation. Only a limited set of [options](#security-scanner-configuration) are accepted. Separate a CLI option and its value using either a blank space or equals (`=`) character. For example: `name1 value1` or `name1=value1`. Multiple options must be separated by blank spaces. For example: `name1 value1 name2 value2`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368565) in GitLab 15.3. | + +#### Security scanner configuration + +SAST analyzers internally use OSS security scanners to perform the analysis. We set the recommended +configuration for the security scanner so that you need not to worry about tuning them. However, +there can be some rare cases where our default scanner configuration does not suit your +requirements. + +To allow some customization of scanner behavior, you can add a limited set of flags to the +underlying scanner. Specify the flags in the `SAST_SCANNER_ALLOWED_CLI_OPTS` CI/CD variable. These +flags are added to the scanner's CLI options. + +| Analyzer | CLI option | Description | +|------------------------------------------------------------------------------|--------------------|------------------------------------------------------------------------------| +| [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) | `--max-memory` | Sets the maximum system memory to use when running a rule on a single file. Measured in MB. | #### Custom CI/CD variables @@ -729,6 +746,31 @@ variables: SECURE_LOG_LEVEL: "debug" ``` +### Pipeline errors related to changes in the GitLab-managed CI/CD template + +The [GitLab-managed SAST CI/CD template](#configure-sast-manually) controls which [analyzer](analyzers.md) jobs run and how they're configured. While using the template, you might experience a job failure or other pipeline error. For example, you might: + +- See an error message like `'<your job>' needs 'spotbugs-sast' job, but 'spotbugs-sast' is not in any previous stage` when you view an affected pipeline. +- Experience another type of unexpected issue with your CI/CD pipeline configuration. + +If you're experiencing a job failure or seeing a SAST-related `yaml invalid` pipeline status, you can temporarily revert to an older version of the template so your pipelines keep working while you investigate the issue. To use an older version of the template, change the existing `include` statement in your CI/CD YAML file to refer to a specific template version, such as `v15.3.3-ee`: + +```yaml +include: + remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/v15.3.3-ee/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml' +``` + +If your GitLab instance has limited network connectivity, you can also download the file and host it elsewhere. + +We recommend that you only use this solution temporarily and that you return to [the standard template](#configure-sast-manually) as soon as possible. + +### Errors in a specific analyzer job + +GitLab SAST [analyzers](analyzers.md) are released as container images. +If you're seeing a new error that doesn't appear to be related to [the GitLab-managed SAST CI/CD template](#configure-sast-manually) or changes in your own project, you can try [pinning the affected analyzer to a specific older version](#pinning-to-minor-image-version). + +Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. + ### `Error response from daemon: error processing tar file: docker-tar: relocation error` This error occurs when the Docker version that runs the SAST job is `19.03.0`. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 93c32f998fa..fe029b26ce5 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -6,26 +6,42 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Secret Detection **(FREE)** -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) from GitLab Ultimate to GitLab Free in 13.3. - -A recurring problem when developing applications is that people may accidentally commit secrets to -their remote Git repositories. Secrets include keys, passwords, API tokens, and other sensitive +> - In GitLab 13.1, Secret Detection was split from the [SAST configuration](../sast/index.md#configuration) +> into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then +> Secret Detection is already enabled. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) from GitLab Ultimate to GitLab +> Free in 13.3. +> - [In GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/297269), Secret Detection jobs +> `secret_detection_default_branch` and `secret_detection` were consolidated into one job, +> `secret_detection`. + +People may accidentally commit secrets to +remote Git repositories. Secrets include keys, passwords, API tokens, and other sensitive information. Anyone with access to the repository could use the secrets for malicious purposes. -Secrets exposed in this way must be treated as compromised, and be replaced, which can be costly. -It's important to prevent secrets from being committed to a Git repository. +Exposed secrets are compromised and must be replaced, which can be costly. + +To help prevent secrets from being committed to a Git repository, you can use Secret Detection +to scan your repository for secrets. Scanning is language +and framework agnostic, but does not support scanning binary files. + +Secret Detection uses a specific analyzer containing the +[Gitleaks](https://github.com/zricethezav/gitleaks) tool to scan the repository for secrets, in a +`secret-detection` job. The results are saved as a +[Secret Detection report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssecret_detection) +that you can later download and analyze. Due to implementation limitations, we always take the +latest Secret Detection artifact available. + +GitLab SaaS supports post-processing hooks, so you can take action when a secret is found. For +more information, see [Post-processing and revocation](post_processing.md). -Secret Detection uses the [Gitleaks](https://github.com/zricethezav/gitleaks) tool to scan the -repository for secrets. All identified secrets are reported in the: +All identified secrets are reported in the: - Merge request widget - Pipelines' **Security** tab -- [Security Dashboard](../security_dashboard/) +- [Security Dashboard](../security_dashboard/index.md)  -WARNING: -Secret Detection does not support scanning binary files. - ## Detected secrets Secret Detection uses a [default ruleset](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) @@ -34,105 +50,57 @@ patterns using [custom rulesets](#custom-rulesets). If you want to contribute ru "well-identifiable" secrets, follow the steps detailed in the [community contributions guidelines](https://gitlab.com/gitlab-org/gitlab/-/issues/345453). -## Requirements - -To run Secret Detection jobs, by default, you need GitLab Runner with the -[`docker`](https://docs.gitlab.com/runner/executors/docker.html) or -[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. -If you're using the shared runners on GitLab.com, this is enabled by default. - -WARNING: -Our Secret Detection jobs expect a Linux/amd64 container type. Windows containers are not supported. - -WARNING: -If you use your own runners, make sure the Docker version installed -is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. - -### Making Secret Detection available to all GitLab tiers +## Features per tier -To make Secret Detection available to as many customers as possible, we have enabled it for all GitLab tiers. -However not all features are available on every tier. See the breakdown below for more details. +Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/). -#### Summary of features per tier +| Capability | In Free & Premium | In Ultimate | +|:---------------------------------------------------------------- |:-----------------------|:-----------------------| +| [Configure Secret Detection scanner](#enable-secret-detection) | **{check-circle}** Yes | **{check-circle}** Yes | +| [Customize Secret Detection settings](#configure-scan-settings) | **{check-circle}** Yes | **{check-circle}** Yes | +| Download [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** Yes | **{check-circle}** Yes | +| See new findings in the merge request widget | **{dotted-circle}** No | **{check-circle}** Yes | +| View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** No | **{check-circle}** Yes | +| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Customize Secret Detection rulesets](#custom-rulesets) | **{dotted-circle}** No | **{check-circle}** Yes | -Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), -as shown in the following table: +## Enable Secret Detection -| Capability | In Free & Premium | In Ultimate | -|:----------------------------------------------------------------|:--------------------|:-------------------| -| [Configure Secret Detection scanner](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize Secret Detection settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | -| Download [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | -| See new findings in the merge request widget | **{dotted-circle}** | **{check-circle}** | -| View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** | **{check-circle}** | -| [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Customize Secret Detection rulesets](#custom-rulesets) | **{dotted-circle}** | **{check-circle}** | +Prerequisites: -## Configuration +- GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or +[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the +shared runners on GitLab.com, this is enabled by default. +- If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See + [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) + for details. +- Linux/amd64 container type. Windows containers are not supported. +- GitLab CI/CD configuration (`.gitlab-ci.yml`) must include the `test` stage. -> - In GitLab 13.1, Secret Detection was split from the [SAST configuration](../sast#configuration) into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then Secret Detection is already enabled. -> - [In GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/297269), Secret Detection jobs `secret_detection_default_branch` and `secret_detection` were consolidated into one job, `secret_detection`. +To enable Secret Detection, either: -Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) -during the `secret-detection` job. It runs regardless of your app's programming language. +- Enable [Auto DevOps](../../../topics/autodevops/index.md), which includes [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection). -The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) checks. +- [Enable Secret Detection by including the template](#enable-secret-detection-by-including-the-template). -Note that the Secret Detection analyzer ignores Password-in-URL vulnerabilities if the password -begins with a dollar sign (`$`), as this likely indicates the password is an environment variable. -For example, `https://username:$password@example.com/path/to/repo` isn't detected, while -`https://username:password@example.com/path/to/repo` is. +- [Enable Secret Detection using a merge request](#enable-secret-detection-using-a-merge-request). -NOTE: -You don't have to configure Secret Detection manually as shown in this section if you're using -[Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection), -provided by [Auto DevOps](../../../topics/autodevops/index.md). +### Enable Secret Detection by including the template -To enable Secret Detection for GitLab 13.1 and later, you must include the -`Secret-Detection.gitlab-ci.yml` template that's provided as a part of your GitLab installation. For -GitLab versions earlier than 11.9, you can copy and use the job as defined in that template. +We recommend this method if you have an existing GitLab CI/CD configuration file. -Ensure your `.gitlab-ci.yml` file has a `stage` called `test`, and add the following to your `.gitlab-ci.yml` file: +Add the following extract to your `.gitlab-ci.yml` file: ```yaml include: - template: Security/Secret-Detection.gitlab-ci.yml ``` -The included template creates Secret Detection jobs in your CI/CD pipeline and scans -your project's source code for secrets. - -The results are saved as a -[Secret Detection report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssecret_detection) -that you can later download and analyze. Due to implementation limitations, we -always take the latest Secret Detection artifact available. - -### Supported distributions - -The default scanner images are build off a base Alpine image for size and maintainability. - -#### FIPS-enabled images - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10. - -GitLab offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) -versions of the images that are FIPS-enabled. To use the FIPS-enabled images, you can either: - -- Set the `SAST_IMAGE_SUFFIX` to `-fips`. -- Add the `-fips` extension to the default image name. - -For example: - -```yaml -variables: - SECRET_DETECTION_IMAGE_SUFFIX: '-fips' - -include: - - template: Security/Secret-Detection.gitlab-ci.yml -``` +Pipelines now include a Secret Detection job, and the results are included in the merge request +widget. -### Enable Secret Detection via an automatic merge request +### Enable Secret Detection using a merge request > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, deployed behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329886) in GitLab 14.1. @@ -142,45 +110,36 @@ This method works best with no existing `.gitlab-ci.yml` file, or with a minimal file. If you have a complex GitLab configuration file it may not be parsed successfully, and an error may occur. -To enable Secret Detection in a project, you can create a merge request: +To enable Secret Detection using a merge request: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. In the **Secret Detection** row, select **Configure with a merge request**. -1. Review and merge the merge request to enable Secret Detection. +1. Review and merge the merge request. -Pipelines now include a Secret Detection job. +Pipelines now include a Secret Detection job, and the results are included in the merge request +widget. -### Customizing settings +## Configure scan settings The Secret Detection scan settings can be changed through [CI/CD variables](#available-cicd-variables) -by using the -[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. +by using the [`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. WARNING: -All customization of GitLab security scanning tools should be tested in a merge request before +All configuration of GitLab security scanning tools should be tested in a merge request before merging these changes to the default branch. Failure to do so can give unexpected results, including a large number of false positives. To override a job definition, (for example, change properties like `variables` or `dependencies`), -declare a job with the same name as the secret detection job to override. Place this new job after the template -inclusion and specify any additional keys under it. - -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. +declare a job with the same name as the secret detection job to override. Place this new job after +the template inclusion and specify any additional keys under it. -#### `GIT_DEPTH` variable +In the following example _extract_ of a `.gitlab-ci.yml` file: -The [`GIT_DEPTH` CI/CD variable](../../../ci/runners/configure_runners.md#shallow-cloning) affects Secret Detection. -The Secret Detection analyzer relies on generating patches between commits to scan content for -secrets. If you override the default, ensure the value is greater than 1. If the number of commits -in an MR is greater than the `GIT_DEPTH` value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). - -#### Custom settings example - -In the following example, we include the Secret Detection template and at the same time we -override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` CI/CD variable to `true`: +- The Secret Detection template is [included](../../../ci/yaml/index.md#include). +- In the `secret_detection` job, the CI/CD variable `SECRET_DETECTION_HISTORIC_SCAN` is set to + `true`. Because the template is evaluated before the pipeline configuration, the last mention of + the variable takes precedence. ```yaml include: @@ -191,10 +150,7 @@ secret_detection: SECRET_DETECTION_HISTORIC_SCAN: "true" ``` -Because the template is [evaluated before](../../../ci/yaml/index.md#include) -the pipeline configuration, the last mention of the variable takes precedence. - -#### Available CI/CD variables +### Available CI/CD variables Secret Detection can be customized by defining available CI/CD variables: @@ -202,7 +158,7 @@ Secret Detection can be customized by defining available CI/CD variables: |-----------------------------------|---------------|-------------| | `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | -| `SECRET_DETECTION_IMAGE_SUFFIX` | "" | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355519) in GitLab 14.10. | +| `SECRET_DETECTION_IMAGE_SUFFIX` | "" | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [Use FIPS-enabled images](#use-fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355519) in GitLab 14.10. | | `SECRET_DETECTION_LOG_OPTIONS` | "" | [`git log`](https://git-scm.com/docs/git-log) options used to define commit ranges. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350660) in GitLab 15.1.| In previous GitLab versions, the following variables were also available: @@ -211,45 +167,79 @@ In previous GitLab versions, the following variables were also available: |-----------------------------------|---------------|-------------| | `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/243564) in GitLab 13.5. Replaced with `SECRET_DETECTION_COMMITS`. | | `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/243564) in GitLab 13.5. Replaced with `SECRET_DETECTION_COMMITS`. | -| `SECRET_DETECTION_COMMITS` | - | The list of commits that Gitleaks should scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243564) in GitLab 13.5. [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/352565) in GitLab 15.0. | +| `SECRET_DETECTION_COMMITS` | - | The list of commits that Gitleaks should scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243564) in GitLab 13.5. [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/352565) in GitLab 15.0. | -### Custom rulesets **(ULTIMATE)** +#### Use FIPS-enabled images -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for -> passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6479) in GitLab 14.10. -You can customize the default secret detection rules provided with GitLab. -Ruleset customization supports the following capabilities that can be used -simultaneously: +The default scanner images are built off a base Alpine image for size and maintainability. GitLab +offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) +versions of the images that are FIPS-enabled. -- [Disabling predefined rules](#disable-predefined-analyzer-rules). -- [Overriding predefined rules](#override-predefined-analyzer-rules). -- Modifying the default behavior of the Secret Detection analyzer by [synthesizing and passing a custom configuration](#synthesize-a-custom-configuration). +To use the FIPS-enabled images, either: -Customization allows replacing the default secret detection rules with rules that you define. +- Set the `SECRET_DETECTION_IMAGE_SUFFIX` CI/CD variable to `-fips`. +- Add the `-fips` extension to the default image name. -To create a custom ruleset: +For example: -1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. -1. Create a custom ruleset file named `secret-detection-ruleset.toml` in the `.gitlab` directory. +```yaml +variables: + SECRET_DETECTION_IMAGE_SUFFIX: '-fips' -#### Disable predefined analyzer rules +include: + - template: Security/Secret-Detection.gitlab-ci.yml +``` -To disable analyzer rules: +## Full history Secret Detection -1. Set the `disabled` flag to `true` in the context of a `ruleset` section. +By default, Secret Detection scans only the current state of the Git repository. Any secrets +contained in the repository's history are not detected. To address this, Secret Detection can +scan the Git repository's full history. + +We recommend you do a full history scan only once, after enabling Secret Detection. A full history +can take a long time, especially for larger repositories with lengthy Git histories. After +completing an initial full history scan, use only standard Secret Detection as part of your +pipeline. + +### Enable full history Secret Detection + +To enable full history Secret Detection, set the variable `SECRET_DETECTION_HISTORIC_SCAN` to `true` in your `.gitlab-ci.yml` file. + +## Custom rulesets **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for passthrough chains. +> Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in +> GitLab 14.8. + +You can customize the default Secret Detection rules provided with GitLab. -1. In one or more `ruleset.identifier` subsections, list the rules that you want disabled. Every `ruleset.identifier` section has: +The following customization options can be used separately, or in combination: - - a `type` field, to name the predefined rule identifier. - - a `value` field, to name the rule to be disabled. +- [Disable predefined rules](#disable-predefined-analyzer-rules). +- [Override predefined rules](#override-predefined-analyzer-rules). +- [Synthesize a custom configuration](#synthesize-a-custom-configuration). -##### Example: Disable predefined rules of Secret Detection analyzer +### Disable predefined analyzer rules -In the following example, the disabled rules is assigned to `secrets` -by matching the `type` and `value` of identifiers: +If there are specific Secret Detection rules that you don't want active, you can disable them. + +To disable analyzer rules: + +1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. +1. Create a custom ruleset file named `secret-detection-ruleset.toml` in the `.gitlab` directory, if + one doesn't already exist. +1. Set the `disabled` flag to `true` in the context of a `ruleset` section. +1. In one or more `ruleset.identifier` subsections, list the rules to disable. Every + `ruleset.identifier` section has: + - A `type` field for the predefined rule identifier. + - A `value` field for the rule name. + +In the following example `secret-detection-ruleset.toml` file, the disabled rules are assigned to +`secrets` by matching the `type` and `value` of identifiers: ```toml [secrets] @@ -260,29 +250,30 @@ by matching the `type` and `value` of identifiers: value = "RSA private key" ``` -#### Override predefined analyzer rules +### Override predefined analyzer rules -To override rules: - -1. In one or more `ruleset.identifier` subsections, list the rules that you want to override. Every `ruleset.identifier` section has: +If there are specific Secret Detection rules you want to customize, you can override them. For +example, you might increase the severity of specific secrets. - - a `type` field, to name the predefined rule identifier that the Secret Detection analyzer uses. - - a `value` field, to name the rule to be overridden. +To override rules: +1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. +1. Create a custom ruleset file named `secret-detection-ruleset.toml` in the `.gitlab` directory, if + one doesn't already exist. +1. In one or more `ruleset.identifier` subsections, list the rules to override. Every + `ruleset.identifier` section has: + - A `type` field for the predefined rule identifier. + - A `value` field for the rule name. 1. In the `ruleset.override` context of a `ruleset` section, provide the keys to override. Any combination of keys can be overridden. Valid keys are: - - description - message - name - severity (valid options are: Critical, High, Medium, Low, Unknown, Info) -##### Example: Override predefined rules of Secret Detection analyzer - -In the following example, rules -are matched by the `type` and `value` of identifiers and -then overridden: +In the following example `secret-detection-ruleset.toml` file, rules are matched by the `type` and +`value` of identifiers and then overridden: ```toml [secrets] @@ -297,166 +288,157 @@ then overridden: severity = "Info" ``` -#### Synthesize a custom configuration +### Synthesize a custom configuration -To create a custom configuration, you can use passthrough chains. +To create a custom configuration, you can use passthrough chains. Passthroughs can also be chained +to build more complex configurations. For more details, see +[SAST Customize ruleset](../sast/customize_rulesets.md). -1. In the `secret-detection-ruleset.toml` file, do one of the following: +In the `secret-detection-ruleset.toml` file, do one of the following: - - Define a custom ruleset: +- Define a custom ruleset, for example: - ```toml - [secrets] - description = 'secrets custom rules configuration' + ```toml + [secrets] + description = 'secrets custom rules configuration' - [[secrets.passthrough]] - type = "raw" - target = "gitleaks.toml" - value = """\ - title = "gitleaks config" - # add regexes to the regex table - [[rules]] - description = "Test for Raw Custom Rulesets" - regex = '''Custom Raw Ruleset T[est]{3}''' - """ - ``` + [[secrets.passthrough]] + type = "raw" + target = "gitleaks.toml" + value = """\ + title = "gitleaks config" + # add regexes to the regex table + [[rules]] + description = "Test for Raw Custom Rulesets" + regex = '''Custom Raw Ruleset T[est]{3}''' + """ + ``` - - Provide the name of the file containing a custom ruleset: +- Provide the name of the file containing a custom ruleset, for example: - ```toml - [secrets] - description = 'secrets custom rules configuration' + ```toml + [secrets] + description = 'secrets custom rules configuration' - [[secrets.passthrough]] - type = "file" - target = "gitleaks.toml" - value = "config/gitleaks.toml" - ``` + [[secrets.passthrough]] + type = "file" + target = "gitleaks.toml" + value = "config/gitleaks.toml" + ``` -Passthroughs can also be chained to build more complex configurations. -For more details, see [SAST Customize ruleset section](../sast/customize_rulesets.md). +## Running Secret Detection in an offline environment **(PREMIUM SELF)** -### Logging level - -To control the verbosity of logs set the `SECURE_LOG_LEVEL` CI/CD variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. - -From highest to lowest severity, the logging levels are: - -- `fatal` -- `error` -- `warn` -- `info` (default) -- `debug` - -## Post-processing and revocation +For self-managed GitLab instances in an environment with limited, restricted, or intermittent access +to external resources through the internet, some configuration changes are required for the Secret +Detection job to run successfully. The instructions in this section must be completed together with +the instructions detailed in [offline environments](../offline_deployments/index.md). -Upon detection of a secret, GitLab SaaS supports post-processing hooks. -For more information, see [Post-processing and revocation](post_processing.md). +### Configure GitLab Runner -## Full History Secret Detection +By default, a runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. We recommend using this default setting, to ensure Docker images remain current. +However, if no network connectivity is available, you must change the default GitLab Runner +`pull_policy` variable. -GitLab 12.11 introduced support for scanning the full history of a repository. This new functionality -is particularly useful when you are enabling Secret Detection in a repository for the first time and you -want to perform a full secret detection scan. Running a secret detection scan on the full history can take a long time, -especially for larger repositories with lengthy Git histories. We recommend not setting this CI/CD variable -as part of your normal job definition. +Configure the GitLab Runner CI/CD variable `pull_policy` to +[`if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy). -A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-cicd-variables)) -can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository. +### Use local Secret Detection analyzer image -## Running Secret Detection in an offline environment +Use a local Secret Detection analyzer image if you want to obtain the image from a local Docker +registry instead of the GitLab container registry. -For self-managed GitLab instances in an environment with limited, restricted, or intermittent access -to external resources through the internet, some adjustments are required for the Secret Detection job to -run successfully. For more information, see [Offline environments](../offline_deployments/index.md). +Prerequisites: -### Requirements for offline Secret Detection +- Importing Docker images into a local offline Docker registry depends on your + network security policy. Consult your IT staff to find an accepted and approved process + to import or temporarily access external resources. -To use Secret Detection in an offline environment, you need: +1. Import the default Secret Detection analyzer image from `registry.gitlab.com` into your + [local Docker container registry](../../packages/container_registry/index.md): -- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). -- A Docker Container Registry with locally available copy of Secret Detection [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. -- Configure certificate checking of packages (optional). + ```plaintext + registry.gitlab.com/security-products/secret-detection:3 + ``` -GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) -in an offline environment if you prefer using only locally available Docker images. However, we -recommend keeping the pull policy setting to `always` if not in an offline environment, as this -enables the use of updated scanners in your CI/CD pipelines. + The Secret Detection analyzer's image is [periodically updated](../index.md#vulnerability-scanner-maintenance) + so you may need to periodically update the local copy. -### Make GitLab Secret Detection analyzer image available inside your Docker registry +1. Set the CI/CD variable `SECURE_ANALYZERS_PREFIX` to the local Docker container registry. -Import the following default Secret Detection analyzer images from `registry.gitlab.com` into your -[local Docker container registry](../../packages/container_registry/index.md): + ```yaml + include: + - template: Security/Secret-Detection.gitlab-ci.yml -```plaintext -registry.gitlab.com/security-products/secret-detection:3 -``` + variables: + SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" + ``` -The process for importing Docker images into a local offline Docker registry depends on -**your network security policy**. Please consult your IT staff to find an accepted and approved -process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance) -with new definitions, and you may be able to make occasional updates on your own. +The Secret Detection job should now use the local copy of the Secret Detection analyzer Docker +image, without requiring internet access. -For details on saving and transporting Docker images as a file, see Docker's documentation on -[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), -[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). +### Configure a custom Certificate Authority -### Set Secret Detection CI/CD variables to use the local Secret Detection analyzer container image +To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle +of CA certificates that you trust. Do this either in the `.gitlab-ci.yml` file, in a file +variable, or as a CI/CD variable. -Add the following configuration to your `.gitlab-ci.yml` file. You must replace -`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: +- In the `.gitlab-ci.yml` file, the `ADDITIONAL_CA_CERT_BUNDLE` value must contain the + [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). -```yaml -include: - - template: Security/Secret-Detection.gitlab-ci.yml + For example: -variables: - SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" -``` + ```yaml + variables: + ADDITIONAL_CA_CERT_BUNDLE: | + -----BEGIN CERTIFICATE----- + MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB + ... + jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= + -----END CERTIFICATE----- + ``` -The Secret Detection job should now use the local copy of the Secret Detection analyzer Docker image to scan your code and generate -security reports without requiring internet access. +- If using a file variable, set the value of `ADDITIONAL_CA_CERT_BUNDLE` to the path to the + certificate. -#### If support for Custom Certificate Authorities are needed +- If using a variable, set the value of `ADDITIONAL_CA_CERT_BUNDLE` to the text + representation of the certificate. -Support for custom certificate authorities was introduced in the following versions. +## Troubleshooting -| Analyzer | Version | -| -------- | ------- | -| secrets | [v3.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/releases/v3.0.0) | +### Set the logging level -To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle -of CA certs that you want to trust in the SAST environment. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. -```yaml -variables: - ADDITIONAL_CA_CERT_BUNDLE: | - -----BEGIN CERTIFICATE----- - MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB - ... - jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= - -----END CERTIFICATE----- -``` +Set the logging level to `debug` when you need diagnostic information in a Secret Detection job log. -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +WARNING: +Debug logging can be a serious security risk. The output may contain the content of environment +variables and other secrets available to the job. The output is uploaded to the GitLab server and +visible in job logs. -## Troubleshooting +1. In the `.gitlab-ci.yml` file, set the `SECURE_LOG_LEVEL` CI/CD variable to `debug`. +1. Run the Secret Detection job. +1. Analyze the content of the Secret Detection job. +1. In the `.gitlab-ci.yml` file, set the `SECURE_LOG_LEVEL` CI/CD variable to `info` (default). -### Getting warning message `gl-secret-detection-report.json: no matching files` +### Warning: `gl-secret-detection-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). ### Error: `Couldn't run the gitleaks command: exit status 2` -If a pipeline is triggered from a merge request containing 60 commits while the `GIT_DEPTH` variable's -value is less than that, the Secret Detection job fails as the clone is not deep enough to contain all of the -relevant commits. For information on the current default value, see the -[pipeline configuration documentation](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone). +The Secret Detection analyzer relies on generating patches between commits to scan content for +secrets. If the number of commits in a merge request is greater than the value of the +[`GIT_DEPTH` CI/CD variable](../../../ci/runners/configure_runners.md#shallow-cloning), Secret +Detection [fails to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). + +For example, if a pipeline is triggered from a merge request containing 60 commits and the +`GIT_DEPTH` variable's value is less than 60, the Secret Detection job fails as the clone is not +deep enough to contain all of the relevant commits. To veridy the current value, see +[pipeline configuration](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone). -To confirm this as the cause of the error, set the -[logging level](../../application_security/secret_detection/index.md#logging-level) to `debug`, then +To confirm this as the cause of the error, set the [logging level](#set-the-logging-level) to `debug`, then rerun the pipeline. The logs should look similar to the following example. The text "object not found" is a symptom of this error. @@ -476,11 +458,12 @@ secret_detection: GIT_DEPTH: 100 ``` -### `secret-detection` job fails with `ERR fatal: ambiguous argument` message +### Error: `ERR fatal: ambiguous argument` -Your `secret-detection` job can fail with `ERR fatal: ambiguous argument` error if your -repository's default branch is unrelated to the branch the job was triggered for. -See issue [!352014](https://gitlab.com/gitlab-org/gitlab/-/issues/352014) for more details. +Secret Detection can fail with the message `ERR fatal: ambiguous argument` error if your +repository's default branch is unrelated to the branch the job was triggered for. See issue +[!352014](https://gitlab.com/gitlab-org/gitlab/-/issues/352014) for more details. -To resolve the issue, make sure to correctly [set your default branch](../../project/repository/branches/default.md#change-the-default-branch-name-for-a-project) on your repository. You should set it to a branch -that has related history with the branch you run the `secret-detection` job on. +To resolve the issue, make sure to correctly [set your default branch](../../project/repository/branches/default.md#change-the-default-branch-name-for-a-project) +on your repository. You should set it to a branch that has related history with the branch you run +the `secret-detection` job on. diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index f3c834e06c7..967e8da58a9 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Secure +stage: Govern group: Threat Insights 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 --- @@ -49,12 +49,15 @@ To reduce false negatives in [dependency scans](../../../user/application_securi > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualize data between given dates. The project Security Dashboard shows the total number of vulnerabilities -over time, with up to 365 days of historical data. Data refreshes daily at 01:15 UTC. -It shows statistics for all vulnerabilities. +over time, with up to 365 days of historical data. Data refresh begins daily at 01:15 UTC via a scheduled job. +Each refresh captures a snapshot of open vulnerabilities. Data is not backported to prior days +so vulnerabilities opened after the job has already run for the day will not be reflected in the +counts until the following day's refresh job. +Project Security Dashboards show statistics for all vulnerabilities with a current status of `Needs triage` or `Confirmed` . To view total number of vulnerabilities over time: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Security Dashboard**. 1. Filter and search for what you need. - To filter the chart by severity, select the legend name. @@ -67,7 +70,7 @@ To view total number of vulnerabilities over time: To download an SVG image of the vulnerabilities chart: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Security dashboard**. 1. Select **Save chart as an image** (**{download}**). @@ -78,7 +81,7 @@ branches of projects in a group and its subgroups. To view vulnerabilities over time for a group: -1. On the top bar, select **Menu > Groups** and select a group. +1. On the top bar, select **Main menu > Groups** and select a group. 1. Select **Security > Security Dashboard**. 1. Hover over the chart to get more details about vulnerabilities. - You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). @@ -88,15 +91,16 @@ To view vulnerabilities over time for a group: ## View project security status for a group -Use the group Security Dashboard to view the security status of projects. The security status is based -on the number of detected vulnerabilities. +Use the group Security Dashboard to view the security status of projects. To view project security status for a group: -1. On the top bar, select **Menu > Groups** and select a group. +1. On the top bar, select **Main menu > Groups** and select a group. 1. Select **Security > Security Dashboard**. -Projects are [graded](#project-vulnerability-grades) by vulnerability severity. Dismissed vulnerabilities are excluded. +Each project is assigned a letter [grade](#project-vulnerability-grades) according to the highest-severity open vulnerability. +Dismissed or resolved vulnerabilities are excluded. Each project can receive only one letter grade and will appear only once +in the Project security status report. To view vulnerabilities, go to the group's [vulnerability report](../vulnerability_report/index.md). @@ -127,13 +131,13 @@ The Security Center includes: ### View the Security Center -To view the Security Center, on the top bar, select **Menu > Security**. +To view the Security Center, on the top bar, select **Main menu > Security**. ### Add projects to the Security Center To add projects to the Security Center: -1. On the top bar, select **Menu > Security**. +1. On the top bar, select **Main menu > Security**. 1. On the left sidebar, select **Settings**, or select **Add projects**. 1. Use the **Search your projects** text box to search for and select projects. 1. Select **Add projects**. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index ad397c3fe04..91793272cce 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -1,5 +1,5 @@ --- -stage: Secure +stage: Govern group: Threat Insights 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 --- @@ -46,14 +46,14 @@ are reintroduced and detected by subsequent scans have a _new_ vulnerability rec 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 is reported again as a new record. You can use the Vulnerability Report's -[Activity filter](../vulnerability_report/#activity-filter) to select all vulnerabilities that are +[Activity filter](../vulnerability_report/index.md#activity-filter) to select all vulnerabilities that are no longer detected, and change their status. ## Change status of a vulnerability To change a vulnerability's status from its Vulnerability Page: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Status** dropdown list select a status, then select **Change status**. @@ -77,7 +77,7 @@ that when Jira integration is enabled, the GitLab issue feature is not available To create a GitLab issue for a vulnerability: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability report**. 1. Select the vulnerability's description. 1. Select **Create issue**. @@ -99,7 +99,7 @@ Prerequisites: To create a Jira issue for a vulnerability: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability report**. 1. Select the vulnerability's description. 1. Select **Create Jira issue**. @@ -132,7 +132,7 @@ Be aware of the following conditions between a vulnerability and a linked issue: To link a vulnerability to existing issues: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability report**. 1. Select the vulnerability's description. 1. In the **Linked issues** section, select the plus icon (**{plus}**). @@ -167,7 +167,7 @@ To resolve a vulnerability, you can either: To resolve the vulnerability with a merge request: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Resolve with merge request** dropdown list, select **Resolve with merge request**. @@ -179,7 +179,7 @@ Process the merge request according to your standard workflow. To manually apply the patch that GitLab generated for a vulnerability: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Resolve with merge request** dropdown list, select **Download patch to resolve**. @@ -197,7 +197,7 @@ Security training helps your developers learn how to fix vulnerabilities. Develo To enable security training for vulnerabilities in your project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Configuration**. 1. On the tab bar, select **Vulnerability Management**. 1. To enable a security training provider, turn on the toggle. @@ -215,7 +215,7 @@ Vulnerabilities with a CWE are most likely to return a training result. To view the security training for a vulnerability: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability report**. 1. Select the vulnerability for which you want to view security training. 1. Select **View training**. diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index 987dac677e7..aed86cd93aa 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -1,6 +1,6 @@ --- type: reference -stage: Secure +stage: Govern group: Threat Insights 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 --- diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 15a287356f8..ba448d410ea 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Secure +stage: Govern group: Threat Insights 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 --- @@ -44,7 +44,7 @@ At the project level, the Vulnerability Report also contains: To view the project-level vulnerability report: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability report**. ## Vulnerability Report actions @@ -57,6 +57,7 @@ From the Vulnerability Report you can: - [View an issue raised for a vulnerability](#view-issues-raised-for-a-vulnerability). - [Change the status of vulnerabilities](#change-status-of-vulnerabilities). - [Export details of vulnerabilities](#export-vulnerability-details). +- [Sort vulnerabilities by date](#sort-vulnerabilities-by-date-detected). - [Manually add a vulnerability finding](#manually-add-a-vulnerability-finding). ## Vulnerability Report filters @@ -186,6 +187,12 @@ Vulnerability records cannot be deleted, so a permanent record always remains. If a vulnerability is dismissed in error, reverse the dismissal by changing its status. +## Sort vulnerabilities by date detected + +By default, vulnerabilities are sorted by severity level, with the highest-severity vulnerabilities listed at the top. + +To sort vulnerabilities by the date each vulnerability was detected, click the "Detected" column header. + ## 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 13.0. @@ -247,7 +254,7 @@ To undo this action, select a different status from the same menu. To add a new vulnerability finding from your project level Vulnerability Report page: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability Report**. 1. Select **Submit Vulnerability**. 1. Complete the fields and submit the form. diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index 32916f4c9c7..7faf273515c 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Secure +stage: Govern group: Threat Insights 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 --- @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w To view vulnerabilities in a pipeline: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **CI/CD > Pipelines**. 1. From the list, select the pipeline you want to check for vulnerabilities. 1. Select the **Security** tab. @@ -26,7 +26,7 @@ For example, if a pipeline contains DAST and SAST jobs, but the DAST job fails b The pipeline vulnerability report only shows results contained in the security report artifacts. This report differs from the [Vulnerability Report](index.md), which contains cumulative results of all successful jobs, and from the merge request -[security widget](../#view-security-scan-information-in-merge-requests), which combines the branch results with +[security widget](../index.md#view-security-scan-information-in-merge-requests), which combines the branch results with cumulative results. Before GitLab displays results, the vulnerability findings in all pipeline reports are [deduplicated](#deduplication-process). @@ -35,7 +35,7 @@ Before GitLab displays results, the vulnerability findings in all pipeline repor **Scan details** shows a summary of vulnerability findings in the pipeline and the source reports. -GitLab displays one row of information for each [scan type](../terminology/#scan-type-report-type) artifact present in +GitLab displays one row of information for each [scan type](../terminology/index.md#scan-type-report-type) artifact present in the pipeline. Note that each scan type's total number of vulnerabilities includes dismissed findings. If the number of findings @@ -83,11 +83,11 @@ incorporated once the pipeline finishes. When a pipeline contains jobs that produce multiple security reports of the same type, it is possible that the same vulnerability finding is present in multiple reports. This duplication is common when different scanners are used to -increase coverage. The deduplication process allows you to maximize the vulnerability scanning coverage while reducing +increase coverage, but can also exist within a single report. The deduplication process allows you to maximize the vulnerability scanning coverage while reducing the number of findings you need to manage. -A finding is considered a duplicate of another finding when their [scan type](../terminology/#scan-type-report-type), -[location](../terminology/#location-fingerprint) and +A finding is considered a duplicate of another finding when their [scan type](../terminology/index.md#scan-type-report-type), +[location](../terminology/index.md#location-fingerprint), and one or more of its [identifiers](../../../development/integrations/secure.md#identifiers) are the same. The scan type must match because each can have its own definition for the location of a vulnerability. For example, @@ -95,8 +95,9 @@ static analyzers are able to locate a file path and line number, whereas a conta name instead. When comparing identifiers, GitLab does not compare `CWE` and `WASC` during deduplication because they are -"type identifiers" and are used to classify groups of vulnerabilities. Including these identifiers results in -many findings being incorrectly considered duplicates. +"type identifiers" and are used to classify groups of vulnerabilities. Including these identifiers would result in +many findings being incorrectly considered duplicates. Two findings are considered unique if none of their +identifiers match. In a set of duplicated findings, the first occurrence of a finding is kept and the remaining are skipped. Security reports are processed in alphabetical file path order, and findings are processed sequentially in the order they @@ -124,16 +125,17 @@ appear in a report. - Location fingerprint: `adc83b19e793491b1c6ea0fd8b46cd9f32e592fc` - Identifiers: CWE-798 - Deduplication result: duplicates because `CWE` identifiers are ignored. -- Example 3: matching scan type, location and identifiers. +- Example 3: matching scan type, location and an identifier. - Finding - Scan type: `container_scanning` - Location fingerprint: `adc83b19e793491b1c6ea0fd8b46cd9f32e592fc` - - Identifiers: CVE-2022-25510, CWE-259 + - Identifiers: CVE-2019-12345, CVE-2022-25510, CWE-259 - Other Finding - Scan type: `container_scanning` - Location fingerprint: `adc83b19e793491b1c6ea0fd8b46cd9f32e592fc` - Identifiers: CVE-2022-25510, CWE-798 - Deduplication result: duplicates because all criteria match, and type identifiers are ignored. + Only one identifier needs to match, in this case CVE-2022-25510. The examples above don't include the raw location values. Each scan type defines its own `fingerprint_data`, which is used to generate a `SHA1` hash that is used as the `location_fingerprint`. diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 16b92eb92a3..7a6c6dc8cd6 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -62,7 +62,7 @@ Authorization configuration can take one or two minutes to propagate. To authorize the agent to access the GitLab project where you keep Kubernetes manifests: -1. On the top bar, select **Menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). +1. On the top bar, select **Main menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `projects` attribute. 1. For the `id`, add the path: @@ -85,7 +85,7 @@ Choose the context to run `kubectl` commands from your CI/CD scripts. To authorize the agent to access all of the GitLab projects in a group or subgroup: -1. On the top bar, select **Menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). +1. On the top bar, select **Main menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `groups` attribute. 1. For the `id`, add the path: @@ -127,7 +127,7 @@ Run `kubectl config get-contexts`. ### Environments with both certificate-based and agent-based connections -When you deploy to an environment that has both a +When you deploy to an environment that has both a [certificate-based cluster](../../infrastructure/clusters/index.md) (deprecated) and an agent connection: - The certificate-based cluster's context is called `gitlab-deploy`. This context diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index 4978b56917b..67439788ef7 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -49,7 +49,7 @@ For details, view the [architecture documentation](https://gitlab.com/gitlab-org To update a Kubernetes cluster by using GitOps, complete the following steps. -1. Ensure you have a working Kubernetes cluster, and that the manifests are in a GitLab project. +1. Ensure you have a working Kubernetes cluster, and that the manifests or [Helm charts](gitops/helm.md) are in a GitLab project. 1. In the same project, [register and install the GitLab agent](install/index.md). 1. Configure the agent configuration file so that the agent monitors the project for changes to the Kubernetes manifests. Use the [GitOps configuration reference](#gitops-configuration-reference) for guidance. @@ -112,12 +112,12 @@ a Kubernetes SIG project. You can read more about the available annotations in t ## Automatic drift remediation -Drift happens when the current configuration of an infrastructure resource differs from its expected configuration. -Typically, this is caused by manually editing resources directly through the service that created the resource. Minimizing the -risk of drift helps to ensure configuration consistency and successful operations. +Drift happens when the current configuration of an infrastructure resource differs from its desired configuration. +Typically, this is caused by manually editing resources directly rather than via the used infrastructure-as-code +mechanism. Minimizing the risk of drift helps to ensure configuration consistency and successful operations. -In GitLab, the agent for Kubernetes regularly compares the expected state from the `git` repository with -the known state from the `cluster`. Deviations from the `git` state are fixed at every check. These checks +In GitLab, the agent for Kubernetes regularly compares the desired state from the `git` repository with +the actual state from the Kubernetes cluster. Deviations from the `git` state are fixed at every check. These checks happen automatically every 5 minutes. They are not configurable. The agent uses [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/). @@ -127,6 +127,7 @@ are checked for drift. This facilitates the use of in-cluster controllers to mod ## Related topics +- [Deploying Helm charts with the GitOps workflow](gitops/helm.md) - [GitOps working examples for training and demos](https://gitlab.com/groups/guided-explorations/gl-k8s-agent/gitops/-/wikis/home) - [Self-paced classroom workshop](https://gitlab-for-eks.awsworkshop.io) (Uses AWS EKS, but you can use for other Kubernetes clusters) - [Managing Kubernetes secrets in a GitOps workflow](gitops/secrets_management.md) diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md new file mode 100644 index 00000000000..bdc2664e7ba --- /dev/null +++ b/doc/user/clusters/agent/gitops/helm.md @@ -0,0 +1,112 @@ +--- +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 +--- + +# Using Helm charts to update a Kubernetes cluster (Alpha) **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371019) in GitLab 15.4. + +You can deploy Helm charts to your Kubernetes cluster and keep the resources in your cluster in sync +with your charts and values. To do this, you use the pull-based GitOps features of the agent for +Kubernetes. + +This feature is in Alpha and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/7938) +to track future work. Please tell us about your use cases by leaving comments in the epic. + +NOTE: +This feature is Alpha. In future releases, to accommodate new features, the configuration format might change without notice. + +## GitOps workflow steps + +To update a Kubernetes cluster by using GitOps with charts, complete the following steps. + +1. Ensure you have a working Kubernetes cluster, and that the chart is in a GitLab project. +1. In the same project, [register and install the GitLab agent](../install/index.md). +1. Configure the agent configuration file so that the agent monitors the project for changes to the chart. + Use the [GitOps configuration reference](#helm-configuration-reference) for guidance. + +## Helm chart with GitOps workflow + +To update a Kubernetes cluster by using Helm charts: + +1. Ensure you have a working Kubernetes cluster. +1. In a GitLab project: + - Store your Helm charts. + - [Register and install the GitLab agent](../install/index.md). +1. Update the agent configuration file so that the agent monitors the project for changes to the chart. + Use the [configuration reference](#helm-configuration-reference) for guidance. + +Any time you commit updates to your chart repository, the agent applies the chart in the cluster. + +## Helm configuration reference + +The following snippet shows an example of the possible keys and values for the GitOps section of an [agent configuration file](../install/index.md#create-an-agent-configuration-file) (`config.yaml`). + +```yaml +gitops: + charts: + - release_name: my-application-release + source: + project: + id: my-group/my-project-with-chart + path: dir-in-project/with/charts + namespace: my-ns + max_history: 1 +``` + +| Keyword | Description | +|--|--| +| `charts` | List of charts you want to be applied in your cluster. Charts are applied concurrently. All charts must be in the same directory. | +| `release_name` | Required. Name of the release to use when applying the chart. | +| `id` | Required. ID of the project where Helm chart is committed. No authentication mechanisms are currently supported. | +| `path` | Optional. Path of the chart in the project repository. Root of the repository is used by default. This is the directory with the `Chart.yaml` file. | +| `namespace` | Optional. Namespace to use when applying the chart. Defaults to `default`. | +| `max_history` | Optional. Maximum number of release [revisions to store in the cluster](https://helm.sh/docs/helm/helm_history/). | + +## Automatic drift remediation + +Drift happens when the current configuration of an infrastructure resource differs from its desired configuration. +Typically, drift is caused by manually editing resources directly, rather than by editing the code that describes the desired state. Minimizing the risk of drift helps to ensure configuration consistency and successful operations. +mechanism. Minimizing the risk of drift helps to ensure configuration consistency and successful operations. + +In GitLab, the agent for Kubernetes regularly compares the desired state from the chart source with +the actual state from the Kubernetes cluster. Deviations from the desired state are fixed at every check. These checks +happen automatically every 5 minutes. They are not configurable. + +## Example repository layout + +```plaintext +/my-chart + ├── templates + | └── ... + ├── charts + | └── ... + ├── Chart.yaml + ├── Chart.lock + ├── values.yaml + ├── values.schema.json + └── some-file-used-in-chart.txt +``` + +## Known issues + +The following are known issues: + +- Your chart must be in a GitLab project. The project must be an agent configuration project or a public + project. This known issue also exists for manifest-based GitOps and is tracked in + [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7704). +- Values for the chart must be in a `values.yaml` file. This file must be with the chart, + in the same project and path. +- Because of drift detection and remediation, release history, stored in the cluster, is not useful. + A new release is created every five minutes and the oldest release is discarded. + Eventually history consists only of the same information. + View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/372023) for details. + +## Troubleshooting + +### Agent cannot find values for the chart + +Make sure values are in `values.yaml` and in the same directory as the `Chart.yaml` file. +The filename must be lowercase, with `.yaml` extension (not `.yml`). diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 0d2b68e154d..eb62a733d36 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -29,14 +29,40 @@ For more details about the agent's purpose and architecture, see the [architectu ## Workflows -You can choose from two primary workflows. +You can choose from two primary workflows. The GitOps workflow is recommended. -In a [**GitOps** workflow](gitops.md), you keep your Kubernetes manifests in GitLab. You install a GitLab agent in your cluster, and -any time you update your manifests, the agent updates the cluster. This workflow is fully driven with Git and is considered pull-based, +### GitOps workflow + +In a [**GitOps** workflow](gitops.md): + +- You keep your Kubernetes manifests in GitLab. +- You install a GitLab agent in your cluster. +- Any time you update your manifests, the agent updates the cluster. +- The cluster automatically cleans up unexpected changes. It uses + [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/) + to fix any configuration inconsistencies that third parties introduce. + +This workflow is fully driven with Git and is considered **pull-based**, because the cluster is pulling updates from your GitLab repository. -In a [**CI/CD** workflow](ci_cd_workflow.md), you use GitLab CI/CD to query and update your cluster by using the Kubernetes API. -This workflow is considered push-based, because GitLab is pushing requests from GitLab CI/CD to your cluster. +GitLab recommends this workflow. We are actively investing in this workflow +so we can provide a first-class experience. + +### GitLab CI/CD workflow + +In a [**CI/CD** workflow](ci_cd_workflow.md): + +- You configure GitLab CI/CD to use the Kubernetes API to query and update your cluster. + +This workflow is considered **push-based**, because GitLab is pushing requests +from GitLab CI/CD to your cluster. + +Use this workflow: + +- When you have a heavily pipeline-oriented processes. +- When you need to migrate to the agent but the GitOps workflow cannot support the use case you need. + +This workflow has a weaker security model and is not recommended for production deployments. ## Supported cluster versions diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 4b0d8b77493..0240fbb45f0 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -40,7 +40,7 @@ To install the agent in your cluster: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the agent configuration file can be added to multiple directories (or subdirectories) of the repository. > - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -The agent uses a YAML file for configuration settings. You must create this file if: +For configuration settings, the agent uses a YAML file in the GitLab project. You must create this file if: - You use [a GitOps workflow](../gitops.md#gitops-workflow-steps). - You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#gitlab-cicd-workflow-steps) and want to authorize a different project to use the agent. @@ -56,7 +56,7 @@ To create an agent configuration file: - Start with an alphanumeric character. - End with an alphanumeric character. -1. In the repository, create a directory in this location: +1. In the repository, in the default branch, create this directory at the root: ```plaintext .gitlab/agents/<agent-name> @@ -81,7 +81,7 @@ Prerequisites: You must register an agent before you can install the agent in your cluster. To register an agent: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. If you have an [agent configuration file](#create-an-agent-configuration-file), it must be in this project. Your cluster manifest files should also be in this project. 1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index 5afe3ccec2b..2d20675b68b 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Operational Container Scanning **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive will be removed in GitLab 16.0. To view cluster vulnerabilities, you can view the [vulnerability report](../../application_security/vulnerabilities/index.md). You can also configure your agent so the vulnerabilities are displayed with other agent information in GitLab. @@ -19,12 +20,12 @@ to scan container images in your cluster for security vulnerabilities. NOTE: In GitLab 15.0 and later, you do not need to install Starboard operator in the Kubernetes cluster. -To begin scanning all resources in your cluster, add a `starboard` +To begin scanning all resources in your cluster, add a `container_scanning` configuration block to your agent configuration with a `cadence` field containing a CRON expression for when the scans will be run. ```yaml -starboard: +container_scanning: cadence: '0 0 * * *' # Daily at 00:00 (Kubernetes cluster time) ``` @@ -42,7 +43,7 @@ if you would like to scan only the `development`, `staging`, and `production` namespaces, you can use this configuration: ```yaml -starboard: +container_scanning: cadence: '0 0 * * *' vulnerability_report: namespaces: @@ -59,7 +60,7 @@ Prerequisite: To view vulnerability information in GitLab: -1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file. +1. On the top bar, select **Main menu > Projects** and find the project that contains the agent configuration file. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select the **Agent** tab. 1. Select an agent to view the cluster vulnerabilities. diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 058243ec218..b28f7546379 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -18,7 +18,7 @@ Prerequisite: To view the list of agents: -1. On the top bar, select **Menu > Projects** and find the project that contains your agent configuration file. +1. On the top bar, select **Main menu > Projects** and find the project that contains your agent configuration file. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select **Agent** tab to view clusters connected to GitLab through the agent. @@ -37,7 +37,7 @@ The activity logs help you to identify problems and get the information you need for troubleshooting. You can see events from a week before the current date. To view an agent's activity: -1. On the top bar, select **Menu > Projects** and find the project that contains your agent configuration file. +1. On the top bar, select **Main menu > Projects** and find the project that contains your agent configuration file. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select the agent you want to see activity for. @@ -59,7 +59,6 @@ To debug the cluster-side component (`agentk`) of the agent, set the log level according to the available options: - `error` -- `warning` - `info` - `debug` @@ -95,7 +94,7 @@ For more information about debugging, see [troubleshooting documentation](troubl To reset the agent token without downtime: 1. Create a new token: - 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select the agent you want to create a token for. 1. On the **Access tokens** tab, select **Create token**. @@ -117,7 +116,7 @@ clean up those resources manually. To remove an agent from the UI: -1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file. +1. On the top bar, select **Main menu > Projects** and find the project that contains the agent configuration file. 1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Delete agent**. diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index cf71729b517..96f41531576 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -33,7 +33,7 @@ With cluster environments, you can gain insight into:  -Access to cluster environments is restricted to +Access to cluster environments is restricted to [group maintainers and owners](../permissions.md#group-members-permissions) ## Usage diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 361276194b0..62f70faa630 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -61,7 +61,7 @@ To associate a cluster management project with your cluster: **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), on the top bar, select **Menu > Admin > Kubernetes**. + - [Instance-level cluster](../instance/clusters/index.md), on the top bar, select **Main 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. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 4b00784a7ae..cd71be321cc 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -45,7 +45,8 @@ If you have already configured the agent and connected a cluster with GitLab: To create a project from the cluster management project template: -1. On the top bar, select **Menu > Projects > Create new project**. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create from template**. 1. From the list of templates, next to **GitLab Cluster Management**, select **Use template**. 1. Enter the project details. @@ -80,7 +81,7 @@ If you remove everything below this comment, the pipeline will succeed. ### The main `helmfile.yml` file -The template contains a [Helmfile](https://github.com/roboll/helmfile) you can use to manage +The template contains a [Helmfile](https://github.com/helmfile/helmfile) you can use to manage cluster applications with [Helm v3](https://helm.sh/). This file has a list of paths to other Helm files for each app. They're all commented out by default, so you must uncomment @@ -89,7 +90,7 @@ the paths for the apps that you would like to use in your cluster. 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. +from your cluster. [Read more](https://helmfile.readthedocs.io/en/latest/) about how Helmfile works. ### Built-in applications 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 9a59d135fa0..ce39e13d928 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -4,7 +4,7 @@ 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 --- -# Migrate from GitLab Managed Apps to Cluster Management Projects **(FREE)** +# Migrate from GitLab Managed Apps to Cluster Management Projects (DEPRECATED) **(FREE)** The GitLab Managed Apps were deprecated in GitLab 14.0 in favor of user-controlled Cluster Management projects. diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index 4cd2705e917..96cb3f3ef38 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern group: Compliance 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 --- @@ -31,7 +31,7 @@ Prerequisites: To view the compliance report: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Compliance report**. ### Severity levels scale @@ -105,7 +105,7 @@ Depending on the merge strategy, the merge commit SHA can be a merge commit, squ To generate the Chain of Custody report: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Compliance report**. 1. Select **List of all merge commits**. @@ -122,7 +122,7 @@ Authenticated group owners can generate a commit-specific Chain of Custody repor - Using the GitLab UI: - 1. On the top bar, select **Menu > Groups** and find your group. + 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Compliance report**. 1. At the top of the compliance report, to the right of **List of all merge commits**, select the down arrow (**{chevron-lg-down}**). 1. Enter the merge commit SHA, and then select **Export commit custody report**. diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index 7b46886e236..c6c4834228b 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -1,6 +1,6 @@ --- type: reference -stage: Manage +stage: Govern group: Compliance 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 --- diff --git a/doc/user/compliance/license_compliance/img/denied_licenses_v13_3.png b/doc/user/compliance/license_compliance/img/denied_licenses_v13_3.png Binary files differdeleted file mode 100644 index aa3deb0c154..00000000000 --- a/doc/user/compliance/license_compliance/img/denied_licenses_v13_3.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/denied_licenses_v15_3.png b/doc/user/compliance/license_compliance/img/denied_licenses_v15_3.png Binary files differnew file mode 100644 index 00000000000..4ed84047133 --- /dev/null +++ b/doc/user/compliance/license_compliance/img/denied_licenses_v15_3.png diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 1c9f9e85ab7..19b01e4d854 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -736,7 +736,9 @@ Note, the merge request is not able to be merged until the `denied` license is r You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), which enables a designated approver that can approve and then merge a merge request with `denied` license. - +These policies can be configured by using the [Managed Licenses API](../../../api/managed_licenses.md). + + The **Policies** tab in the project's license compliance section displays your project's license policies. Project maintainers can specify policies in this section. @@ -763,7 +765,7 @@ license. You can enable `License-Check` one of two ways: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Merge request approvals**. 1. Select **Enable** or **Edit**. @@ -793,6 +795,18 @@ We recommend that you use the most recent version of all containers, and the mos ## Troubleshooting +### The License Compliance widget is stuck in a loading state + +A loading spinner is displayed in the following scenarios: + +- While the pipeline is in progress. +- If the pipeline is complete, but still parsing the results in the background. +- If the license scanning job is complete, but the pipeline is still running. + +The License Compliance widget polls every few seconds for updated results. When the pipeline is complete, the first poll after pipeline completion triggers the parsing of the results. This can take a few seconds depending on the size of the generated report. + +The final state is when a successful pipeline run has been completed, parsed, and the licenses displayed in the widget. + ### ASDF_PYTHON_VERSION does not automatically install the version Defining a non-latest Python version in ASDF_PYTHON_VERSION [doesn't have it automatically installed](https://gitlab.com/gitlab-org/gitlab/-/issues/325604). If your project requires a non-latest version of Python: @@ -888,3 +902,17 @@ root@6abb70e9f193:~# NOTE: Selecting a custom version of [Mono](https://www.mono-project.com/) or [.NET Core](https://dotnet.microsoft.com/download/dotnet) is currently not supported. + +### LicenseFinder::Maven: is not installed error + +If your project contains a `mvnw` or `mvnw.cmd` file, then the license scanning job may fail with the `LicenseFinder::Maven: is not installed error` error. To resolve this, modify the license scanning job to remove the files in the `before_script` section. Example: + +```yaml +include: + - template: License-Scanning.gitlab-ci.yml + +license_scanning: + before_script: + - rm mvnw + - rm mvnw.cmd +``` diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index e71a983ccfd..79f18e3abf1 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -1,6 +1,6 @@ --- stage: Plan -group: Product Planning +group: Certify 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 --- @@ -36,7 +36,7 @@ you must enable CRM features for the subgroup. To enable customer relations management in a group or subgroup: -1. On the top bar, select **Menu > Groups** and find your group or subgroup. +1. On the top bar, select **Main menu > Groups** and find your group or subgroup. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Customer relations is enabled**. @@ -48,7 +48,7 @@ To enable customer relations management in a group or subgroup: To view a group's contacts: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Contacts**.  @@ -57,7 +57,7 @@ To view a group's contacts: To create a contact: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Contacts**. 1. Select **New contact**. 1. Complete all required fields. @@ -70,7 +70,7 @@ contacts using the GraphQL API. To edit an existing contact: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Contacts**. 1. Next to the contact you wish to edit, select **Edit** (**{pencil}**). 1. Edit the required fields. @@ -85,7 +85,7 @@ contacts using the GraphQL API. To view a group's organizations: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Organizations**.  @@ -94,7 +94,7 @@ To view a group's organizations: To create an organization: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Organizations**. 1. Select **New organization**. 1. Complete all required fields. @@ -107,7 +107,7 @@ organizations using the GraphQL API. To edit an existing organization: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Organizations**. 1. Next to the organization you wish to edit, select **Edit** (**{pencil}**). 1. Edit the required fields. @@ -125,7 +125,7 @@ issues are linked to contacts matching the email addresses in the sender and CC To view a contact's issues, select a contact from the issue sidebar, or: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Contacts**. 1. Next to the contact whose issues you wish to view, select **View issues** (**{issues}**). @@ -133,7 +133,7 @@ To view a contact's issues, select a contact from the issue sidebar, or: To view an organization's issues: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Customer relations > Organizations**. 1. Next to the organization whose issues you wish to view, select **View issues** (**{issues}**). diff --git a/doc/user/discussions/img/create-new-issue_v15.png b/doc/user/discussions/img/create-new-issue_v15.png Binary files differdeleted file mode 100644 index 779196b6ba4..00000000000 --- a/doc/user/discussions/img/create-new-issue_v15.png +++ /dev/null diff --git a/doc/user/discussions/img/create_new_issue_v15_4.png b/doc/user/discussions/img/create_new_issue_v15_4.png Binary files differnew file mode 100644 index 00000000000..3720b601cc5 --- /dev/null +++ b/doc/user/discussions/img/create_new_issue_v15_4.png diff --git a/doc/user/discussions/img/unresolved_threads_v15.png b/doc/user/discussions/img/unresolved_threads_v15.png Binary files differdeleted file mode 100644 index 113af20effc..00000000000 --- a/doc/user/discussions/img/unresolved_threads_v15.png +++ /dev/null diff --git a/doc/user/discussions/img/unresolved_threads_v15_4.png b/doc/user/discussions/img/unresolved_threads_v15_4.png Binary files differnew file mode 100644 index 00000000000..1d1669de0f1 --- /dev/null +++ b/doc/user/discussions/img/unresolved_threads_v15_4.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 3fb0be6480c..ed0bcec9f49 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -91,7 +91,7 @@ For example, `28719b171a056960dfdc0012b625d0b47b123196` becomes You can add comments and threads to a particular commit. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Commits**. 1. Below the commits, in the **Comment** field, enter a comment. 1. Select **Comment** or select the down arrow (**{chevron-down}**) to select **Start thread**. @@ -309,15 +309,15 @@ To resolve a thread: 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. In the merge request, at the top of the page, -select **Create issue to resolve all threads** (**{issue-new}**): +click the ellipsis icon button (**{ellipsis_v}**) in the threads control and then select **Create issue to resolve all threads**: - + All threads are marked as resolved, and a link is added from the merge request to the newly created issue. @@ -339,10 +339,9 @@ You can prevent merge requests from being merged until all threads are resolved. When this setting is enabled, the **Unresolved threads** counter in a merge request is shown in orange when at least one thread remains unresolved. -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. Under **Merge checks**, select the **All threads must be resolved** checkbox. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge checks** section, select the **All threads must be resolved** checkbox. 1. Select **Save changes**. ### Automatically resolve threads in a merge request when they become outdated @@ -350,11 +349,10 @@ is shown in orange when at least one thread remains unresolved. You can set merge requests to automatically resolve threads when lines are modified with a new push. -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. Under **Merge options**, select the - **Automatically resolve merge request diff threads when they become outdated** checkbox. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge options** section, select + **Automatically resolve merge request diff threads when they become outdated**. 1. Select **Save changes**. Threads are now resolved if a push makes a diff section outdated. diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index a62b9c9e363..60091449256 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -8,10 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w From October 19, 2022, namespaces in GitLab.com on the Free tier will be limited to five (5) members per [namespace](namespace/index.md). -This limit applies to top-level groups and personal namespaces. - -In a personal namespace, the limit applies across all projects in your personal -namespace. +This limit applies to top-level private groups. On the transition date, if your namespace has six or more unique members: @@ -40,17 +37,11 @@ Prerequisite: - You must have the Owner role for the group. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups > View all groups** and find your group. 1. On the left sidebar, select **Settings > Usage Quotas**. 1. To view all members, select the **Seats** tab. 1. To remove a member, select **Remove user**. -NOTE: -The **Usage Quotas** page is not available for personal namespaces. You can -view and [remove members](project/members/index.md#remove-a-member-from-a-project) -in each project instead. The five user limit includes all -unique members across all projects in your personal namespace. - If you need more time to manage your members, or to try GitLab features with a team of more than five members, you can [start a trial](https://about.gitlab.com/free-trial/). A trial lasts for 30 days and includes an unlimited number of members. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 53e459f7a09..62b685ea4f4 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -208,9 +208,9 @@ from those IPs and allow them. GitLab.com is fronted by Cloudflare. For incoming connections to GitLab.com, you might need to allow CIDR blocks of Cloudflare ([IPv4](https://www.cloudflare.com/ips-v4/) and [IPv6](https://www.cloudflare.com/ips-v6/)). -For outgoing connections from CI/CD runners, we are not providing static IP -addresses. All GitLab.com shared runners are deployed into Google Cloud Platform (GCP). Any -IP-based firewall can be configured by looking up all +For outgoing connections from CI/CD runners, we are not providing static IP addresses. +All GitLab.com shared runners are deployed into Google Cloud Platform (GCP) in `us-east1`. +Any IP-based firewall can be configured by looking up [IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#find_ip_range). ## Hostname list @@ -328,6 +328,12 @@ for `shared_buffers` is quite high, and we are GitLab.com uses the default of 60 seconds for [Puma request timeouts](../../administration/operations/puma.md#change-the-worker-timeout). +## Merge request reviewer maximum + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91406) in GitLab 15.3. + +A maximum of 100 reviewers can be assigned to a merge request. + ## GitLab.com-specific rate limits NOTE: @@ -336,7 +342,7 @@ documentation. When a request is rate limited, GitLab responds with a `429` status code. The client should wait before attempting the request again. There -are also informational headers with this response detailed in +are also informational headers with this response detailed in [rate limiting responses](#rate-limiting-responses). The following table describes the rate limits for GitLab.com, both before and @@ -358,8 +364,8 @@ after the limits change in January, 2021: | **Pipeline creation** requests (for a given **project, user, and commit**) | | **25** requests per minute | | **Alert integration endpoint** requests (for a given **project**) | | **3600** requests per hour | -More details are available on the rate limits for -[protected paths](#protected-paths-throttle) and +More details are available on the rate limits for +[protected paths](#protected-paths-throttle) and [raw endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). GitLab can rate-limit requests at several layers. The rate limits listed here diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index c469d6c2f6d..bdef13af3f9 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -12,13 +12,21 @@ Configure your groups to control group permissions and access. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in GitLab 12.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/224129) in GitLab 13.4. +> - [Moved to Settings/Repository](https://gitlab.com/gitlab-org/gitlab/-/issues/220365) in GitLab 15.4. Group push rules allow group maintainers to set [push rules](../project/repository/push_rules.md) for newly created projects in the specific group. -To configure push rules for a group: +In GitLab 15.4 and later, to configure push rules for a group: -1. Go to the groups's **Push Rules** page. +1. On the left sidebar, select **Push rules**. +1. Select the settings you want. +1. Select **Save Push Rules**. + +In GitLab 15.3 and earlier, to configure push rules for a group: + +1. On the left sidebar, select **Settings > Repository** page. +1. Expand the **Pre-defined push rules** section. 1. Select the settings you want. 1. Select **Save Push Rules**. @@ -27,6 +35,27 @@ The group's new subgroups have push rules set for them based on either: - The closest parent group with push rules defined. - Push rules set at the instance level, if no parent groups have push rules defined. +## Restrict Git access protocols + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365601) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `group_level_git_protocol_control`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to +[enable the feature flag](../../administration/feature_flags.md) named `group_level_git_protocol_control`. On GitLab.com, +this feature is available. + +You can set the permitted protocols used to access a group's repositories to either SSH, HTTPS, or both. This setting +is disabled when the [instance setting](../admin_area/settings/visibility_and_access_controls.md#configure-enabled-git-access-protocols) is +configured by an administrator. + +To change the permitted Git access protocols for a group: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. Choose the permitted protocols from **Enabled Git access protocols**. +1. Select **Save changes**. + ## Restrict group access by IP address **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. @@ -43,8 +72,6 @@ applies to: You should consider some security implications before configuring IP address restrictions. -- Restricting HTTP traffic on GitLab.com with IP address restrictions causes SSH requests (including Git operations over - SSH) to fail. For more information, see [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/271673). - Administrators and group owners can access group settings from any IP address, regardless of IP restriction. However: - Groups owners cannot access projects belonging to the group when accessing from a disallowed IP address. - Administrators can access projects belonging to the group when accessing from a disallowed IP address. @@ -57,14 +84,17 @@ You should consider some security implications before configuring IP address res restricted IP address, the IP restriction prevents code from being cloned. - Users may still see some events from the IP restricted groups and projects on their dashboard. Activity may include push, merge, issue, or comment events. +- IP access restrictions for Git operations via SSH are supported only on GitLab SaaS. + IP access restrictions applied to self-managed instances block SSH completely. ### Restrict group access by IP address To restrict group access by IP address: -1. Go to the group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. -1. In the **Allow access to the following IP addresses** field, enter IPv4 or IPv6 address ranges in CIDR notation. +1. In the **Restrict access by IP address** field, enter IPv4 or IPv6 address ranges in CIDR notation. 1. Select **Save changes**. In self-managed installations of GitLab 15.1 and later, you can also configure @@ -81,7 +111,8 @@ You can prevent users with email addresses in specific domains from being added To restrict group access by domain: -1. Go to the group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. In the **Restrict membership by email** field, enter the domain names. 1. Select **Save changes**. @@ -124,23 +155,24 @@ If you prevent group sharing outside the hierarchy for the **Animals** group: To prevent sharing outside of the group's hierarchy: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. -1. Select **Prevent members from sending invitations to groups outside of `<group_name>` and its subgroups**. +1. Select **Members cannot invite groups outside of `<group_name>` and its subgroups**. 1. Select **Save changes**. ## Prevent a project from being shared with groups -Prevent projects in a group from -[sharing a project with another group](../project/members/share_project_with_groups.md) +Prevent projects in a group from +[sharing a project with another group](../project/members/share_project_with_groups.md) to enable tighter control over project access. To prevent a project from being shared with other groups: -1. Go to the group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. -1. Select **Prevent sharing a project in `<group_name>` with other groups**. +1. Select **Projects in `<group_name>` cannot be shared with other groups**. 1. Select **Save changes**. This setting applies to all subgroups unless overridden by a group owner. Groups already @@ -151,7 +183,7 @@ added to a project lose access when the setting is enabled. As a group owner, you can prevent non-members from requesting access to your group. -1. On the top bar, select **Menu > Groups**. +1. On the top bar, **Main menu > Groups** and find your group. 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. @@ -173,7 +205,8 @@ If even one is set to `true`, then the group does not allow outside forks. To prevent projects from being forked outside the group: -1. Go to the top-level group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Check **Prevent project forking outside current group**. 1. Select **Save changes**. @@ -194,9 +227,9 @@ The setting does not cascade. Projects in subgroups observe the subgroup configu To prevent members from being added to projects in a group: -1. Go to the group's **Settings > General** page. -1. Expand the **Permissions and group features** section. -1. Under **Membership**, select **Prevent adding new members to projects within this group**. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Under **Membership**, select **Users cannot be added to projects in this group**. 1. Select **Save changes**. All users who previously had permissions can no longer add members to a group. @@ -241,7 +274,8 @@ To create group links via filter: LDAP user permissions can be manually overridden by an administrator. To override a user's permissions: -1. Go to your group's **Group information > Members** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Members**. 1. In the row for the user you are editing, select the pencil (**{pencil}**) icon. 1. Select **Edit permissions** in the modal. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 0da7eaa4d55..17a5551adbf 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -21,7 +21,7 @@ your group, enabling you to use the same cluster across multiple projects. To view your group-level Kubernetes clusters: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Kubernetes**. ## Cluster management project @@ -89,7 +89,7 @@ your cluster, which can cause deployment jobs to fail. To clear the cache: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Kubernetes**. 1. Select your cluster. 1. Expand **Advanced settings**. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index ba805d6e1bb..7750782a623 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -19,7 +19,7 @@ group. To view Contribution Analytics: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Contribution**. ## Using Contribution Analytics diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 333bef84dcc..bb18c69f7ae 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -36,7 +36,7 @@ Prerequisite: To view DevOps Adoption: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > DevOps adoption** ## DevOps Adoption categories @@ -80,7 +80,7 @@ twelve months. The chart only shows data from when you enabled DevOps Adoption f To view feature adoption over time: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > DevOps adoption**. 1. Select the **Overview** tab. diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index f03a56d8a00..a8bbb0575b3 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -15,7 +15,7 @@ labels. To view an epic board: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Epics > Boards**.  @@ -28,7 +28,7 @@ Prerequisites: To create a new epic board: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Epics > Boards**. 1. In the upper left corner, select the dropdown with the current board name. 1. Select **Create new board**. @@ -77,7 +77,7 @@ Prerequisites: To create a new list: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Epics > Boards**. 1. In the upper-right corner, select **Create list**. 1. In the **New list** column expand the **Select a label** dropdown and select the label to use as @@ -155,6 +155,42 @@ into another list. Learn about possible effects in [Dragging epics between lists To move a list, select its top bar, and drag it horizontally. You can't move the **Open** and **Closed** lists, but you can hide them when editing an epic board. +#### Move an epic to the start of the list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4. + +When you have many epics, it's inconvenient to manually drag an epic from the bottom of a board list all +the way to the top. You can move epics to the top of the list with a menu shortcut. + +Your epic is moved to the top of the list even if other epics are hidden by a filter. + +Prerequisites: + +- You must at least have the Reporter role for a group. + +To move an epic to the start of the list: + +1. In an epic board, hover over the card of the epic you want to move. +1. Select the vertical ellipsis (**{ellipsis_v}**), then **Move to start of list**. + +#### Move an epic to the end of the list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4. + +When you have many epics, it's inconvenient to manually drag an epic from the top of a board list all +the way to the bottom. You can move epics to the bottom of the list with a menu shortcut. + +Your epic is moved to the bottom of the list even if other epics are hidden by a filter. + +Prerequisites: + +- You must at least have the Reporter role for a group. + +To move an epic to the end of the list: + +1. In an epic board, hover over the card of the epic you want to move. +1. Select the vertical ellipsis (**{ellipsis_v}**), then **Move to end of list**. + #### Dragging epics between lists When you drag epics between lists, the result is different depending on the source list diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 71d7b7fbb0c..26826ec5832 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -210,7 +210,7 @@ Prerequisites: To view epics in a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Epics**. ### Cached epic count @@ -244,7 +244,7 @@ You can filter the list of epics by: To filter: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Epics**. 1. Select the field **Search or filter results**. 1. From the dropdown menu, select the scope or enter plain text to search by epic title or description. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index edf4d7677df..21b389581ae 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -88,6 +88,7 @@ migrated: - Board Lists - Boards - Epics ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250281) in 13.7) + - Epic resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Finisher - Group Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9) - Iterations ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292428) in 13.10) @@ -116,10 +117,17 @@ On self-managed GitLab, migrating project resources are not available by default - CI Pipelines ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339407) in GitLab 14.6) - Designs ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339421) in GitLab 15.1) - Issues ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267946) in GitLab 14.4) + - Issue resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339419) in GitLab 14.4) - LFS Objects ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339405) in GitLab 14.8) - Members ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341886) in GitLab 14.8) - Merge Requests ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339403) in GitLab 14.5) + - Multiple merge request assignees ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request reviewers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request approvers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Merge request resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Migrate Push Rules ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339403) in GitLab 14.6) - Pull Requests (including external pull requests) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339409) in GitLab 14.5) - Pipeline History ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339412) in GitLab 14.6) @@ -167,3 +175,17 @@ import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import) import.status #=> 3 means that the import timed out. ``` + +### Error: `404 Group Not Found` + +If you attempt to import a group that has a path comprised of only numbers (for example, `5000`), GitLab attempts to find the group by ID instead of the +path. This causes a `404 Group Not Found` error. To solve this, the source group path must be changed to include a non-numerical character using either: + +- The GitLab UI: + + 1. On the top bar, select **Main menu > Groups** and find your group. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **Advanced**. + 1. Under **Change group URL**, change the group URL to include non-numeric characters. + +- The [Groups API](../../../api/groups.md#update-group). diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index b3fdeb0ab41..0cde0f1f133 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,51 +1,48 @@ --- -type: reference, howto stage: Manage group: Optimize 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 --- -# Insights **(ULTIMATE)** +# Insights for groups **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. -Configure the Insights that matter for your groups. Explore data such as -triage hygiene, issues created or closed for a given period, average time for merge -requests to be merged, and much more. - - +Configure Insights to explore data about you group's activity, such as +triage hygiene, issues created or closed in a given period, and average time for merge +requests to be merged. ## View your group's Insights +Prerequisites: + +- You must have [permission](../../permissions.md#group-members-permissions) to view the group. +- You must have access to a project to view information about its merge requests and issues, + and permission to view them if they are confidential. + To access your group's Insights: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Insights**. + + ## Configure your Insights -GitLab reads Insights from the [default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). -If you want to customize it: +GitLab reads Insights from the +[default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). +You can also create custom Insights charts that are more relevant for your group. -1. Create a new file [`.gitlab/insights.yml`](../../project/insights/index.md) +To customize your Insights: + +1. Create a new file [`.gitlab/insights.yml`](../../project/insights/index.md#writing-your-gitlabinsightsyml) in a project that belongs to your group. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Insights**. 1. Select the project that contains your `.gitlab/insights.yml` configuration file. 1. Select **Save changes**. -## Permissions - -If you have access to view a group, then you have access to view its Insights. - -NOTE: -Issues or merge requests that you don't have access to (because you don't have -access to the project they belong to, or because they are confidential) are -filtered out of the Insights charts. - -You may also consult the [group permissions table](../../permissions.md#group-members-permissions). - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 62337dabcc0..26d77edd89b 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -15,7 +15,7 @@ prior. To access the chart: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Issue Analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 530635802a6..4cc879ef32d 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -12,11 +12,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Moved to GitLab Premium in 13.9. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 14.6. [Feature flag `group_iterations`](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) removed. -WARNING: -After [Iteration Cadences](#iteration-cadences) becomes generally available, -manual iteration scheduling will be [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) in GitLab 15.6. -To enhance the role of iterations as time boundaries, we will also deprecate the title field. - Iterations are a way to track issues over a period of time. This allows teams to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) for tracking over different time periods. @@ -37,7 +32,7 @@ In GitLab, iterations are similar to milestones, with a few differences: To view the iterations list: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Issues > Iterations**. To view all the iterations in a cadence, ordered by descending date, select that iteration cadence. @@ -66,7 +61,7 @@ Prerequisites: To create an iteration: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues > Iterations**. 1. Select **New iteration**. 1. Enter the title, a description (optional), a start date, and a due date. @@ -174,7 +169,7 @@ and get a more accurate understanding of scope attributable to each label. To group issues by label: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues > Iterations**. 1. In the **Group by** dropdown, select **Label**. 1. Select the **Filter by label** dropdown. @@ -187,7 +182,7 @@ To group issues by label: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1 [with a flag](../../../administration/feature_flags.md), named `iteration_cadences`. Disabled by default. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/354977) in GitLab 15.0: All scheduled iterations must start on the same day of the week as the cadence start day. Start date of cadence cannot be edited after the first iteration starts. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.0. -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/367493) in GitLab 15.3: A new automation start date can be selected for cadence. Upcoming iterations will be scheduled to start on the same day of the week as the changed start date. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/367493) in GitLab 15.4: A new automation start date can be selected for cadence. Upcoming iterations will be scheduled to start on the same day of the week as the changed start date. Iteration cadences can be manually managed by turning off the automatic scheduling feature. Iteration cadences automate iteration scheduling. You can use them to automate creating iterations every 1, 2, 3, or 4 weeks. You can also @@ -203,11 +198,12 @@ Prerequisites: To create an iteration cadence: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues > Iterations**. 1. Select **New iteration cadence**. -1. Complete the fields. - - Enter the title and description of the iteration cadence. +1. Enter the title and description of the iteration cadence. +1. To manually manage the iteration cadence, clear the **Enable automatic scheduling** checkbox and skip the next step. +1. Complete the required fields to use automatic scheduling. - Select the automation start date of the iteration cadence. Iterations will be scheduled to begin on the same day of the week as the day of the week of the start date. - From the **Duration** dropdown list, select how many weeks each iteration should last. @@ -224,11 +220,11 @@ Prerequisites: To edit an iteration cadence: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues > Iterations**. 1. Select **Edit iteration cadence**. -When you edit the **Automation start date** field, +When you are using automatic scheduling and edit the **Automation start date** field, you must set a new start date that doesn't overlap with the existing current or past iterations. @@ -236,52 +232,23 @@ Editing **Upcoming iterations** is a non-destructive action. If ten upcoming iterations already exist, changing the number under **Upcoming iterations** to `2` doesn't delete the eight existing upcoming iterations. -### Delete an iteration cadence - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. - -Prerequisites: - -- You must have at least the Reporter role for a group. - -Deleting an iteration cadence also deletes all iterations within that cadence. - -To delete an iteration cadence: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. -1. Select the three-dot menu (**{ellipsis_v}**) > **Delete cadence** for the cadence you want to delete. -1. Select **Delete cadence** in the confirmation modal. - -### Manual iteration cadences - -When you **enable** the iteration cadences feature, all previously -created iterations are added to a default iteration cadence. -You can continue to add, edit, and remove iterations in -this default cadence. - -#### Convert a manual cadence to use automatic scheduling - -WARNING: -The upgrade is irreversible. After it's done, a new manual iteration cadence cannot be created. - -Prerequisites: +#### Turn on automatic scheduling for manual iterations cadence -- You must have created [iterations](#iterations) without cadences before enabling iteration cadences for your group. -To upgrade the iteration cadence to use the automation features: - -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues > Iterations**. -1. Select the three-dot menu (**{ellipsis_v}**) > **Edit cadence** for the cadence you want to upgrade. +1. Select the three-dot menu (**{ellipsis_v}**) > **Edit cadence** for the cadence for which you want to enable automatic scheduling. +1. Check the **Enable automatic scheduling** checkbox. 1. Complete the required fields **Duration**, **Upcoming iterations**, and **Automation start date**. For **Automation start date**, you can select any date that doesn't overlap with the existing open iterations. If you have upcoming iterations, the automatic scheduling adjusts them appropriately to fit -your chosen duration. +your chosen duration. 1. Select **Save changes**. -#### Converted cadences example +When you want to manage your iterations cadence manually again, edit your cadence and uncheck the **Enable automatic scheduling** checkbox. + +#### Example of turning on automatic scheduling for manual iterations cadence -For example, suppose it's Friday, April 15, and you have three iterations in a manual cadence: +Suppose it's Friday, April 15, and you have three iteration in a manual iterations cadence: - Monday, April 4 - Friday, April 8 (closed) - Tuesday, April 12 - Friday, April 15 (ongoing) @@ -300,8 +267,25 @@ after the conversion you have the following iterations: - Monday, April 18 - Sunday, April 24 (upcoming) - Monday, April 25 - Sunday, May 1 (upcoming) -Your existing upcoming iteration "Tuesday, April 12 - Friday, April 15" +Your existing upcoming iteration "Tuesday, April 12 - Friday, April 15" is changed to "April 18 - Sunday, April 24". An additional upcoming iteration "April 25 - Sunday, May 1" is scheduled to satisfy the requirement that there are at least two upcoming iterations scheduled. + +### Delete an iteration cadence + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. + +Prerequisites: + +- You must have at least the Reporter role for a group. + +Deleting an iteration cadence also deletes all iterations within that cadence. + +To delete an iteration cadence: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Issues > Iterations**. +1. Select the three-dot menu (**{ellipsis_v}**) > **Delete cadence** for the cadence you want to delete. +1. Select **Delete cadence**. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index a9cc6cc8432..ca9ff0d7b3e 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -10,8 +10,7 @@ Use groups to manage one or more related projects at the same time. ## View groups -1. On the top bar, select **Menu > Groups**. -1. Select **Explore groups**. +To view groups, on the top bar, select **Main menu > Groups > View all groups**. The **Groups** page shows a list of groups, sorted by last updated date. @@ -25,7 +24,7 @@ The **Groups** page shows a list of groups, sorted by last updated date. To create a group: 1. On the top bar, either: - - Select **Menu > Groups**, and on the right, select **Create group**. + - Select **Main menu > Groups > View all groups**, and on the right, select **New group**. - To the left of the search box, select the plus sign and then **New group**. 1. Select **Create group**. 1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see @@ -45,7 +44,7 @@ For details about groups, watch [GitLab Namespaces (users, groups and subgroups) To remove a group and its contents: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Remove group** section, select **Remove group**. @@ -54,7 +53,7 @@ To remove a group and its contents: A group can also be removed from the groups dashboard: -1. On the top bar, select **Menu > Groups**. +1. On the top bar, select **Main menu > Groups > View all groups**. 1. Select **Your Groups**. 1. Select (**{ellipsis_v}**) for the group you want to delete. 1. Select **Delete**. @@ -83,7 +82,7 @@ Prerequisites: To immediately remove a group marked for deletion: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Advanced**. 1. In the "Permanently remove group" section, select **Remove group**. @@ -98,7 +97,8 @@ are deleted. To restore a group that is marked for deletion: -1. Go to your group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. Select **Settings > General**. 1. Expand the **Path, transfer, remove** section. 1. In the Restore group section, select **Restore group**. @@ -106,7 +106,7 @@ To restore a group that is marked for deletion: As a user, you can request to be a member of a group, if an administrator allows it. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. Under the group name, select **Request Access**. As many as ten of the most-recently-active group owners receive an email with your request. @@ -127,7 +127,7 @@ To find members in a group, you can sort, filter, or search. Filter a group to find members. By default, all members in the group and subgroups are displayed. -1. Go to the group and select **Group information > Members**. +1. On the top bar, select **Main menu > Groups** and find your group. 1. Above the list of members, in the **Filter members** box, enter filter criteria. - To view members in the group only, select **Membership = Direct**. - To view members of the group and its subgroups, select **Membership = Inherited**. @@ -138,7 +138,8 @@ Filter a group to find members. By default, all members in the group and subgrou You can search for members by name, username, or email. -1. Go to the group and select **Group information > Members**. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Members**. 1. Above the list of members, in the **Filter members** box, enter search criteria. 1. To the right of the **Filter members** box, select the magnifying glass (**{search}**). @@ -146,7 +147,8 @@ You can search for members by name, username, or email. You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in**. -1. Go to the group and select **Group information > Members**. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Members**. 1. Above the list of members, on the top right, from the **Account** list, select the criteria to filter by. 1. To switch the sort between ascending and descending, to the right of the **Account** list, select the @@ -156,7 +158,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last You can give a user access to all projects in a group. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Members**. 1. Select **Invite members**. 1. Fill in the fields. @@ -182,11 +184,12 @@ Prerequisites: To remove a member from a group: -1. Go to the group. -1. From the left menu, select **Group information > Members**. -1. Next to the member you want to remove, select **Delete**. -1. Optional. On the **Remove member** confirmation box, select the - **Also unassign this user from linked issues and merge requests** checkbox. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Members**. +1. Next to the member you want to remove, select **Remove member**. +1. Optional. On the **Remove member** confirmation box: + - To remove direct user membership from subgroups and projects, select the **Also remove direct user membership from subgroups and projects** checkbox. + - To unassign the user from linked issues and merge requests, select the **Also unassign this user from linked issues and merge requests** checkbox. 1. Select **Remove member**. ## Add projects to a group @@ -207,12 +210,12 @@ By default, users with at least the Developer role can create projects under a g To change this setting for a specific group: -1. On the top bar, select **Menu > Groups**. +1. On the top bar, select **Main menu > Groups > View all groups**. 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. 1. Expand the **Permissions and group features** section. -1. Select the desired option in the **Allowed to create projects** dropdown list. +1. Select the desired option in the **Roles allowed to create projects** dropdown list. 1. Select **Save changes**. To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). @@ -223,11 +226,13 @@ You can change the owner of a group. Each group must always have at least one member with the Owner role. - As an administrator: - 1. Go to the group and from the left menu, select **Group information > Members**. + 1. On the top bar, select **Main menu > Groups** and find your group. + 1. On the left sidebar, select **Group information > Members**. 1. Give a different member the **Owner** role. 1. Refresh the page. You can now remove the **Owner** role from the original owner. - As the current group's owner: - 1. Go to the group and from the left menu, select **Group information > Members**. + 1. On the top bar, select **Main menu > Groups** and find your group. + 1. On the left sidebar, select **Group information > Members**. 1. Give a different member the **Owner** role. 1. Have the new owner sign in and remove the **Owner** role from you. @@ -246,7 +251,8 @@ create a new group and transfer projects to it instead. To change your group path (group URL): -1. Go to your group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General** page. 1. Expand the **Advanced** section. 1. Under **Change group URL**, enter a new name. 1. Select **Change group URL**. @@ -326,7 +332,7 @@ When transferring groups, note: To transfer a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Remove group** section, select **Transfer group**. @@ -342,7 +348,7 @@ To transfer a group: > - [User interface changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352961) in GitLab 15.1. [Delayed project deletion](../project/settings/index.md#delayed-project-deletion) is locked and disabled unless the instance-level settings for -[deletion protection](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) is enabled for either groups only or groups and projects. +[deletion protection](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) are enabled for either groups only or groups and projects. When enabled on groups, projects in the group are deleted after a period of delay. During this period, projects are in a read-only state and can be restored. The default period is seven days but [is configurable at the instance level](../admin_area/settings/visibility_and_access_controls.md#retention-period). @@ -356,7 +362,8 @@ the default setting. To enable delayed deletion of projects in a group: -1. Go to the group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Scroll to: - (GitLab 15.1 and later) **Deletion protection** and select **Keep deleted projects**. @@ -377,9 +384,10 @@ You can disable all email notifications related to the group, which includes its To disable email notifications: -1. Go to the group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. -1. Select **Disable email notifications**. +1. Select **Email notifications are disabled**. 1. Select **Save changes**. ## Disable group mentions @@ -396,9 +404,10 @@ This is particularly helpful for groups with a large number of users. To disable group mentions: -1. Go to the group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. -1. Select **Disable group mentions**. +1. Select **Group mentions are disabled**. 1. Select **Save changes**. ## Export members as CSV **(PREMIUM)** @@ -408,7 +417,8 @@ To disable group mentions: You can export a list of members in a group or subgroup as a CSV. -1. Go to your group or subgroup and select either **Group information > Members** or **Subgroup information > Members**. +1. On the top bar, select **Main menu > Groups** and find your group or subgroup. +1. On the left sidebar, select either **Group information > Members** or **Subgroup information > Members**. 1. Select **Export as CSV**. 1. After the CSV file has been generated, it is emailed as an attachment to the user that requested it. @@ -434,7 +444,7 @@ Prerequisite: To specify a user cap: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. You can set a cap on the top-level group only. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. @@ -456,7 +466,7 @@ Prerequisite: To remove the user cap: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. In the **User cap** box, delete the value. @@ -477,7 +487,7 @@ Prerequisite: To approve members that are pending because they've exceeded the user cap: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > Usage Quotas**. 1. On the **Seats** tab, under the alert, select **View pending approvals**. 1. For each member you want to approve, select **Approve**. @@ -508,7 +518,8 @@ Define project templates at a group level by setting a group as the template sou To enable group file templates: -1. Go to the group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Templates** section. 1. Choose a project to act as the template repository. 1. Select **Save changes**. @@ -525,7 +536,8 @@ that belong to the group. To view the merge request approval settings for a group: -1. Go to the top-level group's **Settings > General** page. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Merge request approvals** section. 1. Select the settings you want. 1. Select **Save changes**. @@ -548,7 +560,7 @@ Changes to [group wikis](../project/wiki/group.md) do not appear in group activi 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. On the top bar, select **Main menu > Groups > View all groups**. 1. Select **Your Groups**. 1. Find the group and select it. 1. On the left sidebar, select **Group information > Activity**. @@ -568,3 +580,13 @@ the following checks when creating or updating namespaces or groups: In the unlikely event that you see these errors in your GitLab installation, [contact Support](https://about.gitlab.com/support/) so that we can improve this validation. + +### Find groups using an SQL query + +To find and store an array of groups based on an SQL query in the [rails console](../../administration/operations/rails_console.md): + +```ruby +# Finds groups and subgroups that end with '%oup' +Group.find_by_sql("SELECT * FROM namespaces WHERE name LIKE '%oup'") +=> [#<Group id:3 @test-group>, #<Group id:4 @template-group/template-subgroup>] +``` diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 6e3ea7d6c0f..f130ecb61dc 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -37,7 +37,7 @@ The **Analytics > Repositories** group page displays the average test coverage o To see the latest code coverage for each project in your group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Repositories**. 1. In the **Latest test coverage results** section, from the **Select projects** dropdown list, choose the projects you want to check. @@ -52,7 +52,7 @@ You can get a CSV of the code coverage data for all of the projects in your grou To get the report: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Repositories**. 1. Select **Download historic test coverage data (.csv)**. 1. Select the projects and date range you want to include in the report. diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index 97e8f9c54a3..d09a8524247 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -31,20 +31,27 @@ If you are currently having an issue with GitLab, you may want to check your [su ## Azure Active Directory -Basic SAML app configuration: +This section has screenshots for the elements of Azure Active Directory configuration. + +### Basic SAML app configuration  -User claims and attributes: +### User claims and attributes  -SCIM mapping: +### SCIM mapping + +Provisioning:  + +Attribute mapping: +  -Group Sync: +### Group Sync  diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 8bc316f9396..322b417d466 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -70,9 +70,9 @@ role. Users granted: - A higher role with Group Sync are displayed as having - [direct membership](../../project/members/#display-direct-members) of the group. + [direct membership](../../project/members/index.md#display-direct-members) of the group. - A lower or the same role with Group Sync are displayed as having - [inherited membership](../../project/members/#display-inherited-members) of the group. + [inherited membership](../../project/members/index.md#display-inherited-members) of the group. ### Automatic member removal @@ -167,3 +167,18 @@ graph TB > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. + +## Troubleshooting + +This section contains possible solutions for problems you might encounter. + +### User that belongs to many SAML groups automatically removed from GitLab group + +When using Azure AD as the SAML identity provider, users that belong to many SAML groups can be automatically removed from your GitLab group. Users are removed from GitLab +groups if the group claim is missing from the user's SAML assertion. + +Because of a [known issue with Azure AD](https://support.esri.com/en/technical-article/000022190), if a user belongs to more than 150 SAML groups, the group claim is not sent +in the user's SAML assertion. + +To work around this issue, allow more than 150 group IDs to be sent in SAML token using configuration steps in the +[Azure AD documentation](https://support.esri.com/en/technical-article/000022190). diff --git a/doc/user/group/saml_sso/img/scim_token_v13_3.png b/doc/user/group/saml_sso/img/scim_token_v13_3.png Binary files differdeleted file mode 100644 index e98f755718a..00000000000 --- a/doc/user/group/saml_sso/img/scim_token_v13_3.png +++ /dev/null diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 25060f8e749..d33cde0a6b1 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -24,7 +24,7 @@ If required, you can find [a glossary of common terms](../../../integration/saml ## Configure your identity provider 1. Find the information in GitLab required for configuration: - 1. On the top bar, select **Menu > Groups** and find your group. + 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > SAML SSO**. 1. Note the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. 1. Configure your SAML identity provider app using the noted details. @@ -79,7 +79,7 @@ You can configure the following attributes with GitLab.com Group SAML: GitLab provides metadata XML that can be used to configure your identity provider. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. 1. Follow your identity provider's documentation and paste the metadata URL when it's requested. @@ -88,7 +88,7 @@ GitLab provides metadata XML that can be used to configure your identity provide After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > SAML SSO**. 1. Find the SSO URL from your identity provider and enter it the **Identity provider single sign-on URL** field. 1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. @@ -101,6 +101,19 @@ After you set up your identity provider to work with GitLab, you must configure NOTE: The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#google-workspace-setup-notes)), use a secure signature algorithm. +### Additional configuration information + +Many SAML terms can vary between providers. It is possible that the information you are looking for is listed under another name. + +For more information, start with your identity provider's documentation. Look for their options and examples to see how they configure SAML. This can provide hints on what you need to configure GitLab to work with these providers. + +It can also help to look at our [more detailed docs for self-managed GitLab](../../../integration/saml.md). +SAML configuration for GitLab.com is mostly the same as for self-managed instances. +However, self-managed GitLab instances use a configuration file that supports more options as described in the external [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml/). +Internally that uses the [`ruby-saml` library](https://github.com/onelogin/ruby-saml), so we sometimes check there to verify low level details of less commonly used options. + +It can also help to compare the XML response from your provider with our [example XML used for internal testing](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/spec/fixtures/saml/response.xml). + ### SSO enforcement > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. @@ -122,7 +135,7 @@ prompts the user to sign in again through SSO. An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. -SSO has the following effects when enabled: +SSO enforcement has the following effects when enabled: - For groups, users can't share a project in the group outside the top-level group, even if the project is forked. @@ -157,8 +170,8 @@ If you have any questions on configuring the SAML app, please contact your provi Follow the Azure documentation on [configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) with the notes below for consideration. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -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). +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 you should follow the [SCIM documentation](scim_setup.md#configure-azure-active-directory). | GitLab Setting | Azure Field | | ------------------------------------ | ------------------------------------------ | @@ -168,7 +181,7 @@ objectID mapping and the [SCIM documentation should be followed](scim_setup.md#a | Identity provider single sign-on URL | Login URL | | Certificate fingerprint | Thumbprint | -The recommended attributes and claims settings are: +The recommended attributes are: - **Unique User Identifier (Name identifier)** set to `user.objectID`. - **nameid-format** set to persistent. @@ -311,6 +324,13 @@ On subsequent visits, you should be able to go [sign in to GitLab.com with SAML] 1. From the list of apps, select the "GitLab.com" app. (The name is set by the administrator of the identity provider.) 1. You are then signed in to GitLab.com and redirected to the group. +### Change NameID for one or more users + +If the NameID changes for one or more users, they need to reconnect their SAML account. + +1. Ask relevant users to [unlink their account from the group](#unlinking-accounts). +1. Ask relevant users to [link their account to the new SAML app](#linking-saml-to-your-existing-gitlabcom-account). + ### Configure user settings from SAML response > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. @@ -357,6 +377,18 @@ convert the information to XML. An example SAML response is shown here. </saml2:AttributeStatement> ``` +### Bypass user email confirmation with verified domains + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4. + +By default, users provisioned with SAML or SCIM are sent a verification email to verify their identity. Instead, you can +[configure GitLab with a custom domain](../../project/pages/custom_domains_ssl_tls_certification/index.md) and GitLab +will automatically confirm user accounts. Users will still receive an enterprise user welcome email. +Confirmation is bypassed for users: + +- That are provisioned with SAML or SCIM. +- That have an email address that belongs to the verified domain. + ### Role Starting from [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523), group owners can set a @@ -412,160 +444,4 @@ The [Generated passwords for users created through integrated authentication](.. ## Troubleshooting -This section contains possible solutions for problems you might encounter. - -### SAML debugging tools - -SAML responses are base64 encoded, so we recommend the following browser plugins to decode them on the fly: - -- [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) for Firefox. -- [SAML Message Decoder](https://chrome.google.com/webstore/detail/saml-message-decoder/mpabchoaimgbdbbjjieoaeiibojelbhm?hl=en) for Chrome. - -Specific attention should be paid to: - -- The [NameID](#nameid), which we use to identify which user is signing in. If the user has previously signed in, this [must match the value we have stored](#verifying-nameid). -- The presence of a `X509Certificate`, which we require to verify the response signature. -- The `SubjectConfirmation` and `Conditions`, which can cause errors if misconfigured. - -#### Generate a SAML Response - -SAML Responses can be used to preview the attribute names and values sent in the assertions list while attempting to sign in using an IdP. - -To generate a SAML Response: - -1. Install either: - - [SAML Chrome Panel](https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace) for Chrome. - - [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) for Firefox. -1. Open a new browser tab. -1. Open the SAML tracer console: - - Chrome: Right-click on the page, select **Inspect**, then select the **SAML** tab in the opened developer console. - - Firefox: Select the SAML-tracer icon located on the browser toolbar. -1. Go to the GitLab single sign-on URL for the group in the same browser tab with the SAML tracer open. -1. Select **Authorize** or attempt to log in. A SAML response is displayed in the tracer console that resembles this - [example SAML response](#example-saml-response). -1. Within the SAML tracer, select the **Export** icon to save the response in JSON format. - -### Verifying configuration - -For convenience, we've included some [example resources](../../../user/group/saml_sso/example_saml_config.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. - -### Verifying NameID - -In troubleshooting the Group SAML setup, any authenticated user can use the API to verify the NameID GitLab already has linked to the user by visiting [`https://gitlab.com/api/v4/user`](https://gitlab.com/api/v4/user) and checking the `extern_uid` under identities. - -Similarly, group members of a role with the appropriate permissions can make use of the [members API](../../../api/members.md) to view group SAML identity information for members of the group. - -This can then be compared to the [NameID](#nameid) being sent by the identity provider by decoding the message with a [SAML debugging tool](#saml-debugging-tools). We require that these match in order to identify users. - -### Users receive a 404 - -Because SAML SSO for groups is a paid feature, your subscription expiring can result in a `404` error when you're signing in using SAML SSO on GitLab.com. -If all users are receiving a `404` when attempting to log in using SAML, confirm -[there is an active subscription](../../../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) being used in this SAML SSO namespace. - -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](#configure-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 needs to provide the URL to users. - -### Message: "SAML authentication failed: Extern UID has already been taken" - -This error suggests you are signed in as a GitLab user but have already linked your SAML identity to a different GitLab user. Sign out and then try to sign in again using the SSO SAML link, which should log you into GitLab with the linked user account. - -If you do not wish to use that GitLab user with the SAML login, you can [unlink the GitLab account from the group's SAML](#unlinking-accounts). - -### 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, or the NameID value has changed. -Here are possible causes and solutions: - -| 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 every time 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 needs to [link their account](#user-access-and-management). | - -User accounts are created in one of the following ways: - -- User registration -- Sign in through OAuth -- Sign in through SAML -- SCIM provisioning - -### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" - -Getting both of these errors at the same time suggests the NameID capitalization provided by the identity provider didn't exactly match the previous value for that user. - -This can be prevented by configuring the [NameID](#nameid) to return a consistent value. Fixing this for an individual user involves [unlinking SAML in the GitLab account](#unlinking-accounts), although this causes group membership and to-do items to be lost. - -### Message: "Request to link SAML account must be authorized" - -Ensure that the user who is trying to link their GitLab account has been added as a user within the identity provider's SAML app. - -Alternatively, the SAML response may be missing the `InResponseTo` attribute in the -`samlp:Response` tag, which is [expected by the SAML gem](https://github.com/onelogin/ruby-saml/blob/9f710c5028b069bfab4b9e2b66891e0549765af5/lib/onelogin/ruby-saml/response.rb#L307-L316). -The identity provider administrator should ensure that the login is -initiated by the service provider and not the identity provider. - -### Message: "Sign in to GitLab to connect your organization's account" - -A user can see this message when they are trying to [manually link SAML to their existing GitLab.com account](#linking-saml-to-your-existing-gitlabcom-account). - -To resolve this problem, the user should check they are using the correct GitLab password to log in. They first need to -[reset their password](https://gitlab.com/users/password/new) if both: - -- The account was provisioned by SCIM. -- This is the first time the user has logged in the username and password. - -### Stuck in a login "loop" - -Ensure that the **GitLab single sign-on URL** has been configured as "Login URL" (or similarly named field) in the identity provider's SAML app. - -Alternatively, when users need to [link SAML to their existing GitLab.com account](#linking-saml-to-your-existing-gitlabcom-account), provide the **GitLab single sign-on URL** and instruct users not to use the SAML app on first sign in. - -### The NameID has changed - -| 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 additional information to configure my identity provider - -Many SAML terms can vary between providers. It is possible that the information you are looking for is listed under another name. - -For more information, start with your identity provider's documentation. Look for their options and examples to see how they configure SAML. This can provide hints on what you need to configure GitLab to work with these providers. - -It can also help to look at our [more detailed docs for self-managed GitLab](../../../integration/saml.md). -SAML configuration for GitLab.com is mostly the same as for self-managed instances. -However, self-managed GitLab instances use a configuration file that supports more options as described in the external [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml/). -Internally that uses the [`ruby-saml` library](https://github.com/onelogin/ruby-saml), so we sometimes check there to verify low level details of less commonly used options. - -It can also help to compare the XML response from your provider with our [example XML used for internal testing](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/spec/fixtures/saml/response.xml). - -### Searching Rails log - -With access to the rails log or `production_json.log` (available only to GitLab team members for GitLab.com), -you should be able to find the base64 encoded SAML response by searching with the following filters: - -- `json.meta.caller_id`: `Groups::OmniauthCallbacksController#group_saml` -- `json.meta.user` or `json.username`: `username` -- `json.method`: `POST` -- `json.path`: `/groups/GROUP-PATH/-/saml/callback` - -In a relevant log entry, the `json.params` should provide a valid response with: - -- `"key": "SAMLResponse"` and the `"value": (full SAML response)`, -- `"key": "RelayState"` with `"value": "/group-path"`, and -- `"key": "group_id"` with `"value": "group-path"`. - -In some cases, if the SAML response is lengthy, you may receive a `"key": "truncated"` with `"value":"..."`. -In these cases, please ask a group owner for a copy of the SAML response from when they select -the "Verify SAML Configuration" button on the group SSO Settings page. - -Use a base64 decoder to see a human-readable version of the SAML response. +See our [troubleshooting SAML guide](troubleshooting.md). diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 7962f171166..a67b2fbe02e 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -5,107 +5,129 @@ group: Authentication and Authorization 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 --- -# SCIM provisioning using SAML SSO for GitLab.com groups **(PREMIUM SAAS)** +# Configure SCIM for GitLab.com groups **(PREMIUM SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab 11.10. -System for Cross-domain Identity Management (SCIM), is an open standard that enables the -automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of -that group is synchronized between GitLab and the identity provider. +You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically: -The GitLab [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). - -## Features +- Create users. +- Remove users (deactivate SCIM identity). -The following actions are available: +GitLab SAML SSO SCIM doesn't support updating users. -- Create users -- Remove users (deactivate SCIM identity) +When SCIM is enabled for a GitLab group, membership of that group is synchronized between GitLab and an identity provider. -The following identity providers are supported: - -- Azure -- Okta +The GitLab [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). -## Requirements +## Configure GitLab -- [Group Single Sign-On](index.md) must be configured. +Prerequisites: -## GitLab configuration +- [Group single sign-on](index.md) must be configured. -Once [Group Single Sign-On](index.md) has been configured, we can: +To configure GitLab SAML SSO SCIM: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > SAML SSO**. 1. Select **Generate a SCIM token**. -1. Save the token and URL for use in the next step. +1. For configuration of your identity provider, save the: + - Token from the **Your SCIM token** field. + - URL from the **SCIM API endpoint URL** field. - +## Configure an identity provider -## Identity Provider configuration +You can configure one of the following as an identity provider: -- [Azure](#azure-configuration-steps) -- [Okta](#okta-configuration-steps) +- [Azure Active Directory](#configure-azure-active-directory). +- [Okta](#configure-okta). +- [OneLogin](#configure-onelogin). -### Azure configuration steps +NOTE: +Other providers can work with GitLab but they have not been tested and are not supported. -The SAML application that was created during [Single sign-on](index.md) setup for [Azure](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) now needs to be set up for SCIM. You can refer to [Azure SCIM setup documentation](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#getting-started). +### Configure Azure Active Directory -1. In your app, go to the Provisioning tab, and set the **Provisioning Mode** to **Automatic**. - Then fill in the **Admin Credentials**, and save. The **Tenant URL** and **secret token** are the items - retrieved in the [previous step](#gitlab-configuration). +The SAML application created during [single sign-on](index.md) set up for +[Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) +must be set up for SCIM. For an example, see [example configuration](example_saml_config.md#scim-mapping). -1. After saving, two more tabs appear: +To configure Azure Active Directory for SCIM: - - **Settings**: We recommend setting a notification email and selecting the **Send an email notification when a failure occurs** checkbox. - You also control what is actually synced by selecting the **Scope**. For example, **Sync only assigned users and groups** only syncs the users and groups assigned to the application. Otherwise, it syncs the whole Active Directory. +1. In your app, go to the **Provisioning** tab and select **Get started**. +1. Set the **Provisioning Mode** to **Automatic**. +1. Complete the **Admin Credentials** using the value of: + - **SCIM API endpoint URL** in GitLab for the **Tenant URL** field. + - **Your SCIM token** in GitLab for the **Secret Token** field. +1. Select **Test Connection**. If the test is successful, save your configuration before continuing, or see the + [troubleshooting](#troubleshooting) information. +1. Select **Save**. - - **Mappings**: We recommend keeping **Provision Azure Active Directory Users** enabled, and disable **Provision Azure Active Directory Groups**. - Leaving **Provision Azure Active Directory Groups** enabled does not break the SCIM user provisioning, but it causes errors in Azure AD that may be confusing and misleading. +After saving, **Settings** and **Mappings** sections appear. + +1. Under **Settings**, if required, set a notification email and select the + **Send an email notification when a failure occurs** checkbox. +1. Under **Mappings**, we recommend you: + 1. Keep **Provision Azure Active Directory Users** enabled and select the **Provision Azure Active Directory Users** + link to [configure attribute mappings](#configure-attribute-mappings). + 1. Below the mapping list select the **Show advanced options** checkbox. + 1. Select the **Edit attribute list for customappsso** link. + 1. Ensure the `id` is the primary and required field, and `externalId` is also required. + 1. Select **Save**. +1. Return to the **Provisioning** tab, saving unsaved changes if necessary. +1. Select **Edit attribute mappings**. +1. Under **Mappings**: + 1. Select **Provision Azure Active Directory Groups**. + 1. On the Attribute Mapping page, turn off the **Enabled** toggle. Leaving it turned on doesn't break the SCIM user + provisioning, but it causes errors in Azure Active Directory that may be confusing and misleading. + 1. Select **Save**. +1. Return to the **Provisioning** tab, saving unsaved changes if necessary. +1. Select **Edit attribute mappings**. +1. Turn on the **Provisioning Status** toggle. Synchronization details and any errors appears on the bottom of the + **Provisioning** screen, together with a link to the audit events. -1. You can then test the connection by selecting **Test Connection**. If the connection is successful, save your configuration before moving on. See below for [troubleshooting](#troubleshooting). +WARNING: +Once synchronized, changing the field mapped to `id` and `externalId` may cause a number of errors. These include +provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group. -#### Configure attribute mapping +#### Configure attribute mappings -Follow [Azure documentation to configure the attribute mapping](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes). +While [configuring Azure Active Directory for SCIM](#configure-azure-active-directory), you configure attribute mappings. +For an example, see [example configuration](example_saml_config.md#scim-mapping). -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. In particular, the `externalId` must -match the [SAML NameID](index.md#nameid). -If a mapping is not listed in the table, use the Azure defaults. -For a list of required attributes, refer to the [SCIM API documentation](../../../api/scim.md). +The following table provides attribute mappings known to work with GitLab. -| Azure Active Directory Attribute | `customappsso` Attribute | Matching precedence | -| -------------------------------- | ------------------------------ | ------------------- | -| `objectId` | `externalId` | 1 | -| `userPrincipalName` | `emails[type eq "work"].value` | | -| `mailNickname` | `userName` | | +| Source attribute | Target attribute | Matching precedence | +|:--------------------|:-------------------------------|:--------------------| +| `objectId` | `externalId` | 1 | +| `userPrincipalName` | `emails[type eq "work"].value` | | +| `mailNickname` | `userName` | | -For guidance, you can view [an example configuration](example_saml_config.md#azure-active-directory). +Each attribute mapping has: -1. Below the mapping list select **Show advanced options > Edit attribute list for AppName**. -1. Ensure the `id` is the primary and required field, and `externalId` is also required. +- An Azure Active Directory attribute (source attribute). +- A `customappsso` attribute (target attribute). +- A matching precedence. - NOTE: - `username` should neither be primary nor required as we don't support - that field on GitLab SCIM yet. +For each attribute: -1. Save all changes. -1. In the **Provisioning** step, set the `Provisioning Status` to `On`. +1. Select the attribute to edit it. +1. Select the required settings. +1. Select **Ok**. -Once enabled, the synchronization details and any errors appears on the -bottom of the **Provisioning** screen, together with a link to the audit events. +If your SAML configuration differs from [the recommended SAML settings](index.md#azure-setup-notes), select the mapping +attributes and modify them accordingly. In particular, the `objectId` source attribute must map to the `externalId` +target attribute. -WARNING: -Once synchronized, changing the field mapped to `id` and `externalId` may cause a number of errors. These include provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group. +If a mapping is not listed in the table, use the Azure Active Directory defaults. For a list of required attributes, +refer to the [SCIM API documentation](../../../api/scim.md). -### Okta configuration steps +### Configure Okta Before you start this section: - Check that you are using Okta [Lifecycle Management](https://www.okta.com/products/lifecycle-management/) product. This product tier is required to use SCIM on Okta. To check which Okta product you are using, check your signed Okta contract, contact your Okta AE, CSM, or Okta support. -- Complete the [GitLab configuration](#gitlab-configuration) process. +- Complete the [GitLab configuration](#configure-gitlab) process. - Complete the setup for SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/), as described in the [Okta setup notes](index.md#okta-setup-notes). - Check that your Okta SAML setup matches our documentation exactly, especially the NameID configuration. Otherwise, the Okta SCIM app may not work properly. @@ -137,7 +159,7 @@ The Okta GitLab application currently only supports SCIM. Continue using the separate Okta [SAML SSO](index.md) configuration along with the new SCIM application described above. An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/216173) to add SAML support to the Okta GitLab application. -### OneLogin +### Configure OneLogin As the developers of this app, OneLogin provides a "GitLab (SaaS)" app in their catalog, which includes a SCIM integration. Please reach out to OneLogin if you encounter issues. @@ -216,17 +238,17 @@ The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenev This value is also used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. -It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](index.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](index.md#troubleshooting). +It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](troubleshooting.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](troubleshooting.md). ### How do I verify user's SAML NameId matches the SCIM externalId -Admins can use the Admin Area to [list SCIM identities for a user](../../admin_area/#user-identities). +Admins can use the Admin Area to [list SCIM identities for a user](../../admin_area/index.md#user-identities). Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. A possible alternative is to use the [SCIM API](../../../api/scim.md#get-a-list-of-scim-provisioned-users) to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`. -To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](index.md#saml-debugging-tools). +To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools). ### Update or fix mismatched SCIM externalId and SAML NameId @@ -241,7 +263,7 @@ that provider may create duplicate users. If the `externalId` for a user is not correct, and also doesn't match the SAML NameID, you can address the problem in the following ways: -- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](index.md#message-saml-authentication-failed-user-has-already-been-taken) section. +- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](troubleshooting.md#message-saml-authentication-failed-user-has-already-been-taken) section. - You can unlink all users simultaneously, by removing all users from the SAML app while provisioning is turned on. - It may be possible to use the [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) to manually correct the `externalId` stored for users to match the SAML `NameId`. To look up a user, you need to know the desired value that matches the `NameId` as well as the current `externalId`. @@ -314,4 +336,4 @@ and the error response can include a HTML result of the GitLab URL `https://gitl This error is harmless and occurs because Group provisioning was turned on but GitLab SCIM integration does not support it nor require it. To remove the error, follow the instructions in the Azure configuration guide to disable the option -[`Synchronize Azure Active Directory Groups to AppName`](#azure-configuration-steps). +[`Synchronize Azure Active Directory Groups to AppName`](#configure-azure-active-directory). diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md new file mode 100644 index 00000000000..177f33228c0 --- /dev/null +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -0,0 +1,249 @@ +--- +type: reference +stage: Manage +group: Authentication and Authorization +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 +--- + +# Troubleshooting SAML **(FREE)** + +This page contains possible solutions for problems you might encounter when using: + +- [SAML SSO for GitLab.com groups](index.md). +- The self-managed instance-level [SAML OmniAuth Provider](../../../integration/saml.md). + +## SAML debugging tools + +SAML responses are base64 encoded, so we recommend the following browser plugins to decode them on the fly: + +- [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) for Firefox. +- [SAML Message Decoder](https://chrome.google.com/webstore/detail/saml-message-decoder/mpabchoaimgbdbbjjieoaeiibojelbhm?hl=en) for Chrome. + +Specific attention should be paid to: + +- The NameID, which we use to identify which user is signing in. If the user has previously signed in, this [must match the value we have stored](#verifying-nameid). +- The presence of a `X509Certificate`, which we require to verify the response signature. +- The `SubjectConfirmation` and `Conditions`, which can cause errors if misconfigured. + +### Generate a SAML response + +Use SAML responses to preview the attribute names and values sent in the assertions list while attempting to sign in +using an identity provider. + +To generate a SAML Response: + +1. Install one of the browser debugging tools previously mentioned. +1. Open a new browser tab. +1. Open the SAML tracer console: + - Chrome: On a context menu on the page, select **Inspect**, then select the **SAML** tab in the opened developer + console. + - Firefox: Select the SAML-tracer icon located on the browser toolbar. +1. Go to the GitLab single sign-on URL for the group in the same browser tab with the SAML tracer open. +1. Select **Authorize** or attempt to log in. A SAML response is displayed in the tracer console that resembles this + [example SAML response](index.md#example-saml-response). +1. Within the SAML tracer, select the **Export** icon to save the response in JSON format. + +## GitLab SAML Testing Environments + +To troubleshoot, [a complete GitLab with SAML testing environment using Docker compose](https://gitlab.com/gitlab-com/support/toolbox/replication/tree/master/compose_files) +is available. + +If you only require a SAML provider for testing, a [quick start guide to start a Docker container](../../../administration/troubleshooting/test_environments.md#saml) with a plug and play SAML 2.0 Identity Provider (identity provider) is available. + +You can test the SaaS feature locally by [enabling SAML for groups on a self-managed instance](../../../integration/saml.md#configuring-group-saml-on-a-self-managed-gitlab-instance). + +## Verifying configuration + +For convenience, we've included some [example resources](../../../user/group/saml_sso/example_saml_config.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. + +## Searching Rails log for a SAML response **(FREE SELF)** + +You can find the base64-encoded SAML Response in the [`production_json.log`](../../../administration/logs/index.md#production_jsonlog). +This response is sent from the identity provider, and contains user information that is consumed by GitLab. +Many errors in the SAML integration can be solved by decoding this response and comparing it to the SAML settings in the GitLab configuration file. + +For example, with SAML for groups, +you should be able to find the base64 encoded SAML response by searching with the following filters: + +- `json.meta.caller_id`: `Groups::OmniauthCallbacksController#group_saml` +- `json.meta.user` or `json.username`: `username` +- `json.method`: `POST` +- `json.path`: `/groups/GROUP-PATH/-/saml/callback` + +In a relevant log entry, the `json.params` should provide a valid response with: + +- `"key": "SAMLResponse"` and the `"value": (full SAML response)`, +- `"key": "RelayState"` with `"value": "/group-path"`, and +- `"key": "group_id"` with `"value": "group-path"`. + +In some cases, if the SAML response is lengthy, you may receive a `"key": "truncated"` with `"value":"..."`. +In these cases, use one of the [SAML debugging tools](#saml-debugging-tools), or for SAML SSO for groups, +a group owner can get a copy of the SAML response from when they select +the "Verify SAML Configuration" button on the group SSO Settings page. + +Use a base64 decoder to see a human-readable version of the SAML response. + +## Configuration errors + +### Invalid audience + +This error means that the identity provider doesn't recognize GitLab as a valid sender and +receiver of SAML requests. Make sure to: + +- Add the GitLab callback URL to the approved audiences of the identity provider server. +- Avoid trailing whitespace in the `issuer` string. + +### Key validation error, Digest mismatch or Fingerprint mismatch + +These errors all come from a similar place, the SAML certificate. SAML requests +must be validated using either a fingerprint, a certificate, or a validator. + +For this requirement, be sure to take the following into account: + +- If a fingerprint is used, it must be the SHA1 fingerprint +- If no certificate is provided in the settings, a fingerprint or fingerprint + validator needs to be provided and the response from the server must contain + a certificate (`<ds:KeyInfo><ds:X509Data><ds:X509Certificate>`) +- If a certificate is provided in the settings, it is no longer necessary for + the request to contain one. In this case the fingerprint or fingerprint + validators are optional + +If none of the above described scenarios is valid, the request +fails with one of the mentioned errors. + +### Missing claims, or `Email can't be blank` errors + +The identity provider server needs to pass certain information in order for GitLab to either +create an account, or match the login information to an existing account. `email` +is the minimum amount of information that needs to be passed. If the identity provider server +is not providing this information, all SAML requests fail. + +Make sure this information is provided. + +Another issue that can result in this error is when the correct information is being sent by +the identity provider, but the attributes don't match the names in the OmniAuth `info` hash. In this case, +you must set `attribute_statements` in the SAML configuration to +[map the attribute names in your SAML Response to the corresponding OmniAuth `info` hash names](../../../integration/saml.md#attribute_statements). + +## User sign in banner error messages + +### Message: "SAML authentication failed: Extern UID has already been taken" + +This error suggests you are signed in as a GitLab user but have already linked your SAML identity to a different GitLab user. Sign out and then try to sign in again using SAML, which should log you into GitLab with the linked user account. + +If you do not wish to use that GitLab user with the SAML login, you can [unlink the GitLab account from the SAML app](index.md#unlinking-accounts). + +### 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, or the NameID value has changed. +Here are possible causes and solutions: + +| 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](index.md#unlinking-accounts) from this GitLab account before attempting to sign in again. | +| The NameID changes every time the user requests SSO identification | [Check the NameID](#verifying-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 needs to [link their account](index.md#user-access-and-management). | + +User accounts are created in one of the following ways: + +- User registration +- Sign in through OAuth +- Sign in through SAML +- SCIM provisioning + +### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" + +Getting both of these errors at the same time suggests the NameID capitalization provided by the identity provider didn't exactly match the previous value for that user. + +This can be prevented by configuring the NameID to return a consistent value. Fixing this for an individual user involves changing the identifier for the user. For GitLab.com, the user needs to [unlink their SAML from the GitLab account](index.md#unlinking-accounts). + +### Message: "Request to link SAML account must be authorized" + +Ensure that the user who is trying to link their GitLab account has been added as a user within the identity provider's SAML app. + +Alternatively, the SAML response may be missing the `InResponseTo` attribute in the +`samlp:Response` tag, which is [expected by the SAML gem](https://github.com/onelogin/ruby-saml/blob/9f710c5028b069bfab4b9e2b66891e0549765af5/lib/onelogin/ruby-saml/response.rb#L307-L316). +The identity provider administrator should ensure that the login is +initiated by the service provider and not only the identity provider. + +### Message: "Sign in to GitLab to connect your organization's account" **(PREMIUM SAAS)** + +A user can see this message when they are trying to [manually link SAML to their existing GitLab.com account](index.md#linking-saml-to-your-existing-gitlabcom-account). + +To resolve this problem, the user should check they are using the correct GitLab password to log in. The user first needs +to [reset their password](https://gitlab.com/users/password/new) if both: + +- The account was provisioned by SCIM. +- They are signing in with username and password for the first time. + +## Other user sign in issues + +### Verifying NameID + +In troubleshooting, any authenticated user can use the API to verify the NameID GitLab already has linked to the user by visiting [`https://gitlab.com/api/v4/user`](https://gitlab.com/api/v4/user) and checking the `extern_uid` under identities. + +For self-managed, administrators can use the [users API](../../../api/users.md) to see the same information. + +When using SAML for groups, group members of a role with the appropriate permissions can make use of the [members API](../../../api/members.md) to view group SAML identity information for members of the group. + +This can then be compared to the NameID being sent by the identity provider by decoding the message with a [SAML debugging tool](#saml-debugging-tools). We require that these match in order to identify users. + +### Stuck in a login "loop" + +Ensure that the **GitLab single sign-on URL** (for GitLab.com) or the instance URL (for self-managed) has been configured as "Login URL" (or similarly named field) in the identity provider's SAML app. + +For GitLab.com, alternatively, when users need to [link SAML to their existing GitLab.com account](index.md#linking-saml-to-your-existing-gitlabcom-account), provide the **GitLab single sign-on URL** and instruct users not to use the SAML app on first sign in. + +### Users receive a 404 **(PREMIUM SAAS)** + +Because SAML SSO for groups is a paid feature, your subscription expiring can result in a `404` error when you're signing in using SAML SSO on GitLab.com. +If all users are receiving a `404` when attempting to log in using SAML, confirm +[there is an active subscription](../../../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) being used in this SAML SSO namespace. + +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](index.md#configure-your-identity-provider), they may see a 404. +As outlined in the [user access section](index.md#linking-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users. + +### 500 error after login **(FREE SELF)** + +If you see a "500 error" in GitLab when you are redirected back from the SAML +sign-in page, this could indicate that: + +- GitLab couldn't get the email address for the SAML user. Ensure the identity provider provides a claim containing the user's + email address using the claim name `email` or `mail`. +- The certificate set your `gitlab.rb` file for `identity provider_cert_fingerprint` or `identity provider_cert` file is incorrect. +- Your `gitlab.rb` file is set to enable `identity provider_cert_fingerprint`, and `identity provider_cert` is being provided, or the reverse. + +### 422 error after login **(FREE SELF)** + +If you see a "422 error" in GitLab when you are redirected from the SAML +sign-in page, you might have an incorrectly configured Assertion Consumer +Service (ACS) URL on the identity provider. + +Make sure the ACS URL points to `https://gitlab.example.com/users/auth/saml/callback`, where +`gitlab.example.com` is the URL of your GitLab instance. + +If the ACS URL is correct, and you still have errors, review the other +Troubleshooting sections. + +### User is blocked when signing in through SAML **(FREE SELF)** + +The following are the most likely reasons that a user is blocked when signing in through SAML: + +- In the configuration, `gitlab_rails['omniauth_block_auto_created_users'] = true` is set and this is the user's first time signing in. +- [`required_groups`](../../../integration/saml.md#required-groups) are configured but the user is not a member of one. + +## Google workspace troubleshooting tips + +The Google Workspace documentation on [SAML app error messages](https://support.google.com/a/answer/6301076?hl=en) is helpful for debugging if you are seeing an error from Google while signing in. +Pay particular attention to the following 403 errors: + +- `app_not_configured` +- `app_not_configured_for_user` diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index c3098bb56c2..eb9c6af9edf 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -27,6 +27,13 @@ associated with a group rather than a project or user. In self-managed instances, group access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. +WARNING: +The ability to create group access tokens without expiry was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and is planned for removal in GitLab +16.0. When this ability is removed, existing group access tokens without an expiry are planned to have an expiry added. +The automatic adding of an expiry occurs on GitLab.com during the 16.0 milestone. The automatic adding of an expiry +occurs on self-managed instances when they are upgraded to GitLab 16.0. This change is a breaking change. + You can use group access tokens: - On GitLab SaaS if you have the Premium license tier or higher. Group access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). @@ -43,11 +50,12 @@ configured for personal access tokens. ## Create a group access token using UI -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days and default role of Guest is populated in the UI. To create a group access token: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the group. 1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. @@ -104,7 +112,7 @@ or API. However, administrators can use a workaround: To revoke a group access token: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > Access Tokens**. 1. Next to the group access token to revoke, select **Revoke**. @@ -138,7 +146,7 @@ The scope determines the actions you can perform when you authenticate with a gr To enable or disable group access token creation for all sub-groups in a top-level group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Users can create project access tokens and group access tokens in this group**. @@ -154,8 +162,9 @@ to groups instead of projects. Bot users for groups: - Do not count as licensed seats. - Can have a maximum role of Owner for a group. For more information, see [Create a group access token](../../../api/group_access_tokens.md#create-a-group-access-token). -- The username is set to `group_{project_id}_bot` for the first access token. For example, `project_123_bot`. -- The email is set to `group{group_id}_bot@noreply.{Gitlab.config.gitlab.host}`. For example, `group123_bot@noreply.example.com`. -- All other properties are similar to [bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects) +- Have a username set to `group_{group_id}_bot` for the first access token. For example, `group_123_bot`. +- Have an email set to `group{group_id}_bot@noreply.{Gitlab.config.gitlab.host}`. For example, `group123_bot@noreply.example.com`. + +All other properties are similar to [bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects). For more information, see [Bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects). diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index eb94a181647..7a398c7d086 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -28,7 +28,7 @@ Prerequisite: To enable import and export for a group: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility and access controls**. 1. In the **Import sources** section, select the checkboxes for the sources you want. @@ -44,6 +44,7 @@ be imported into the desired group structure. - If imported into a parent group, a subgroup inherits the same level of visibility unless otherwise restricted. - To preserve the member list and their respective permissions on imported groups, review the users in these groups. Make sure these users exist before importing the desired groups. +- Users must set a public email in the source GitLab instance that matches one of their verified emails in the target GitLab instance. ### Exported contents @@ -55,6 +56,7 @@ The following items are exported: - Badges - Subgroups (including all the aforementioned data) - Epics + - Epic resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Events - [Wikis](../../project/wiki/group.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9) @@ -77,7 +79,7 @@ Prerequisites: To export the contents of a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. In the **Advanced** section, select **Export Group**. 1. After the export is generated, you should receive an email with a link to the [exported contents](#exported-contents) diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 12434de5efc..657ef361bd5 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -56,7 +56,7 @@ the private subgroup. To view the subgroups of a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. Select the **Subgroups and projects** tab. 1. To view a nested subgroup, expand a subgroup in the hierarchy list. @@ -84,7 +84,7 @@ You cannot host a GitLab Pages subgroup website with a top-level domain name. Fo To create a subgroup: -1. On the top bar, select **Menu > Groups** and find and select the parent group to add a subgroup to. +1. On the top bar, select **Main menu > Groups** and find and select the parent group to add a subgroup to. 1. On the parent group's overview page, in the top right, select **New subgroup**. 1. Select **Create group**. 1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) that cannot be used as group names. @@ -98,13 +98,13 @@ default: To change who can create subgroups on a group: - As a user with the Owner role on the group: - 1. On the top bar, select **Menu > Groups** and find your group. + 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. Select a role from **Roles allowed to create subgroups**. 1. Select **Save changes**. - As an administrator: - 1. On the top bar, select **Menu > Admin**. + 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. 1. In the group's row select **Edit**. 1. Select a role from **Allowed to create subgroups**. @@ -159,7 +159,7 @@ Group permissions for a member can be changed only by: To see if a member has inherited the permissions from a parent group: -1. On the top bar, select **Menu > Groups** and find the group. +1. On the top bar, select **Main menu > Groups** and find the group. 1. Select **Group information > Members**. Members list for an example subgroup _Four_: @@ -201,7 +201,7 @@ role on an ancestor group, add the user to the subgroup again with a higher role ## Mention subgroups Mentioning subgroups ([`@<subgroup_name>`](../../discussions/index.md#mentions)) in issues, commits, and merge requests -notifies all members of that group. Mentioning works the same as for projects and groups, and you can choose the group +notifies all direct members of that group. Inherited members of a sub-group are not notified by mentions. Mentioning works the same as for projects and groups, and you can choose the group of people to be notified. <!-- ## Troubleshooting diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 3e41b7b63cc..9078874d32c 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -35,7 +35,7 @@ Prerequisite: To view value stream analytics for your group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. 1. To view metrics for a particular stage, select a stage below the **Filter results** text box. 1. Optional. Filter the results: @@ -73,7 +73,7 @@ To view deployment metrics, you must have a To view the DORA metrics and key metrics: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. 1. Optional. Filter the results: 1. Select the **Filter results** text box. @@ -125,7 +125,7 @@ In GitLab 13.8 and earlier, deployment frequency metrics are calculated based on ### How value stream analytics aggregates data -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335391) in GitLab 14.5 [with a flag](../../../administration/feature_flags.md) named `use_vsa_aggregated_tables`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335391) in GitLab 14.5. > - Filter by stop date toggle [added](https://gitlab.com/gitlab-org/gitlab/-/issues/352428) in GitLab 14.9 > - Data refresh badge [added](https://gitlab.com/gitlab-org/gitlab/-/issues/341739) in GitLab 14.9 > - Filter by stop date toggle [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84356) in GitLab 14.9 @@ -154,7 +154,7 @@ Value stream analytics shows the median time spent by issues or merge requests i To view the median time spent in each stage by a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. 1. Optional. Filter the results: 1. Select the **Filter results** text box. @@ -251,7 +251,7 @@ You can change the name of a project environment in your GitLab CI/CD configurat When you create a value stream, you can use GitLab default stages and hide or re-order them to customize. You can also create custom stages in addition to those provided in the default template. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. 1. Select **Create new Value Stream**. 1. Enter a name for the value stream. @@ -275,7 +275,7 @@ If you have recently upgraded to GitLab Premium, it can take up to 30 minutes fo When you create a value stream, you can create and add custom stages that align with your own development workflows. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. 1. Select **Create value stream**. 1. For each stage: @@ -301,7 +301,7 @@ time from a staging environment to production, you could use the following label After you create a value stream, you can customize it to suit your purposes. To edit a value stream: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. 1. In the top right, select the dropdown list, and select a value stream. 1. Next to the value stream dropdown list, select **Edit**. @@ -320,7 +320,7 @@ After you create a value stream, you can customize it to suit your purposes. To To delete a custom value stream: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. 1. In the top right, select the dropdown list and then select the value stream you would like to delete. 1. Select **Delete (name of value stream)**. @@ -336,7 +336,7 @@ To delete a custom value stream: The **Total time chart** shows the average number of days it takes for development cycles to complete. The chart shows data for the last 500 workflow items. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. 1. Above the **Filter results** box, select a stage: - To view a summary of the cycle time for all stages, select **Overview**. @@ -349,13 +349,19 @@ The chart shows data for the last 500 workflow items. - In the **From** field, select a start date. - In the **To** field, select an end date. -## Tasks by type chart +## View tasks by type -This chart shows a cumulative count of issues and merge requests per day. +The **Tasks by type** chart displays the cumulative number of issues and merge requests per day for your group. -This chart uses the global page filters for displaying data based on the selected -group, projects, and time frame. The chart defaults to showing counts for issues but can be -toggled to show data for merge requests and further refined for specific group-level labels. +The chart uses the global page filters to display data based on the selected +group, projects, and time frame. -By default the top group-level labels (max. 10) are pre-selected, with the ability to -select up to a total of 15 labels. +To view tasks by type: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. +1. Below the **Filter results** text box, select **Overview**. The **Tasks by type** chart displays below the **Total time** chart. +1. To switch between the task type, select the **Settings** (**{settings}**) dropdown list + and select **Issues** or **Merge Requests**. +1. To add or remove labels, select the **Settings** (**{settings}**) dropdown list + and select or search for a label. By default the top group-level labels (maximum 10) are selected. You can select a maximum of 15 labels. diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 37e1024a32c..af728cb5c21 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -34,17 +34,17 @@ your cluster's level. **Project-level clusters:** -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. **Group-level clusters:** -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Kubernetes**. **Instance-level clusters:** -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Kubernetes**. ## Security implications for clusters connected with certificates diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md index ecf93958b1e..f9feef6329c 100644 --- a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create a Civo Kubernetes cluster -Every new Civo account receives [$250 in credit](https://civo.com/signup) to get started with the GitLab integration with Civo Kubernetes. You can also use a marketplace app to install GitLab on your Civo Kubernetes cluster. +Every new Civo account receives [$250 in credit](https://dashboard.civo.com/signup) to get started with the GitLab integration with Civo Kubernetes. You can also use a marketplace app to install GitLab on your Civo Kubernetes cluster. Learn how to create a new cluster on Civo Kubernetes through [Infrastructure as Code (IaC)](../../index.md). This process uses the Civo @@ -15,7 +15,7 @@ by using the GitLab agent for Kubernetes. **Prerequisites:** -- A [Civo account](https://civo.com/signup). +- A [Civo account](https://dashboard.civo.com/signup). - [A runner](https://docs.gitlab.com/runner/install/) you can use to run the GitLab CI/CD pipeline. **Steps:** @@ -35,7 +35,8 @@ Start by [importing the example project by URL](../../../project/import/repo_by_ To import the project: -1. On the top bar, select **Menu > Create new project**. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Import project**. 1. Select **Repository by URL**. 1. For the **Git repository URL**, enter `https://gitlab.com/civocloud/gitlab-terraform-civo.git`. @@ -64,7 +65,7 @@ Use CI/CD environment variables to configure your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Variables**. -1. Set the variable `BASE64_CIVO_TOKEN` to the [token](https://www.civo.com/account/security) from your Civo account. +1. Set the variable `BASE64_CIVO_TOKEN` to the token from your Civo account. 1. Set the variable `TF_VAR_agent_token` to the agent token you received in the previous task. 1. Set the variable `TF_VAR_kas_address` to the agent server address in the previous task. @@ -95,7 +96,7 @@ After configuring your project, manually trigger the provisioning of your cluste When the pipeline finishes successfully, you can see your new cluster: -- In Civo dashboard: on your [Kubernetes tab](https://www.civo.com/account/kubernetes). +- In Civo dashboard: on your Kubernetes tab. - In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**. ## Use your cluster diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 2f5967bd7ee..126968baee7 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -34,7 +34,8 @@ Start by [importing the example project by URL](../../../project/import/repo_by_ To import the project: -1. On the top bar, select **Menu > Create new project**. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Import project**. 1. Select **Repository by URL**. 1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks.git`. @@ -82,7 +83,6 @@ contains other variables that you can override according to your needs: - `TF_VAR_cluster_version`: Set the version of Kubernetes. - `TF_VAR_instance_type`: Set the instance type for the Kubernetes nodes. - `TF_VAR_instance_count`: Set the number of Kubernetes nodes. -- `TF_VAR_agent_version`: Set the version of the GitLab agent. - `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab agent. View the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options. diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 07d0c722d8b..a23a9e7a6e5 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -41,7 +41,8 @@ Start by [importing the example project by URL](../../../project/import/repo_by_ To import the project: -1. On the top bar, select **Menu > Create new project**. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Import project**. 1. Select **Repository by URL**. 1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git`. @@ -107,7 +108,6 @@ contains other variables that you can override according to your needs: - `TF_VAR_cluster_description`: Set a description for the cluster. We recommend setting this to `$CI_PROJECT_URL` to create a reference to your GitLab project on your GCP cluster detail page. This way you know which project was responsible for provisioning the cluster you see on the GCP dashboard. - `TF_VAR_machine_type`: Set the machine type for the Kubernetes nodes. - `TF_VAR_node_count`: Set the number of Kubernetes nodes. -- `TF_VAR_agent_version`: Set the version of the GitLab agent. - `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab agent. Refer to the [Google Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options. 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 51fd626ce0f..5f77b7e402a 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -30,8 +30,8 @@ And update the `applications/cert-manager/helmfile.yaml` with a valid email addr ``` NOTE: -If your Kubernetes version is earlier than 1.20 and you are -[migrating from GitLab Managed Apps to a cluster management project](../../../../clusters/migrating_from_gma_to_project_template.md), +If your Kubernetes version is earlier than 1.20 and you are +[migrating from GitLab Managed Apps to a cluster management project](../../../../clusters/migrating_from_gma_to_project_template.md), then you can instead use `- path: applications/cert-manager-legacy/helmfile.yaml` to take over an existing release of cert-manager v0.10. diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 422552c5b71..d5eabb9ba46 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -64,7 +64,7 @@ In each GitLab major release (for example, 15.0), the latest templates replace t To use a Terraform template: -1. On the top bar, select **Menu > Projects** and find the project you want to integrate with Terraform. +1. On the top bar, select **Main menu > Projects** and find the project you want to integrate with Terraform. 1. On the left sidebar, select **Repository > Files**. 1. Edit your `.gitlab-ci.yml` file, use the `include` attribute to fetch the Terraform template: diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 4e78e0bbed5..d4fea6b7dba 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. Terraform uses state files to store details about your infrastructure configuration. -With Terraform remote [backends](https://www.terraform.io/language/settings/backends), +With Terraform remote [backends](https://www.terraform.io/language/settings/backends/configuration), you can store the state file in a remote and shared store. GitLab provides a [Terraform HTTP backend](https://www.terraform.io/language/settings/backends/http) @@ -109,7 +109,7 @@ inconsistent. Instead, use a remote storage resource. [initialized for CI/CD](#initialize-a-terraform-state-as-a-backend-by-using-gitlab-cicd). 1. Copy a pre-populated Terraform `init` command: - 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Infrastructure > Terraform**. 1. Next to the environment you want to use, select **Actions** (**{ellipsis_v}**) and select **Copy Terraform init command**. @@ -287,7 +287,7 @@ To read the Terraform state in the target project, you need at least the Develop To view Terraform state files: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Infrastructure > Terraform**. [An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/4563) to track improvements to this UI. diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index e187fe54136..3286b550507 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -97,9 +97,7 @@ As a result, to create a plan and later use the same plan in another CI job, you `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. -Another possible error message for the same problem could be: `Error: Error loading state: HTTP remote state endpoint requires auth`. - -As a workaround, use [http backend configuration variables](https://www.terraform.io/docs/language/settings/backends/http.html#configuration-variables) in your CI job, +As a workaround, use [http backend configuration variables](https://www.terraform.io/language/settings/backends/http#configuration-variables) in your CI job, which is what happens behind the scenes when following the [Get started using GitLab CI](terraform_state.md#initialize-a-terraform-state-as-a-backend-by-using-gitlab-cicd) instructions. @@ -112,8 +110,8 @@ If you don't set `TF_STATE_NAME` or `TF_ADDRESS` in your job, the job fails with To resolve this, ensure that either `TF_ADDRESS` or `TF_STATE_NAME` is accessible in the job that returned the error: -1. Configure the [CI/CD environment scope](../../../ci/variables/#add-a-cicd-variable-to-a-project) for the job. -1. Set the job's [environment](../../../ci/yaml/#environment), matching the environment scope from the previous step. +1. Configure the [CI/CD environment scope](../../../ci/variables/index.md#add-a-cicd-variable-to-a-project) for the job. +1. Set the job's [environment](../../../ci/yaml/index.md#environment), matching the environment scope from the previous step. ### Error refreshing state: HTTP remote state endpoint requires auth diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index a5c1402b9ec..27aa3479b88 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -21,7 +21,7 @@ projects. To view the instance level Kubernetes clusters: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Kubernetes**. ## Cluster precedence diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 6a524fe206a..d61190fbd31 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -346,10 +346,13 @@ backslash `\`. Otherwise the diff highlight does not render correctly: [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#math). Math written in LaTeX syntax is rendered with [KaTeX](https://github.com/KaTeX/KaTeX). +_KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._ +This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see +the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). -Math written between dollar signs `$` is rendered inline with the text. Math written -in a [code block](#code-spans-and-blocks) with the language declared as `math` is rendered -on a separate line: +Math written between dollar signs with backticks (``$`...`$``) is rendered +inline with the text. Math written in a [code block](#code-spans-and-blocks) with +the language declared as `math` is rendered on a separate line: ````markdown This math is inline: $`a^2+b^2=c^2`$. @@ -369,10 +372,44 @@ This math is on a separate line: a^2+b^2=c^2 ``` -_KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._ +#### LaTeX-compatible fencing -This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see -the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). +> Introduced in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `markdown_dollar_math`. Disabled by default. + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#latex-compatible-fencing). + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `markdown_dollar_math`. +On GitLab.com, this feature is available. +The feature is not ready for production use. + +Math written between dollar signs (`$...$`) is rendered +inline with the text. Math written between double dollar signs (`$$...$$`) is rendered +on a separate line: + +````markdown +This math is inline: $a^2+b^2=c^2$. + +This math is on a separate line: $$a^2+b^2=c^2$$ + +This math is on a separate line: + +$$ +a^2+b^2=c^2 +$$ +```` + +<!-- Uncomment the example below when the flag is enabled on GitLab.com --> +<!-- This math is inline: $a^2+b^2=c^2$. + +This math is on a separate line: $$a^2+b^2=c^2$$ + +This math is on a separate line: + +$$ +a^2+b^2=c^2 +$$ --> ### Task lists @@ -611,9 +648,10 @@ Quote break. If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiline-blockquote). GitLab Flavored Markdown extends the standard Markdown by also supporting multi-line blockquotes -fenced by `>>>`: +fenced by `>>>`, with a blank line before and after the block: ```markdown + >>> If you paste a message from somewhere else @@ -621,6 +659,7 @@ that spans multiple lines, you can quote that without having to manually prepend `>` to every line! >>> + ``` >>> @@ -772,6 +811,8 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` +<!-- markdownlint-disable MD050 --> + Emphasis, aka italics, with *asterisks* or _underscores_. Strong emphasis, aka bold, with double **asterisks** or __underscores__. @@ -780,6 +821,8 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ +<!-- markdownlint-enable MD050 --> + #### Multiple underscores in words and mid-word emphasis If this section isn't rendered correctly, @@ -1471,7 +1514,9 @@ Press <kbd>Enter</kbd> to go to the next page. ### Tables -Tables are not part of the core Markdown spec, but they are part of GitLab Flavored Markdown. +Tables are not part of the core Markdown specification, but are part of GitLab Flavored Markdown. + +#### Markdown 1. The first line contains the headers, separated by "pipes" (`|`). 1. The second line separates the headers from the cells. @@ -1547,12 +1592,12 @@ but they do not render properly on `docs.gitlab.com`: | cell 3 | <ul><li> - [ ] Task one </li><li> - [ ] Task two </li></ul> | ``` -#### Copy from spreadsheet and paste in Markdown +##### Copy and paste from a spreadsheet > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7. If you're working in spreadsheet software (for example, Microsoft Excel, Google -Sheets, or Apple Numbers), GitLab creates a Markdown table when you copy-and-paste +Sheets, or Apple Numbers), GitLab creates a Markdown table when you copy and paste from a spreadsheet. For example, suppose you have the following spreadsheet: @@ -1563,6 +1608,160 @@ entry and paste the spreadsheet:  +#### JSON + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86353) in GitLab 15.3. + +To render tables with JSON code blocks, use the following syntax: + +````markdown +```json:table +{} +``` +```` + +Watch the following video walkthrough of this feature: + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=12yWKw1AdKY">Demo: JSON Tables in Markdown</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/12yWKw1AdKY" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +The `items` attribute is a list of objects representing the data points. + +````markdown +```json:table +{ + "items" : [ + {"a": "11", "b": "22", "c": "33"} + ] +} +``` +```` + +To specify the table labels, use the `fields` attribute. + +````markdown +```json:table +{ + "fields" : ["a", "b", "c"], + "items" : [ + {"a": "11", "b": "22", "c": "33"} + ] +} +``` +```` + +Not all elements of `items` must have corresponding values in `fields`. + +````markdown +```json:table +{ + "fields" : ["a", "b", "c"], + "items" : [ + {"a": "11", "b": "22", "c": "33"}, + {"a": "211", "c": "233"} + ] +} +``` +```` + +When `fields` is not explicitly specified, the labels are picked from the first element of `items`. + +````markdown +```json:table +{ + "items" : [ + {"a": "11", "b": "22", "c": "33"}, + {"a": "211", "c": "233"} + ] +} +``` +```` + +You can specify custom labels for `fields`. + +````markdown +```json:table +{ + "fields" : [ + {"key": "a", "label": "AA"}, + {"key": "b", "label": "BB"}, + {"key": "c", "label": "CC"} + ], + "items" : [ + {"a": "11", "b": "22", "c": "33"}, + {"a": "211", "b": "222", "c": "233"} + ] +} +``` +```` + +You can enable sorting for individual elements of `fields`. + +````markdown +```json:table +{ + "fields" : [ + {"key": "a", "label": "AA", "sortable": true}, + {"key": "b", "label": "BB"}, + {"key": "c", "label": "CC"} + ], + "items" : [ + {"a": "11", "b": "22", "c": "33"}, + {"a": "211", "b": "222", "c": "233"} + ] +} +``` +```` + +You can use the `filter` attribute to render a table with content filtered dynamically by user input. + +````markdown +```json:table +{ + "fields" : [ + {"key": "a", "label": "AA"}, + {"key": "b", "label": "BB"}, + {"key": "c", "label": "CC"} + ], + "items" : [ + {"a": "11", "b": "22", "c": "33"}, + {"a": "211", "b": "222", "c": "233"} + ], + "filter" : true +} +``` +```` + +By default, every JSON table has the caption `Generated with JSON data`. +You can override this caption by specifying the `caption` attribute. + +````markdown +```json:table +{ + "items" : [ + {"a": "11", "b": "22", "c": "33"} + ], + "caption" : "Custom caption" +} +``` +```` + +If JSON is invalid, an error occurs. + +````markdown +```json:table +{ + "items" : [ + {"a": "11", "b": "22", "c": "33"} + ], +} +``` +```` + ## References - This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). diff --git a/doc/user/namespace/index.md b/doc/user/namespace/index.md index 9ffc65a4e8e..138b0a355ad 100644 --- a/doc/user/namespace/index.md +++ b/doc/user/namespace/index.md @@ -6,11 +6,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Namespaces -In GitLab, a *namespace* organizes related projects together. +In GitLab, a *namespace* provides one place to organize your related projects. Projects in one namespace are separate from projects in other namespaces, +which means you can use the same name for projects in different namespaces. + GitLab has two types of namespaces: -- A *personal* namespace, which is based on your username. Projects under a personal namespace must be configured one at a time. -- A *group* or *subgroup* namespace. In these namespaces, you can manage multiple projects at once. +- A *Personal* namespace, which is based on your username and provided to you when you create your account. + - If you change your username, the project and namespace URLs in your account also change. Before you change your username, + read about [repository redirects](../project/repository/index.md#what-happens-when-a-repository-path-changes). + - You cannot create subgroups in a personal namespace. + - Groups in your namespace do not inherit your namespace permissions and group features. + - All the *Personal Projects* created will fall under the scope of this namespace. + +- A *group* or *subgroup* namespace: + - You can create multiple subgroups to manage multiple projects. + - You can change the URL of group and subgroup namespaces. + - You can configure settings specifically for each subgroup and project in the namespace. + - When you create a subgroup, it inherits some of the parent group settings. You can view these in the subgroup **Settings**. To determine whether you're viewing a group or personal namespace, you can view the URL. For example: diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 1b14582a3f0..0a7e9d6395b 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. -To access the dashboard, on the top bar, select **Menu > Operations**. +To access the dashboard, on the top bar, select **Main menu > Operations**. ## Adding a project to the dashboard diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 4fc55d18253..84f544ec4ad 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -127,7 +127,7 @@ To publish the package with a deploy token: - `<tag>` is the Git tag name of the version you want to publish. To publish a branch, use `branch=<branch>` instead of `tag=<tag>`. -You can view the published package by going to **Packages & Registries > Package Registry** and +You can view the published package by going to **Packages and registries > Package Registry** and selecting the **Composer** tab. ## Publish a Composer package by using CI/CD @@ -145,11 +145,12 @@ You can publish a Composer package to the Package Registry as part of your CI/CD script: - apk add curl - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/composer"' + environment: production ``` 1. Run the pipeline. -To view the published package, go to **Packages & Registries > Package Registry** and select the **Composer** tab. +To view the published package, go to **Packages and registries > Package Registry** and select the **Composer** tab. ### Use a CI/CD template diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 7260dbb616c..ed106685b62 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -310,6 +310,7 @@ create_package: - conan new <package-name>/0.1 -t - conan create . <group-name>+<project-name>/stable - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload <package-name>/0.1@<group-name>+<project-name>/stable --all --remote=gitlab + environment: production ``` Additional Conan images to use as the basis of your CI file are available in the @@ -389,7 +390,7 @@ There are two ways to remove a Conan package from the GitLab Package Registry. - From the GitLab user interface: - Go to your project's **Packages & Registries > Package Registry**. Remove the + Go to your project's **Packages and registries > Package Registry**. Remove the package by selecting **Remove repository** (**{remove}**). ## Search for Conan packages in the Package Registry diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index a203de2ed2c..bfbc400f4dd 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -26,7 +26,7 @@ Registry for your GitLab instance, visit the You can view the Container Registry for a project or group. 1. Go to your project or group. -1. Go to **Packages & Registries > Container Registry**. +1. Go to **Packages and registries > Container Registry**. You can search, sort, filter, and [delete](#delete-images-from-within-gitlab) containers on this page. You can share a filtered view by copying the URL from your browser. @@ -40,7 +40,7 @@ If a project is public, so is the Container Registry. You can view a list of tags associated with a given container image: 1. Go to your project or group. -1. Go to **Packages & Registries > Container Registry**. +1. Go to **Packages and registries > Container Registry**. 1. Select the container image you are interested in. This brings up the Container Registry **Tag Details** page. You can view details about each tag, @@ -55,7 +55,7 @@ tags on this page. You can share a filtered view by copying the URL from your br To download and run a container image hosted in the GitLab Container Registry: 1. Copy the link to your container image: - - Go to your project or group's **Packages & Registries > Container Registry** + - Go to your project or group's **Packages and registries > Container Registry** and find the image you want. - Next to the image name, select **Copy**. @@ -67,6 +67,8 @@ To download and run a container image hosted in the GitLab Container Registry: docker run [options] registry.example.com/group/project/image [arguments] ``` +[Authentication](#authenticate-with-the-container-registry) is needed to download images from private repository. + For more information on running Docker containers, visit the [Docker documentation](https://docs.docker.com/engine/userguide/intro/). @@ -97,15 +99,9 @@ registry.example.com/mynamespace/myproject/image:latest registry.example.com/mynamespace/myproject/my/image:rc1 ``` -## Build and push images by using Docker commands - -To build and push to the Container Registry, you can use Docker commands. - -### Authenticate with the Container Registry +## Authenticate with the Container Registry -Before you can build and push images, you must authenticate with the Container Registry. - -To authenticate, you can use: +To authenticate with the Container Registry, you can use: - A [personal access token](../../profile/personal_access_tokens.md). - A [deploy token](../../project/deploy_tokens/index.md). @@ -121,7 +117,9 @@ To authenticate, run the `docker` command. For example: docker login registry.example.com -u <username> -p <token> ``` -### Build and push images by using Docker commands +## Build and push images by using Docker commands + +Before you can build and push images, you must [authenticate](#authenticate-with-the-container-registry) with the Container Registry. To build and push to the Container Registry: @@ -139,7 +137,7 @@ To build and push to the Container Registry: docker push registry.example.com/group/project/image ``` -To view these commands, go to your project's **Packages & Registries > Container Registry**. +To view these commands, go to your project's **Packages and registries > Container Registry**. ## Build and push by using GitLab CI/CD @@ -301,6 +299,7 @@ deploy: - ./deploy.sh only: - main + environment: production ``` NOTE: @@ -394,7 +393,7 @@ images), are automatically scheduled for deletion after 24 hours if left unrefer To delete images from within GitLab: -1. Navigate to your project's or group's **Packages & Registries > Container Registry**. +1. Navigate to your project's or group's **Packages and registries > Container Registry**. 1. From the **Container Registry** page, you can select what you want to delete, by either: @@ -508,7 +507,7 @@ You can, however, remove the Container Registry for a project: and disable **Container Registry**. 1. Select **Save changes**. -The **Packages & Registries > Container Registry** entry is removed from the project's sidebar. +The **Packages and registries > Container Registry** entry is removed from the project's sidebar. ## Change visibility of the Container Registry diff --git a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md index 8f90f42ad08..76e3da9538f 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md +++ b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md @@ -125,7 +125,7 @@ upgrading to [GitLab Premium or Ultimate](https://about.gitlab.com/upgrade/). ## Purchase additional data transfer -Read more about managing your [data transfer limits](../../../subscriptions/gitlab_com/#purchase-more-storage-and-transfer). +Read more about managing your [data transfer limits](../../../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). ## Related issues diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index 788e57b6410..b3dd8da9b41 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -113,7 +113,7 @@ You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the To create a cleanup policy in the UI: -1. For your project, go to **Settings > Packages & Registries**. +1. For your project, go to **Settings > Packages and registries**. 1. Expand the **Clean up image tags** section. 1. Complete the fields. @@ -206,7 +206,7 @@ For self-managed instances, those settings can be updated in the [Rails console] They are also available in the [administrator area](../../admin_area/index.md): -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. Go to **Settings > CI/CD > Container Registry**. ### Use the cleanup policy API @@ -219,7 +219,7 @@ Examples: ```shell curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" \ - --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-main"}}' \ + --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":".*","name_regex_keep":".*-main"}}' \ "https://gitlab.example.com/api/v4/projects/2" ``` diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 1d846a60281..4143ab0881f 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -175,3 +175,43 @@ To install a package: ```shell sudo apt-get -y install -t <codename> <package-name> ``` + +## Download a source package + +To download a source package: + +1. Configure the repository: + + If you are using a private project, add your [credentials](#authenticate-to-the-package-registry) to your apt configuration: + + ```shell + echo 'machine gitlab.example.com login <username> password <your_access_token>' \ + | sudo tee /etc/apt/auth.conf.d/gitlab_project.conf + ``` + + Download your distribution key: + + ```shell + sudo mkdir -p /usr/local/share/keyrings + curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions/<codename>/key.asc" \ + | \ + gpg --dearmor \ + | \ + sudo tee /usr/local/share/keyrings/<codename>-archive-keyring.gpg \ + > /dev/null + ``` + + Add your project as a source: + + ```shell + echo 'deb-src [ signed-by=/usr/local/share/keyrings/<codename>-archive-keyring.gpg ] https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian <codename> <component1> <component2>' \ + | sudo tee /etc/apt/sources.list.d/gitlab_project-sources.list + sudo apt-get update + ``` + +1. Download the source package: + + ```shell + sudo apt-get source -t <codename> <package-name> + ``` diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index b570bba73e5..1310f8eedaa 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -37,8 +37,8 @@ For a list of planned additions, view the To enable or turn off the Dependency Proxy for a group: -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Packages & Registries**. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Packages and registries**. 1. Expand the **Dependency Proxy** section. 1. To enable the proxy, turn on **Enable Proxy**. To turn it off, turn the toggle off. @@ -50,8 +50,8 @@ for the entire GitLab instance. To view the Dependency Proxy: -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Packages & Registries > Dependency Proxy**. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Dependency Proxy**. The Dependency Proxy is not available for projects. @@ -175,8 +175,8 @@ You can also use [custom CI/CD variables](../../../ci/variables/index.md#custom- To store a Docker image in Dependency Proxy storage: -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Packages & Registries > Dependency Proxy**. +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Dependency Proxy**. 1. Copy the **Dependency Proxy image prefix**. 1. Use one of these commands. In these examples, the image is `alpine:latest`. 1. You can also pull images by digest to specify exactly which version of an image to pull. diff --git a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md index 839684da875..fecf60feeef 100644 --- a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md +++ b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md @@ -33,7 +33,7 @@ image or tag from Docker Hub. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340777) in GitLab 14.6 You can enable an automatic time-to-live (TTL) policy for the Dependency Proxy from the user -interface. To do this, navigate to your group's **Settings > Packages & Registries > Dependency Proxy** +interface. To do this, navigate to your group's **Settings > Packages and registries > Dependency Proxy** and enable the setting to automatically clear items from the cache after 90 days. ### Enable cleanup policies with GraphQL diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index d4acb14b9ca..312a2c119d6 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -123,7 +123,7 @@ or the UI. In the UI: -1. For your group, go to **Settings > Packages & Registries**. +1. For your group, go to **Settings > Packages and registries**. 1. Expand the **Package Registry** section. 1. Turn on the **Reject duplicates** toggle. 1. Optional. To allow some duplicate packages, in the **Exceptions** box enter a regex pattern that @@ -215,7 +215,7 @@ It also demonstrates how to manage a semantic version for the generic package: s ### Internal Server error on large file uploads to S3 -S3-compatible object storage [limits the size of a single PUT request to 5GB](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html). If the `aws_signature_version` is set to `2` in the [object storage connection settings](../../../administration/object_storage.md), attempting to publish a package file larger than the 5GB limit can result in a `HTTP 500: Internal Server Error` response. +S3-compatible object storage [limits the size of a single PUT request to 5GB](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html). If the `aws_signature_version` is set to `2` in the [object storage connection settings](../../../administration/object_storage.md), attempting to publish a package file larger than the 5GB limit can result in a `HTTP 500: Internal Server Error` response. If you are receiving `HTTP 500: Internal Server Error` responses when publishing large files to S3, set the `aws_signature_version` to `4`: diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md new file mode 100644 index 00000000000..720e274aee5 --- /dev/null +++ b/doc/user/packages/harbor_container_registry/index.md @@ -0,0 +1,69 @@ +--- +stage: Package +group: Package +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 +--- + +# Harbor Registry **(FREE)** + +You can integrate the [Harbor container registry](../../../user/project/integrations/harbor.md#harbor-container-registry-integration) into GitLab and use Harbor as the container registry for your GitLab project to store images. + +## View the Harbor Registry + +You can view the Harbor Registry for a project or group. + +1. On the top bar, select **Main menu > Projects/Groups**. +1. Go to the project or group that you are interested in. +1. On the left sidebar, select **Packages and registries > Harbor Registry**. + +You can search, sort, and filter images on this page. You can share a filtered view by copying the URL from your browser. + +At the project level, you can see **CLI Commands** in the upper right corner, where you can copy +corresponding commands to log in, build images, and push images. **CLI Commands** is not shown at +the group level. + +NOTE: +Default settings for the Harbor integration at the project level are inherited from the group level. + +## Use images from the Harbor Registry + +To download and run a Harbor image hosted in the GitLab Harbor Registry: + +1. Copy the link to your container image: + 1. Go to your project or group's **Packages and registries > Harbor Registry** and find the image you want. + 1. Click the **Copy** icon next to the image name. + +1. Use the command to run the container image you want. + +## View the tags of a specific artifact + +To view the list of tags associated with a specific artifact: + +1. Go to your project or group. +1. Go to **Packages and registries > Harbor Registry**. +1. Click the image name to view its artifacts. +1. Select the artifact you want. + +This brings up the list of tags. You can view the tag count and the time published. + +You can also copy the tag URL and use it to pull the corresponding artifact. + +## Build and push images by using commands + +To build and push to the Harbor Registry: + +1. Authenticate with the Harbor Registry. +1. Run the command to build or push. + +To view these commands, go to your project's **Packages and registries > Harbor Registry > CLI Commands**. + +## Disable the Harbor Registry for a project + +To remove the Harbor Registry for a project: + +1. Go to your project/group's **Settings > Integrations** page. +1. Click **Harbor** under **Active integrations**. +1. Clear the **Active** checkbox under **Enable integration**. +1. Select **Save changes**. + +The **Packages and registries > Harbor Registry** entry is removed from the sidebar. diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md index e6a179c9d12..48cc7b9dea9 100644 --- a/doc/user/packages/infrastructure_registry/index.md +++ b/doc/user/packages/infrastructure_registry/index.md @@ -18,7 +18,7 @@ projects. To view packages within your project: 1. Go to the project. -1. Go to **Packages & Registries > Infrastructure Registry**. +1. Go to **Packages and registries > Infrastructure Registry**. You can search, sort, and filter packages on this page. @@ -49,7 +49,7 @@ You can see the pipeline that published the package as well as the commit and th To download a package: -1. Go to **Packages & Registries > Infrastructure Registry**. +1. Go to **Packages and registries > Infrastructure Registry**. 1. Select the name of the package you want to download. 1. In the **Activity** section, select the name of the package you want to download. @@ -64,7 +64,7 @@ You can delete packages by using [the API](../../../api/packages.md#delete-a-pro To delete a package in the UI, from your project: -1. Go to **Packages & Registries > Infrastructure Registry**. +1. Go to **Packages and registries > Infrastructure Registry**. 1. Find the name of the package you want to delete. 1. Select **Delete**. @@ -75,7 +75,7 @@ The package is permanently deleted. The Infrastructure Registry is automatically enabled. For self-managed instances, a GitLab administrator can -[disable](../../../administration/packages/index.md) **Packages & Registries**, +[disable](../../../administration/packages/index.md) **Packages and registries**, which removes this menu item from the sidebar. You can also remove the Infrastructure Registry for a specific project: diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index eaa04404a1f..957374245d2 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -605,7 +605,7 @@ To publish a package by using Gradle: gradle publish ``` -Now navigate to your project's **Packages & Registries** page and view the published artifacts. +Now navigate to your project's **Packages and registries** page and view the published artifacts. ### Publishing a package with the same name or version @@ -624,7 +624,7 @@ To prevent users from publishing duplicate Maven packages, you can use the [Grap In the UI: -1. For your group, go to **Settings > Packages & Registries**. +1. For your group, go to **Settings > Packages and registries**. 1. Expand the **Package Registry** section. 1. Turn on the **Reject duplicates** toggle. 1. Optional. To allow some duplicate packages, in the **Exceptions** box, enter a regex pattern that matches the names and/or versions of packages you want to allow. @@ -670,14 +670,20 @@ Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT ### Use Maven with `mvn dependency:get` -You can install packages by using the Maven commands directly. +You can install packages by using the Maven `dependency:get` [command](https://maven.apache.org/plugins/maven-dependency-plugin/get-mojo.html) directly. 1. In your project directory, run: ```shell - mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT + mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT -DremoteRepositories=gitlab-maven::::<gitlab endpoint url> -s <path to settings.xml> ``` + - `<gitlab endpoint url>` is the URL of the GitLab [endpoint](#use-the-gitlab-endpoint-for-maven-packages). + - `<path to settings.xml>` is the path to the `settings.xml` file that contains the [authentication details](#authenticate-to-the-package-registry-with-maven). + +NOTE: +The repository IDs in the command(`gitlab-maven`) and the `settings.xml` file must match. + The message should show that the package is downloading from the Package Registry: ```shell @@ -697,9 +703,70 @@ dependencies { } ``` +### Request forwarding to Maven Central + +> [Introduced](<https://gitlab.com/gitlab-org/gitlab/-/issues/362657>) behind a [feature flag](../../feature_flags.md), disabled by default in GitLab 15.4 + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. +On GitLab.com, this feature is not available. + +When a Maven package is not found in the Package Registry, the request is forwarded +to [Maven Central](https://search.maven.org/). + +When the feature flag is enabled, administrators can disable this behavior in the +[Continuous Integration settings](../../admin_area/settings/continuous_integration.md). + +There are many ways to configure your Maven project so that it will request packages +in Maven Central from GitLab. Maven repositories are queried in a +[specific order](https://maven.apache.org/guides/mini/guide-multiple-repositories.html#repository-order). +By default, maven-central is usually checked first through the +[Super POM](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Super_POM), so +GitLab needs to be configured to be queried before maven-central. + +[Using GitLab as a mirror of the central proxy](#setting-gitlab-as-a-mirror-for-the-central-proxy) is one +way to force GitLab to be queried in place of maven-central. + +Maven forwarding is restricted to only the [project level](#project-level-maven-endpoint) and +[group level](#group-level-maven-endpoint) endpoints. The [instance level endpoint](#instance-level-maven-endpoint) +has naming restrictions that prevent it from being used for packages that don't follow that convention and also +introduces too much security risk for supply-chain style attacks. + +#### Setting GitLab as a mirror for the central proxy + +To ensure all package requests are sent to GitLab instead of Maven Central, +you can override Maven Central as the central repository by adding a `<mirror>` +section to your `settings.xml`: + +```xml +<settings> + <servers> + <server> + <id>central-proxy</id> + <configuration> + <httpHeaders> + <property> + <name>Private-Token</name> + <value>{personal_access_token}</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> + <mirrors> + <mirror> + <id>central-proxy</id> + <name>GitLab proxy of central repo</name> + <url>https://gitlab.example.com/api/v4/projects/{project_id}/packages/maven</url> + <mirrorOf>central</mirrorOf> + </mirror> + </mirrors> +</settings> +``` + ## Remove a package -For your project, go to **Packages & Registries > Package Registry**. +For your project, go to **Packages and registries > Package Registry**. To remove a package, select the red trash icon or, from the package details, the **Delete** button. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 28de06b2d8a..678f5681890 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -284,7 +284,7 @@ To upload an npm package to your project, run this command: npm publish ``` -To view the package, go to your project's **Packages & Registries**. +To view the package, go to your project's **Packages and registries**. You can also define `"publishConfig"` for your project in `package.json`. For example: @@ -325,6 +325,7 @@ deploy: script: - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc - npm publish + environment: production ``` See the diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 2e182d20811..5b1e5bbd304 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -403,6 +403,7 @@ updated: - dotnet nuget push "bin/Release/*.nupkg" --source gitlab only: - main + environment: production ``` 1. Commit the changes and push it to your GitLab repository to trigger a new CI/CD build. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 7748780d0e4..fe19c549536 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -26,7 +26,7 @@ Learn how to use the GitLab Package Registry to build your own custom package wo You can view packages for your project or group. 1. Go to the project or group. -1. Go to **Packages & Registries > Package Registry**. +1. Go to **Packages and registries > Package Registry**. You can search, sort, and filter packages on this page. You can share your search results by copying and pasting the URL from your browser. @@ -99,7 +99,7 @@ For information on reducing your storage use for the Package Registry, see The Package Registry is automatically enabled. If you are using a self-managed instance of GitLab, your administrator can remove -the menu item, **Packages & Registries**, from the GitLab sidebar. For more information, +the menu item, **Packages and registries**, from the GitLab sidebar. For more information, see the [administration documentation](../../../administration/packages/index.md). You can also remove the Package Registry for your project specifically: @@ -109,7 +109,7 @@ You can also remove the Package Registry for your project specifically: **Packages** feature. 1. Select **Save changes**. -The **Packages & Registries > Package Registry** entry is removed from the sidebar. +The **Packages and registries > Package Registry** entry is removed from the sidebar. ## Package Registry visibility permissions diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index cd7dd062f60..d85992fe05d 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -7,12 +7,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Reduce Package Registry Storage **(FREE)** Without cleanup, package registries become large over time. When a large number of packages and -their files are added: +their assets are added: - Fetching the list of packages becomes slower. - They take up a large amount of storage space on the server, impacting your [storage usage quota](../../usage_quotas.md). -We recommend deleting unnecessary packages and files. This page offers examples of how to do so. +We recommend deleting unnecessary packages and assets. This page offers examples of how to do so. ## Check Package Registry Storage Use @@ -29,40 +29,40 @@ You can delete packages by using [the API](../../../api/packages.md#delete-a-pro To delete a package in the UI, from your group or project: -1. Go to **Packages & Registries > Package Registry**. +1. Go to **Packages and registries > Package Registry**. 1. Find the name of the package you want to delete. 1. Select **Delete**. The package is permanently deleted. -## Delete files associated with a package +## Delete assets associated with a package -To delete package files, you must have suitable [permissions](../../permissions.md). +To delete package assets, you must have suitable [permissions](../../permissions.md). You can delete packages by using [the API](../../../api/packages.md#delete-a-package-file) or the UI. -To delete package files in the UI, from your group or project: +To delete package assets in the UI, from your group or project: -1. Go to **Packages & Registries > Package Registry**. +1. Go to **Packages and registries > Package Registry**. 1. Find the name of the package you want to delete. 1. Select the package to view additional details. -1. Find the name of the file you would like to delete. -1. Expand the ellipsis and select **Delete file**. +1. Find the name of the assets you would like to delete. +1. Expand the ellipsis and select **Delete asset**. -The package files are permanently deleted. +The package assets are permanently deleted. ## Cleanup policy > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346153) in GitLab 15.2. Depending on the number of packages to remove, the process of manually deleting the packages can take a long time to finish. -A cleanup policy defines a set of rules that, applied to a project, defines which package files you can automatically delete. +A cleanup policy defines a set of rules that, applied to a project, defines which package assets you can automatically delete. ### Enable the cleanup policy By default, the packages cleanup policy is disabled. To enable it: -1. Go to your project **Settings > Packages & Registries**. +1. Go to your project **Settings > Packages and registries**. 1. Expand **Manage storage used by package assets**. 1. Set the rules appropriately. @@ -73,7 +73,7 @@ To access these project settings, you must be at least a maintainer on the relat - `Number of duplicated assets to keep`. The number of duplicated assets to keep. Some package formats allow you to upload more than one copy of an asset. You can limit the number of duplicated assets to keep and automatically - delete the oldest files once the limit is reached. + delete the oldest assets once the limit is reached. ### Set cleanup limits to conserve resources diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index ba9ecbe50a3..302c88bf46f 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -309,7 +309,7 @@ Uploading mypypipackage-0.0.1.tar.gz 100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.24k/4.24k [00:00<00:00, 11.0kB/s] ``` -To view the published package, go to your project's **Packages & Registries** +To view the published package, go to your project's **Packages and registries** page. If you didn't use a `.pypirc` file to define your repository source, you can diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index 05113d0bc10..682a3e2ecf1 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -130,7 +130,7 @@ Pushing gem to https://gitlab.example.com/api/v4/projects/1/packages/rubygems... {"message":"201 Created"} ``` -To view the published gem, go to your project's **Packages & Registries** page. Gems pushed to +To view the published gem, go to your project's **Packages and registries** page. Gems pushed to GitLab aren't displayed in your project's Packages UI immediately. It can take up to 10 minutes to process a gem. diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 436c55f9ee0..0a3de25bf7d 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -24,7 +24,7 @@ When you publish a Terraform Module, if it does not exist, it is created. Prerequisites: -- A package with the same name and version must not already exist. +- A package with the same name and version must not already exist in the top-level namespace. - Your project and group names must not include a dot (`.`). For example, `source = "gitlab.example.com/my.group/project.name"`. - You must [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index eca94fce2e9..9a4590d9478 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -88,6 +88,8 @@ The following table lists project permissions available for each role: | [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | | [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | | [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | +| [Issue boards](project/issue_board.md):<br>Create or delete lists | | ✓ | ✓ | ✓ | ✓ | +| [Issue boards](project/issue_board.md):<br>Move issues between lists | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Add Labels | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Assign | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Create (*18*) | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -95,7 +97,7 @@ The following table lists project permissions available for each role: | [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [related issues](project/issues/related_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues]](project/issues/index.md):<br>Set [parent epic](group/epics/manage_epics.md#add-an-existing-issue-to-an-epic) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set [parent epic](group/epics/manage_epics.md#add-an-existing-issue-to-an-epic) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Close / reopen (*19*) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | @@ -119,7 +121,7 @@ The following table lists project permissions available for each role: | [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>[Resolve a thread](discussions/#resolve-a-thread) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>[Resolve a thread](discussions/index.md#resolve-a-thread) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage [merge approval rules](project/merge_requests/approvals/settings.md) (project settings) | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | | [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*6*) | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -348,11 +350,6 @@ from pushing to a protected branch. Read through the documentation on Find the current permissions on the value stream analytics dashboard, as described in [related documentation](analytics/value_stream_analytics.md#access-permissions-for-value-stream-analytics). -### 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). - ### File Locking permissions **(PREMIUM)** The user that locks a file or directory is the only one that can edit and push their changes back to the repository where the locked objects are located. @@ -386,7 +383,7 @@ The following table lists group permissions available for each role: | Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View group [epic](group/epics/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| View [group wiki](project/wiki/group.md) pages | ✓ (6) | ✓ | ✓ | ✓ | ✓ | +| View [group wiki](project/wiki/group.md) pages | ✓ (5) | ✓ | ✓ | ✓ | ✓ | | View [Insights](project/insights/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | View [Insights](project/insights/index.md) charts | ✓ | ✓ | ✓ | ✓ | ✓ | | View [Issue analytics](analytics/issue_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -398,13 +395,13 @@ The following table lists group permissions available for each role: | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | | Delete [packages](packages/index.md) | | | | ✓ | ✓ | | Create/edit/delete [Maven and generic package duplicate settings](packages/generic_packages/index.md#do-not-allow-duplicate-generic-packages) | | | | ✓ | ✓ | -| Pull a Container Registry image | ✓ (7) | ✓ | ✓ | ✓ | ✓ | +| Pull a Container Registry image | ✓ (6) | ✓ | ✓ | ✓ | ✓ | | Remove a Container Registry image | | | ✓ | ✓ | ✓ | | View [Group DevOps Adoption](group/devops_adoption/index.md) | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | View [Productivity analytics](analytics/productivity_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | Create and edit [group wiki](project/wiki/group.md) pages | | | ✓ | ✓ | ✓ | -| Create project in group | | | ✓ (3)(5) | ✓ (3) | ✓ (3) | +| Create project in group | | | ✓ (2)(4) | ✓ (2) | ✓ (2) | | Create/edit/delete group milestones | | ✓ | ✓ | ✓ | ✓ | | Create/edit/delete iterations | | ✓ | ✓ | ✓ | ✓ | | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | @@ -412,10 +409,10 @@ The following table lists group permissions available for each role: | Purge the dependency proxy for a group | | | | | ✓ | | Create/edit/delete dependency proxy [cleanup policies](packages/dependency_proxy/reduce_dependency_proxy_storage.md#cleanup-policies) | | | | ✓ | ✓ | | Use [security dashboard](application_security/security_dashboard/index.md) | | | ✓ | ✓ | ✓ | -| View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | +| View group Audit Events | | | ✓ (6) | ✓ (6) | ✓ | | Create subgroup | | | | ✓ (1) | ✓ | | Delete [group wiki](project/wiki/group.md) pages | | | ✓ | ✓ | ✓ | -| Edit [epic](group/epics/index.md) comments (posted by any user) | | | | ✓ (2) | ✓ (2) | +| Edit [epic](group/epics/index.md) comments (posted by any user) | | | | ✓ | ✓ | | List group deploy tokens | | | | ✓ | ✓ | | Manage [group push rules](group/access_and_permissions.md#group-push-rules) | | | | ✓ | ✓ | | View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | @@ -426,14 +423,14 @@ The following table lists group permissions available for each role: | Delete group [epic](group/epics/index.md) | | | | | ✓ | | Disable notification emails | | | | | ✓ | | Edit group settings | | | | | ✓ | -| Edit [SAML SSO](group/saml_sso/index.md) | | | | | ✓ (4) | +| Edit [SAML SSO](group/saml_sso/index.md) | | | | | ✓ (3) | | Filter members by 2FA status | | | | | ✓ | | Manage group level CI/CD variables | | | | | ✓ | | Manage group members | | | | | ✓ | | Share (invite) groups with groups | | | | | ✓ | | View 2FA status of members | | | | | ✓ | -| View [Billing](../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) | | | | | ✓ (4) | -| View group [Usage Quotas](usage_quotas.md) page | | | | | ✓ (4) | +| View [Billing](../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) | | | | | ✓ (3) | +| View group [Usage Quotas](usage_quotas.md) page | | | | | ✓ (3) | | Manage group runners | | | | | ✓ | | [Migrate groups](group/import/index.md) | | | | | ✓ | | Manage [subscriptions, and purchase CI/CD minutes and storage](../subscriptions/gitlab_com/index.md) | | | | | ✓ | @@ -441,14 +438,13 @@ The following table lists group permissions available for each role: <!-- markdownlint-disable MD029 --> 1. Groups can be set to allow either Owners, or Owners and users with the Maintainer role, to [create subgroups](group/subgroups/index.md#create-a-subgroup). -2. Introduced in GitLab 12.2. -3. Default project creation role can be changed at: +2. Default project creation role can be changed at: - The [instance level](admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). - The [group level](group/manage.md#specify-who-can-add-projects-to-a-group). -4. Does not apply to subgroups. -5. Developers can push commits to the default branch of a new project only if the [default branch protection](group/manage.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". -6. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. -7. Users can only view events based on their individual actions. +3. Does not apply to subgroups. +4. Developers can push commits to the default branch of a new project only if the [default branch protection](group/manage.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". +5. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. +6. Users can only view events based on their individual actions. <!-- markdownlint-enable MD029 --> @@ -470,7 +466,8 @@ project and should only have access to that project. External users: -- Can only create projects (including forks), subgroups, and snippets within the top-level group to which they belong. +- Cannot create project, groups, and snippets within their personal namespaces. +- Can only create projects (including forks), subgroups, and snippets within top-level groups to which they are explicitly granted access. - Can only access public projects and projects to which they are explicitly granted access, thus hiding all other internal or private ones from them (like being logged out). @@ -496,7 +493,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**. + 1. On the top bar, select **Main 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. @@ -510,7 +507,7 @@ Additionally, users can be set as external users using: 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**. +1. On the top bar, select **Main 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 694ed02a694..e3f7d47038d 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -33,7 +33,7 @@ Prerequisites: To create a user manually: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users** (`/admin/users`). 1. Select **New user**. 1. Complete the fields. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 5ec29814e06..d2e0c1ad834 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -28,7 +28,7 @@ As a user, to delete your own account: As an administrator, to delete a user account: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main 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/index.md b/doc/user/profile/index.md index 4c859d98004..e4cf905bbce 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -111,8 +111,8 @@ the README file with information, it's included on your profile page. To create a new project and add its README to your profile: -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, enter the name for your new project. @@ -205,7 +205,7 @@ To set your current status: 1. Select a value from the **Clear status after** dropdown list. 1. Select **Set status**. Alternatively, you can select **Remove status** to remove your user status entirely. -You can also set your current status by [using the API](../../api/users.md#user-status). +You can also set your current status from [your user settings](#access-your-user-settings) or by [using the API](../../api/users.md#user-status). If you select the **Busy** checkbox, remember to clear it when you become available again. @@ -421,7 +421,7 @@ When you sign in to the main GitLab application, a `_gitlab_session` cookie is set. When you close your browser, the cookie is cleared client-side and it expires after a set duration. GitLab administrators can determine the duration: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Account and limit**. The set duration is in **Session duration (minutes)**. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 0245f0615e0..1b737f14f68 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -108,7 +108,7 @@ To select a notification level for a group, use either of these methods: Or: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main 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). @@ -139,7 +139,7 @@ To select a notification level for a project, use either of these methods: Or: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main 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). diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 427c412219a..2fd18f583a4 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -19,6 +19,13 @@ Personal access tokens can be an alternative to [OAuth2](../../api/oauth2.md) an In both cases, you authenticate with a personal access token in place of your password. +WARNING: +The ability to create personal access tokens without expiry was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and is planned for removal in GitLab +16.0. When this ability is removed, existing personal access tokens without an expiry are planned to have an expiry added. +The automatic adding of an expiry occurs on GitLab.com during the 16.0 milestone. The automatic adding of an expiry +occurs on self-managed instances when they are upgraded to GitLab 16.0. This change is a breaking change. + Personal access tokens are: - Required when [two-factor authentication (2FA)](account/two_factor_authentication.md) is enabled. @@ -40,6 +47,8 @@ Use impersonation tokens to automate authentication as a specific user. ## Create a personal access token +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days is populated in the UI. + You can create as many personal access tokens as you like. 1. In the top-right corner, select your avatar. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index e99a2dad980..31ab802a8b8 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -116,12 +116,11 @@ between the fixed (max. `1280px`) and the fluid (`100%`) application layout. NOTE: While `1280px` is the standard max width when using fixed layout, some pages still use 100% width, depending on the content. -### Default dashboard +### Dashboard For users who have access to a large number of projects but only keep up with a -select few, the amount of activity on the default Dashboard page can be -overwhelming. Changing this setting allows you to redefine your default -dashboard. +select few, the amount of activity on the your dashboard can be +overwhelming. Changing this setting allows you to redefine what is displayed by default. You can include the following options for your default dashboard view: diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 2f9e04fb828..cf0ff4ed8b9 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -21,7 +21,7 @@ If you find that you have to add the same badges to several projects, you may wa To add a new badge to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Badges**. 1. Under "Link", enter the URL that the badges should point to and under @@ -41,7 +41,7 @@ A common project badge presents the GitLab CI pipeline status. To add this badge to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Badges**. 1. Under **Name**, enter _Pipeline Status_. @@ -68,7 +68,7 @@ If you need individual badges for each project, either: To add a new badge to a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Badges**. 1. Under "Link", enter the URL that the badges should point to and under @@ -118,7 +118,7 @@ https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg To add a new badge to a group or project with a custom image: -1. On the top bar, select **Menu** and find your group or project. +1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Badges**. 1. Under **Name**, enter the name for the badge. diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index f8494116655..aac704e2cdd 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -38,8 +38,8 @@ want to make sure the performance stays the same, or improves. Developers need to be careful when using canaries with user-facing changes, because by default, requests from the same user are randomly distributed between canary and non-canary pods, which could result in confusion or even errors. If needed, you -may want to consider -[setting `service.spec.sessionAffinity` to `ClientIP` in your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), +may want to consider +[setting `service.spec.sessionAffinity` to `ClientIP` in your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), but that is beyond the scope of this document. ## Advanced traffic control with Canary Ingress diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index be73f2c9a01..d9339291328 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -56,7 +56,7 @@ cluster certificates: 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 > Kubernetes**, for an instance-level cluster. + - **Main menu > Admin > Kubernetes**, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, select **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. @@ -248,7 +248,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 > Settings > General** and expand the **Amazon EKS** section. +1. In GitLab, on the top bar, select **Main 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 c55c11151ce..d7137c18a03 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -68,7 +68,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 > Kubernetes** page, for an instance-level cluster. + 1. **Main menu > Admin > Kubernetes** page, for an instance-level cluster. 1. On the **Kubernetes clusters** page, select the **Connect with a certificate** option from the **Actions** dropdown menu. 1. On the **Connect a cluster** page, fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index bfaf9aab7b7..6ed02838e9b 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -51,7 +51,7 @@ Note the following: cluster's pod address IP range is set to `/16` instead of the regular `/14`. `/16` is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to - set up an [initial service account](cluster_access.md). In + set up an [initial service account](cluster_access.md). In [GitLab versions 11.10 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58208), the cluster creation process explicitly requests GKE to create clusters with basic authentication enabled and a client certificate. @@ -63,7 +63,7 @@ cluster certificates: - 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 > Kubernetes** page, for an instance-level cluster. + - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, select **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 f1004a40a13..2fba00ae940 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -19,7 +19,7 @@ When you successfully connect an existing cluster using cluster certificates, th 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 > Kubernetes** page, for an instance-level cluster. + - **Main 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. Select **Save changes**. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index f89d863e83b..940b58103f5 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -24,5 +24,5 @@ to a single project. To view project-level Kubernetes clusters: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 7f35caf2a68..860ebfbed14 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -17,7 +17,10 @@ development environments (IDE), including: Code Intelligence is built into GitLab and powered by [LSIF](https://lsif.dev/) (Language Server Index Format), a file format for precomputed code -intelligence data. +intelligence data. GitLab processes one LSIF file per project, and +Code Intelligence does not support different LSIF files per branch. +Follow epic [#4212, Code intelligence enhancements](https://gitlab.com/groups/gitlab-org/-/epics/4212) +for progress on upcoming enhancements. NOTE: You can automate this feature in your applications by using [Auto DevOps](../../topics/autodevops/index.md). @@ -59,13 +62,5 @@ under the **References** tab: ## Language support Generating an LSIF file requires a language server indexer implementation for the -relevant language. - -| Language | Implementation | -|---|---| -| Go | [`sourcegraph/lsif-go`](https://github.com/sourcegraph/lsif-go) | -| JavaScript | [`sourcegraph/lsif-node`](https://github.com/sourcegraph/lsif-node) | -| TypeScript | [`sourcegraph/lsif-node`](https://github.com/sourcegraph/lsif-node) | - -View a complete list of [available LSIF indexers](https://lsif.dev/#implementations-server) on their website and +relevant language. View a complete list of [available LSIF indexers](https://lsif.dev/#implementations-server) on their website and refer to their documentation to see how to generate an LSIF file for your specific language. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 41afbdada6b..63010610605 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -116,7 +116,7 @@ To display the deploy boards for a specific [environment](../../ci/environments/ Kubernetes. NOTE: - Matching based on the Kubernetes `app` label was removed in + Matching based on the Kubernetes `app` label was removed in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14020). To migrate, please apply the required annotations (see above) and re-deploy your application. If you are using Auto DevOps, this will diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index a9f19d27416..f424ec529b2 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -54,7 +54,7 @@ For example: To view the deploy keys available to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. @@ -72,7 +72,7 @@ Prerequisites: - [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH key on the host that requires access to the repository. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Complete the fields. @@ -92,7 +92,7 @@ Prerequisites: To create a public deploy key: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Deploy Keys**. 1. Select **New deploy key**. 1. Complete the fields. @@ -109,7 +109,7 @@ Prerequisites: To grant a public deploy key access to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Publicly accessible deploy keys**. @@ -129,7 +129,7 @@ Prerequisites: To disable a deploy key: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Disable** (**{cancel}**). diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 595f5e541b7..04a2eeacffb 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -31,7 +31,7 @@ You can create as many deploy tokens as you need from the settings of your project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). 1. Sign in to your GitLab account. -1. On the top bar, select **Menu > Projects** or **Menu > Groups** to find your project or group. +1. On the top bar, select **Main menu > Projects** or **Main menu > Groups** to find your project or group. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. Choose a name, and optionally, an expiration date and username for the token. @@ -51,7 +51,7 @@ Deploy tokens expire at midnight UTC on the date you define. To revoke a deploy token: -1. On the top bar, select **Menu > Projects** or **Menu > Groups** to find your project or group. +1. On the top bar, select **Main menu > Projects** or **Main menu > Groups** to find your project or group. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. @@ -190,7 +190,8 @@ To pull images from the Dependency Proxy, you must: ### GitLab deploy token -> Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default. +> - Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default. +> - [Feature flag `ci_variable_for_group_gitlab_deploy_token`](https://gitlab.com/gitlab-org/gitlab/-/issues/363621) removed in GitLab 15.4. There's a special case when it comes to deploy tokens. If a user creates one named `gitlab-deploy-token`, the username and token of the deploy token is diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 5df3a973cca..4050fa34026 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -32,7 +32,7 @@ directory in your repository. To create an issue description template: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. @@ -51,7 +51,7 @@ push to your default branch. To create a merge request description template: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. @@ -103,7 +103,7 @@ As a result, you can use the same templates in issues and merge requests in all To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Templates**. 1. From the dropdown list, select your template project as the template repository at group level. @@ -134,10 +134,9 @@ To set a default description template for merge requests, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and higher: set the default template in project settings: - 1. On the top bar, select **Menu > Projects** and find your project. - 1. On the left sidebar, select **Settings**. - 1. Expand **Merge requests**. - 1. Fill in the **Default description template for merge requests** text area. + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **Settings > Merge requests**. + 1. In the **Merge commit message template** section, fill in **Default description template for merge requests**. 1. Select **Save changes**. To set a default description template for issues, either: @@ -147,7 +146,7 @@ To set a default description template for issues, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and higher: set the default template in project settings: - 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings**. 1. Expand **Default issue template**. 1. Fill in the **Default description template for issues** text area. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 4810fb96ed3..f1b9bde6cd0 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -220,7 +220,7 @@ To view the user who locked the file (if it was not you), hover over the button. To view and remove file locks: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Locked Files**. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 90f64b7262c..f2e4b65e3d4 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -23,5 +23,5 @@ ignored. ## Syntax Highlighting The `.gitattributes` file can be used to define which language to use when -syntax highlighting files and diffs. See +syntax highlighting files and diffs. See ["Syntax Highlighting"](highlighting.md) for more information. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index d9ad0c57d79..2d9f92c38e4 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w tools developed by IBM which also include a centralized version control system similar to Git. -A good read of ClearCase's basic concepts is can be found in this +A good read of ClearCase's basic concepts is can be found in this [StackOverflow post](https://stackoverflow.com/a/645771/974710). The following table illustrates the main differences between ClearCase and Git: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index a3dfa3edff0..c04f734e8bb 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -26,7 +26,7 @@ If you are importing from GitHub Enterprise to a 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 GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#allowlist-for-local-requests) +- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests) with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941). @@ -62,7 +62,7 @@ For this association to succeed, each GitHub author and assignee in the reposito must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. -- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address) +- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) that matches their GitLab account's email address. GitLab content imports that use GitHub accounts require that the GitHub public-facing email address is populated. This means @@ -76,7 +76,7 @@ field to be populated so you may have to add it on existing accounts. Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: - A GitLab account that has logged in using the GitHub icon. -- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/rest/reference/users#get-a-user) in the profile of the GitHub user +- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) in the profile of the GitHub user If you are importing to GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#use-a-github-token). We do not recommend this method, as it does not associate all user activity (such as issues and pull requests) with matching GitLab users. @@ -171,12 +171,15 @@ The following items of a project are imported: - Repository description. - Git repository data. +- Branch protection rules. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22650) in GitLab 15.4. - Issues. - Pull requests. - Wiki pages. - Milestones. - Labels. - Release note descriptions. +- Release note attachments. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15620) in GitLab 15.4 with `github_importer_attachments_import` + [feature flag](../../../administration/feature_flags.md) disabled by default. - Pull request review comments. - Regular issue and pull request comments. - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md). @@ -184,6 +187,8 @@ The following items of a project are imported: - Pull request "merged by" information (GitLab.com and GitLab 13.7 and later). - Pull request comments replies in discussions ([GitLab.com and GitLab 14.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/336596)). - Diff Notes suggestions ([GitLab.com and GitLab 14.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/340624)). +- Issue events and pull requests events. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7673) in GitLab 15.4 with `github_importer_issue_events_import` + [feature flag](../../../administration/feature_flags.md) disabled by default. References to pull requests and issues are preserved. Each imported repository maintains visibility level unless that [visibility level is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), in which case it diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 4103367accc..8d30a9c7f52 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -5,29 +5,30 @@ 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 importing from GitLab.com to your private GitLab instance **(FREE)** +# Import a project from GitLab.com to your private GitLab instance **(FREE)** -You can import your existing GitLab.com projects to your GitLab instance, but keep in -mind that it is possible only if GitLab.com integration is enabled on your GitLab instance. -[Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md). +You can import your existing GitLab.com projects to your GitLab instance. -To get to the importer page you need to go to "New project" page. +Prerequisite: -NOTE: -If you are interested in importing Wiki and merge request data to your new instance, -you'll need to follow the instructions for [exporting a project](../settings/import_export.md#export-a-project-and-its-data) +- GitLab.com integration must be enabled on your GitLab instance. + [Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md). - +To import a GitLab.com project to your self-managed GitLab instance: -Go to the **Import Projects** tab, then select **GitLab.com**, and you are redirected to GitLab.com -for permission to access your projects. After accepting, you are automatically redirected to the importer. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Import project**. +1. Select **GitLab.com**. +1. Give GitLab.com permission to access your projects. +1. Select **Import**. - +The importer imports your repository and issues. +When the importer is done, a new GitLab project is created with your imported data. -To import a project, select **Import**. The importer imports your repository and issues. -Once the importer is done, a new GitLab project is created with your imported data. +## Related topics -## Automate group and project import **(PREMIUM)** - -For information on automating user, group, and project import API calls, see -[Automate group and project import](index.md#automate-group-and-project-import). +- To automate user, group, and project import API calls, see + [Automate group and project import](index.md#automate-group-and-project-import). +- To import Wiki and merge request data to your new instance, + see [exporting a project](../settings/import_export.md#export-a-project-and-its-data). diff --git a/doc/user/project/import/img/gitlab_importer.png b/doc/user/project/import/img/gitlab_importer.png Binary files differdeleted file mode 100644 index 27d42eb492e..00000000000 --- a/doc/user/project/import/img/gitlab_importer.png +++ /dev/null diff --git a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png Binary files differdeleted file mode 100644 index ff6e5dbf4a1..00000000000 --- a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 432f043f945..72d533efd1b 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -85,7 +85,7 @@ Migrate the assets in this order: Keep in mind the limitations of the [import/export feature](../settings/import_export.md#items-that-are-exported). -You must still migrate your [Container Registry](../../packages/container_registry/) +You must still migrate your [Container Registry](../../packages/container_registry/index.md) over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts. ## Migrate from GitLab.com to self-managed GitLab @@ -142,5 +142,10 @@ GitLab from: - Bitbucket Server - Bitbucket Data Center -See the [Quick Start Guide](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start) -to learn how to use this approach for migrating users, groups, and projects at scale. +For more information, see: + +- [Quick Start](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start). +- [Frequently Asked Migration Questions](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/customer/famq.md), + including settings that need checking afterwards and other limitations. + +For support, customers must enter into a paid engagement with GitLab Professional Services. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 5163f957171..d64bea2bb41 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can import your existing repositories by providing the Git URL: -1. On the top bar, select **Menu > Create new project**. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select the **Import project** tab. 1. Select **Repository by URL**. 1. Enter a **Git repository URL**. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index b88abf91ae1..d6bcb0a2018 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -5,186 +5,87 @@ 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 --- -# Migrating from SVN to GitLab **(FREE)** +# Migrate from Subversion to GitLab **(FREE)** -Subversion (SVN) is a central version control system (VCS) while -Git is a distributed version control system. There are some major differences -between the two, for more information consult your favorite search engine. +GitLab uses Git as its version control system. If you're using Subversion (SVN) as your version control system, +you can migrate to using a Git repository in GitLab using `svn2git`. -There are two approaches to SVN to Git migration: +You can follow the steps on this page to migrate to Git if your SVN repository: -- [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which: - - Makes the GitLab repository to mirror the SVN project. - - Git and SVN repositories are kept in sync; you can use either one. - - Smoothens the migration process and allows you to manage migration risks. +- Has a standard format (trunk, branches, and tags). +- Is not nested. -- [Cut over migration](#cut-over-migration-with-svn2git) which: - - Translates and imports the existing data and history from SVN to Git. - - Is a fire and forget approach, good for smaller teams. +For a non-standard repository see the [`svn2git` documentation](https://github.com/nirvdrum/svn2git). -## Smooth migration with a Git/SVN mirror using SubGit +We recommend a hard cut over from SVN to Git and GitLab. Run the migration command once and then have all users use the +new GitLab repository immediately. -[SubGit](https://subgit.com) is a tool for a smooth, stress-free SVN to Git -migration. It creates a writable Git mirror of a local or remote Subversion -repository and that way you can use both Subversion and Git as long as you like. -It requires access to your GitLab server as it talks with the Git repositories -directly in a file system level. +## Install `svn2git` -### SubGit prerequisites +Install `svn2git` on a local workstation rather than the GitLab server: -1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can - follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html). -1. Download SubGit from <https://subgit.com/download>. -1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit` - command is available at `/opt/subgit-VERSION/bin/subgit`. +- On all systems you can install as a Ruby gem if you already have Ruby and Git installed: -### SubGit configuration + ```shell + sudo gem install svn2git + ``` -The first step to mirror you SVN repository in GitLab is to create a new empty -project that is used as a mirror. For Omnibus installations the path to -the repository is -`/var/opt/gitlab/git-data/repositories/USER/REPO.git` by default. For -installations from source, the default repository directory is -`/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a -variable: +- On Debian-based Linux distributions you can install the native packages: -```shell -GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git -``` + ```shell + sudo apt-get install git-core git-svn ruby + ``` -SubGit keeps this repository in sync with a remote SVN project. For -convenience, assign your remote SVN project URL to a variable: +## Prepare an authors file (recommended) -```shell -SVN_PROJECT_URL=http://svn.company.com/repos/project -``` +Prepare an authors file so `svn2git` can map SVN authors to Git authors. If you choose not to create the authors file, +commits are not attributed to the correct GitLab user. -Next you need to run SubGit to set up a Git/SVN mirror. Make sure the following -`subgit` command is ran on behalf of the same user that keeps ownership of -GitLab Git repositories (by default `git`): +To map authors, you must map every author present on changes in the SVN repository. If you don't, the +migration fails and you have to update the author file accordingly. -```shell -subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPO_PATH -``` +1. Search through the SVN repository and output a list of authors: -Adjust authors and branches mappings, if necessary. Open with your favorite -text editor: + ```shell + svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq + ``` -```shell -edit $GIT_REPO_PATH/subgit/authors.txt -edit $GIT_REPO_PATH/subgit/config -``` +1. Use the output from the last command to construct the authors file. Create a file called `authors.txt` and add one + mapping per line. For example: -For more information regarding the SubGit configuration options, refer to -[SubGit's documentation](https://subgit.com/documentation/) website. + ```plaintext + sidneyjones = Sidney Jones <sidneyjones@example.com> + ``` -### Initial translation +## Migrate SVN repository to Git repository -Now that SubGit has configured the Git/SVN repositories, run `subgit` to perform the -initial translation of existing SVN revisions into the Git repository: +`svn2git` supports excluding certain file paths, branches, tags, and more. See +the [`svn2git` documentation](https://github.com/nirvdrum/svn2git) or run `svn2git --help` for full documentation on all of +the available options. -```shell -subgit install $GIT_REPO_PATH -``` +For each repository to migrate: -After the initial translation is completed, `subgit` keeps the Git repository and the SVN -project sync - new Git commits are translated to -SVN revisions and new SVN revisions are translated to Git commits. Mirror -works transparently and does not require any special commands. +1. Create a new directory and change into it. +1. For repositories that: -If you would prefer to perform one-time cut over migration with `subgit`, use -the `import` command instead of `install`: + - Don't require a username and password, run: -```shell -subgit import $GIT_REPO_PATH -``` + ```shell + svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt + ``` -### SubGit licensing + - Do require a username and password, run: -Running SubGit in a mirror mode requires a -[registration](https://subgit.com/pricing). Registration is free for open -source, academic and startup projects. + ```shell + svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt --username <username> --password <password> + ``` -### SubGit support +1. Create a new GitLab project for your migrated code. +1. Copy the SSH or HTTP(S) repository URL from the GitLab project page. +1. Add the GitLab repository as a Git remote and push all the changes. This pushes all commits, branches, and tags. -For any questions related to SVN to GitLab migration with SubGit, you can -contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.com). - -## Cut over migration with svn2git - -NOTE: -Any issues with svn2git should be directed to the [relevant project and maintainer](https://github.com/nirvdrum/svn2git). -Check for existing issues and history for update frequency. - -If you are currently using an SVN repository, you can migrate the repository -to Git and GitLab. We recommend a hard cut over - run the migration command once -and then have all developers start using the new GitLab repository immediately. -Otherwise, it's hard to keep changing in sync in both directions. The conversion -process should be run on a local workstation. - -Install `svn2git`. On all systems you can install as a Ruby gem if you already -have Ruby and Git installed. - -```shell -sudo gem install svn2git -``` - -On Debian-based Linux distributions you can install the native packages: - -```shell -sudo apt-get install git-core git-svn ruby -``` - -Optionally, prepare an authors file so `svn2git` can map SVN authors to Git authors. -If you choose not to create the authors file then commits are not attributed -to the correct GitLab user. Some users may not consider this a big issue while -others want to ensure they complete this step. If you choose to map authors, -you must map every author present on changes in the SVN -repository. If you don't, the conversion fails and you have to update -the author file accordingly. The following command searches through the -repository and output a list of authors. - -```shell -svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq -``` - -Use the output from the last command to construct the authors file. -Create a file called `authors.txt` and add one mapping per line. - -```plaintext -janedoe = Jane Doe <janedoe@example.com> -johndoe = John Doe <johndoe@example.com> -``` - -If your SVN repository is in the standard format (trunk, branches, tags, -not nested) the conversion is simple. For a non-standard repository see -[svn2git documentation](https://github.com/nirvdrum/svn2git). The following -command will checkout the repository and do the conversion in the current -working directory. Be sure to create a new directory for each repository before -running the `svn2git` command. The conversion process takes some time. - -```shell -svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt -``` - -If your SVN repository requires a username and password add the -`--username <username>` and `--password <password>` flags to the above command. -`svn2git` also supports excluding certain file paths, branches, tags, and so on. See -[svn2git documentation](https://github.com/nirvdrum/svn2git) or run -`svn2git --help` for full documentation on all of the available options. - -Create a new GitLab project, into which you push your converted code. -Copy the SSH or HTTP(S) repository URL from the project page. Add the GitLab -repository as a Git remote and push all the changes. This pushes all commits, -branches and tags. - -```shell -git remote add origin git@gitlab.com:<group>/<project>.git -git push --all origin -git push --tags origin -``` - -## Contribute to this guide - -We welcome all contributions that would expand this guide with instructions on -how to migrate from SVN and other version control systems. + ```shell + git remote add origin git@gitlab.example.com:<group>/<project>.git + git push --all origin + git push --tags origin + ``` diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 53547e69e00..81293fb1645 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Optimize 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 --- @@ -158,7 +158,7 @@ Supported values are: | `stacked-bar` |  | NOTE: -The `dora` data source only supports the `bar` chart type. +The `dora` data source supports the `bar` and `line` chart types. ### `query` @@ -352,7 +352,7 @@ dora: title: "DORA charts" charts: - title: "DORA deployment frequency" - type: bar # only bar chart is supported at the moment + type: bar # or line query: data_source: dora params: diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index a10e261f10e..07b37b5be43 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -32,7 +32,7 @@ In Asana, create a Personal Access Token. Complete these steps in GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 75f099268cb..7b39f6c7162 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -36,7 +36,7 @@ integration in GitLab. ## Configure GitLab -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Atlassian Bamboo**. 1. Ensure the **Active** checkbox is selected. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index ac4b9d0769b..f058950e0f4 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -14,7 +14,7 @@ You can configure Bugzilla as an To enable the Bugzilla integration in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Bugzilla**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 71ca9f4f640..c3794aa1a2b 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -20,7 +20,7 @@ on the left sidebar in your project. To enable a custom issue tracker in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Custom issue tracker**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 3780ea37c0b..dffcc780206 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -26,7 +26,7 @@ and configure it in GitLab. With the webhook URL created in the Discord channel, you can set up the Discord Notifications service in GitLab. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Discord Notifications**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index c1c48c7fb12..37d9a86f8fa 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -11,7 +11,7 @@ that is pushed to your project. To enable emails on push: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Emails on push**. 1. In the **Recipients** section, provide a list of emails separated by spaces or newlines. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index b02f1a06e96..45f3653757d 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -14,7 +14,7 @@ This IBM product was [formerly named Rational Team Concert](https://jazz.net/blo To enable the EWM integration, in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **EWM**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index c07142d6edf..4be541d99cb 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -29,7 +29,7 @@ Complete these steps on GitHub: Complete these steps in GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **GitHub**. 1. Ensure the **Active** checkbox is selected. @@ -39,7 +39,7 @@ Complete these steps in GitLab: 1. Optional. Select **Test settings**. 1. Select **Save changes**. -After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) +After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests) to configure pipelines to run for open pull requests. ### Static or dynamic status check names diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index dc56c2669f8..afc379e7a07 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -74,7 +74,6 @@ Slack user on GitLab.com. The only difference with the [manually configurable Slack slash commands](slack_slash_commands.md) is that all the commands should be prefixed with the `/gitlab` keyword. -We are working on making this configurable in the future. For example, to show the issue number `1001` under the `gitlab-org/gitlab` project, you would do: diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index fbfa7d914a5..b2586383b43 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -10,7 +10,7 @@ Integrate your project to send notifications from GitLab to a room of your choice in [Google Chat](https://chat.google.com/) (former Google Hangouts). -## How it works +## Integration workflow To enable this integration, first you need to create a webhook for the room in Google Chat where you want to receive the notifications from your project. @@ -23,9 +23,9 @@ notifications to Google Chat:  -## In Google Chat +## Enable the integration in Google Chat -Select a room and create a webhook: +To enable the integration in Google Chat: 1. Enter the room where you want to receive notifications from GitLab. 1. Open the room dropdown menu on the top-left and select **Manage webhooks**. @@ -36,9 +36,22 @@ Select a room and create a webhook: For further details, see [the Google Chat documentation for configuring webhooks](https://developers.google.com/chat/how-tos/webhooks). -## In GitLab +### Enable threads in Google Chat -Enable the Google Chat integration in GitLab: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27823) in GitLab 15.4. + +To enable threaded notifications for the same GitLab object (for example, an issue or merge request): + +1. Go to [Google Chat](https://chat.google.com/). +1. In **Spaces**, select **+ > Create space**. +1. Enter the space name and (optionally) other details, and select **Use threaded replies**. +1. Select **Create**. + +You cannot enable threaded replies for existing Google Chat spaces. + +## Enable the integration in GitLab + +To enable the integration in GitLab: 1. In your project, go to **Settings > Integrations** and select **Google Chat**. 1. Scroll down to the end of the page where you find a **Webhook** field. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index da35f0dc226..535703ff59e 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -25,7 +25,7 @@ In the Harbor instance, ensure that: GitLab supports integrating Harbor projects at the group or project level. Complete these steps in GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Harbor**. 1. Turn on the **Active** toggle under **Enable Integration**. @@ -42,7 +42,9 @@ After the Harbor integration is activated: - The global variables `$HARBOR_USERNAME`, `$HARBOR_HOST`, `$HARBOR_OCI`, `$HARBOR_PASSWORD`, `$HARBOR_URL`, and `$HARBOR_PROJECT` are created for CI/CD use. - The project-level integration settings override the group-level integration settings. -## Secure your requests to the Harbor APIs +## Security considerations + +### Secure your requests to the Harbor APIs For each API request through the Harbor integration, the credentials for your connection to the Harbor API use the `username:password` combination. The following are suggestions for safe use: @@ -51,6 +53,12 @@ the `username:password` combination. The following are suggestions for safe use: - Follow the principle of least privilege (for access on Harbor) with your credentials. - Have a rotation policy on your credentials. +### CI/CD variable security + +Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables, including +`$HARBOR_PASSWORD`, and send them to a third-party server. For more details, see +[CI/CD variable security](../../../ci/variables/index.md#cicd-variable-security). + ## Examples of Harbor variables in CI/CD ### Push a Docker image with kaniko diff --git a/doc/user/project/integrations/img/mattermost_add_slash_command.png b/doc/user/project/integrations/img/mattermost_add_slash_command.png Binary files differdeleted file mode 100644 index 7759efa183c..00000000000 --- a/doc/user/project/integrations/img/mattermost_add_slash_command.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_bot_auth.png b/doc/user/project/integrations/img/mattermost_bot_auth.png Binary files differdeleted file mode 100644 index a05d8da1237..00000000000 --- a/doc/user/project/integrations/img/mattermost_bot_auth.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_bot_available_commands.png b/doc/user/project/integrations/img/mattermost_bot_available_commands.png Binary files differdeleted file mode 100644 index 3232ccc3451..00000000000 --- a/doc/user/project/integrations/img/mattermost_bot_available_commands.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_gitlab_token.png b/doc/user/project/integrations/img/mattermost_gitlab_token.png Binary files differdeleted file mode 100644 index 63140503824..00000000000 --- a/doc/user/project/integrations/img/mattermost_gitlab_token.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 3ef40fdfe44..18e827f8df8 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -18,7 +18,7 @@ Prerequisites: To view the available integrations for your project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. You can also view and manage integration settings across [all projects in an instance or group](../../admin_area/settings/project_integration_management.md). @@ -76,6 +76,7 @@ You can configure the following integrations. | [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | +| [Shimo Workspace](shimo.md) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | | [Slack application](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | | [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in a workspace. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index b2c2aea2c2b..5f7de09cc9d 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -39,7 +39,7 @@ network. For more details, read ## Complete these steps in GitLab -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 7dd4c1d1a8b..12575e34058 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -39,7 +39,7 @@ Display name override is not enabled by default, you need to ask your administra After the Mattermost instance has an incoming webhook set up, you can set up GitLab to send the notifications: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Mattermost notifications**. 1. Select the GitLab events to generate notifications for. For each event you select, input the Mattermost channel diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 768acb02ee6..28a5f2eec18 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -6,48 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Mattermost slash commands **(FREE)** -If your team uses [Mattermost](https://mattermost.com/) as a chat service, you can -integrate GitLab commands into Mattermost chat. This integration enables users to -run common operations, such as creating a GitLab issue, from the Mattermost chat -environment. +You can use slash commands to run common GitLab operations, like creating an issue, +from a [Mattermost](https://mattermost.com/) chat environment. GitLab can also send events (such as `issue created`) to Mattermost as part of the -separately configured [Mattermost Notifications Service](mattermost.md). +separately configured [Mattermost notifications](mattermost.md). -## Prerequisites +## Configuration options -Mattermost [3.4 or later](https://mattermost.com/blog/category/platform/releases/) is required. -GitLab provides different methods of configuring Mattermost slash commands, depending -on your configuration: +GitLab provides different ways to configure Mattermost slash commands. For any of these options, +you must have Mattermost [3.4 or later](https://mattermost.com/blog/category/platform/releases/). - **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](../../../integration/mattermost/index.md). + [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, + read the [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). + [automated configuration](#configure-automatically). +- **For all other installations**, use the [manual configuration](#configure-manually). -## Automated configuration +## Configure automatically -If Mattermost is installed on the same server as GitLab, the configuration process can be -done for you by GitLab. +If Mattermost is installed on the same server as GitLab, +you can automatically configure Mattermost slash commands: -Go to the Mattermost Slash Command service on your project and select **Add to Mattermost**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. In **Add an integration**, select **Mattermost slash commands**. +1. In **Enable integration**, ensure the **Active** checkbox is selected. +1. Select **Add to Mattermost**, and select **Save changes**. -## Manual configuration +## Configure manually To manually configure slash commands in Mattermost, you must: -1. [Enable custom slash commands](#enable-custom-slash-commands) in Mattermost. -1. [Get configuration values](#get-configuration-values-from-gitlab) from GitLab. -1. [Create a new slash command](#create-a-slash-command) in Mattermost. -1. [Provide the Mattermost token](#provide-the-mattermost-token-to-gitlab) to GitLab. +1. [Enable custom slash commands in Mattermost](#enable-custom-slash-commands-in-mattermost). + (This step is required only for installations from source.) +1. [Get configuration values from GitLab](#get-configuration-values-from-gitlab). +1. [Create a slash command in Mattermost](#create-a-slash-command-in-mattermost). +1. [Provide the Mattermost token to GitLab](#provide-the-mattermost-token-to-gitlab). -### Enable custom slash commands - -NOTE: -Omnibus GitLab installations are preconfigured. This step is required only for -installations from source. +### Enable custom slash commands in Mattermost To enable custom slash commands from the Mattermost administrator console: @@ -58,80 +56,68 @@ To enable custom slash commands from the Mattermost administrator console: - **Enable Custom Slash Commands** - **Enable integrations to override usernames** - **Enable integrations to override profile picture icons** -1. Select **Save**, but do not close this browser tab, because you need it in +1. Select **Save**, but do not close this browser tab. You need it in a later step. ### Get configuration values from GitLab -After you enable custom slash commands in Mattermost, you need configuration -information from GitLab. To get this information: +To get configuration values from GitLab: -1. In a different browser tab than your current Mattermost session, sign in to +1. In a different browser tab, sign in to GitLab as a user with administrator access. -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** - as you need it for the next step. All other values are suggestions. -1. Do not close this browser tab, because you need it in future steps. - -Next, create a slash command in Mattermost with the values from GitLab. +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Mattermost slash commands**. GitLab displays potential values for Mattermost settings. +1. Copy the **Request URL** value. All other values are suggestions. +1. Do not close this browser tab. You need it in a later step. -### Create a slash command +### Create a slash command in Mattermost -To create a slash command, you need the values you obtained from GitLab in -the previous step: +To create a slash command in Mattermost: -1. In the Mattermost tab you left open when you - [enabled custom slash commands](#enable-custom-slash-commands), go to your - team page. +1. [In the Mattermost browser tab](#enable-custom-slash-commands-in-mattermost), + go to your team page. 1. Select the **{ellipsis_v}** **Settings** icon, and select **Integrations**. -1. In the left menu, select **Slash commands**. -1. Select **Add Slash Command**: - -  +1. On the left sidebar, select **Slash commands**. +1. Select **Add Slash Command**. 1. Provide a **Display Name** and **Description** for your new command. -1. Provide a **Command Trigger Word** according to your application's configuration: +1. Provide a **Command Trigger Word** based on your application's configuration: - - **If you intend to only connect one project to your Mattermost team**: Use + - **If you intend to only connect one project to your Mattermost team**, use `/gitlab` for your trigger word. - - **If you intend to connect multiple projects**: Use a trigger word that relates + - **If you intend to connect multiple projects**, use a trigger word that relates to your project, such as `/project-name` or `/gitlab-project-name`. -1. For **Request URL**, provide the value you copied from GitLab when you - [viewed configuration values](#get-configuration-values-from-gitlab). -1. For all other values, you may use the suggestions from GitLab or use your +1. For **Request URL**, [paste the value you copied from GitLab](#get-configuration-values-from-gitlab). +1. For all other values, you may use the suggestions from GitLab or your preferred values. -1. Copy the **Token** value, as you need it in a later step, and select **Done**. +1. Copy the **Token** value, and select **Done**. ### Provide the Mattermost token to GitLab -When you create a new slash command in Mattermost, it generates a token you must +Creating a slash command in Mattermost generates a token you must provide to GitLab: -1. In the GitLab browser tab from - [getting configuration values from GitLab](#get-configuration-values-from-gitlab), - select the **Active** checkbox to enable this configuration. -1. In the **Token** field, paste the token you obtained from Mattermost. - ensure that the **Active** toggle is enabled. - -  - -1. Select **Save changes** for the changes to take effect. +1. [In the GitLab browser tab](#get-configuration-values-from-gitlab), + select the **Active** checkbox. +1. In the **Token** text box, [paste the token you copied from Mattermost](#create-a-slash-command-in-mattermost). +1. Select **Save changes**. Your slash command can now communicate with your GitLab project. -## Authorizing Mattermost to interact with GitLab +## Connect your GitLab account to Mattermost -The first time a user interacts with the newly created slash commands, -Mattermost triggers an authorization process. +Prerequisite: - +- To run [slash commands](#available-slash-commands), you must have + [permission](../../permissions.md#project-members-permissions) to + perform the action in the GitLab project. -This connects your Mattermost user with your GitLab user. You can -see all authorized chat accounts in your profile's page under **Chat**. +To interact with GitLab using Mattermost slash commands: -When the authorization process is complete, you can start interacting with -GitLab using the Mattermost commands. +1. In a Mattermost chat environment, run your new slash command. +1. Select **connect your GitLab account** to authorize access. + +You can see all authorized chat accounts in your Mattermost profile page under **Chat**. ## Available slash commands @@ -139,30 +125,21 @@ The available slash commands for Mattermost are: | Command | Description | Example | | ------- | ----------- | ------- | -| <kbd>/<trigger> issue new <title> <kbd>⇧ Shift</kbd>+<kbd>↵ Enter</kbd> <description></kbd> | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` | -| <kbd>/<trigger> issue show <issue-number></kbd> | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` | -| <kbd>/<trigger> deploy <environment> to <environment></kbd> | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` | - -To see a list of available commands to interact with GitLab, type the -trigger word followed by <kbd>help</kbd>. Example: `/gitlab help` - - +| `/<trigger> issue new <title>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<description>` | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` | +| `/<trigger> issue show <issue-number>` | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` | +| `/<trigger> deploy <environment> to <environment>` | Start the CI/CD job that deploys from one environment to another (for example, `staging` to `production`). CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` | +| `/<trigger> help` | View a list of available slash commands. | `/gitlab help` | -## Permissions +## Related topics -The permissions to run the [available commands](#available-slash-commands) derive from -the [permissions you have on the project](../../permissions.md#project-members-permissions). +- [Mattermost slash commands](https://developers.mattermost.com/integrate/slash-commands/) +- [Omnibus GitLab Mattermost](../../../integration/mattermost/index.md) ## Troubleshooting -If an event is not being triggered, confirm that the channel you're using is a public one. -Mattermost webhooks do not have access to private channels. - -If a private channel is required, you can edit the webhook's channel in Mattermost and -select a private channel. It is not possible to use different channels for -different types of notifications. All events are sent to the specified channel. - -## Further reading +When a Mattermost slash command does not trigger an event in GitLab: -- [Mattermost slash commands documentation](https://docs.mattermost.com/developer/slash-commands.html) -- [Omnibus GitLab Mattermost](../../../integration/mattermost/) +- Ensure you're using a public channel. + Mattermost webhooks do not have access to private channels. +- If you require a private channel, edit the webhook channel, + and select a private one. All events are sent to the specified channel. diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 6679bab745b..2e6954390fb 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -35,7 +35,7 @@ After you configure Microsoft Teams to receive notifications, you must configure GitLab to send the notifications: 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Microsoft Teams notifications**. 1. To enable the integration, select **Active**. diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 7f5414b86de..a0798da21f0 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -37,7 +37,7 @@ In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/ar Complete these steps in GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 068a2810a53..c1181169261 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -62,7 +62,7 @@ GitLab can use these to access the resource. More information about authenticati service account can be found at Google's documentation for [Authenticating from a service account](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_service_account). -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Prometheus**. 1. For **API URL**, provide the domain name or IP address of your server, such as @@ -83,7 +83,7 @@ You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prom with GitLab. Use the domain name or IP address of the Thanos server you'd like to integrate with. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Prometheus**. 1. Provide the domain name or IP address of your server, for example diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index cd28a7c0048..0eb3a38bb86 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -25,8 +25,8 @@ notifications: 1. To enable the integration for your group or project: 1. In your group or project, on the left sidebar, select **Settings > Integrations**. -1. To enable the integration for your instance: - 1. On the top bar, select **Menu > Admin**. +1. To enable the integration for your instance: + 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select the **Pumble** integration. 1. Ensure that the **Active** toggle is enabled. @@ -36,4 +36,4 @@ notifications: 1. Optional. To test the integration, select **Test settings**. 1. Select **Save changes**. -The Pumble channel begins to receive all applicable GitLab events. +The Pumble channel begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index a989b418199..bc1d299dccf 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -10,7 +10,7 @@ Use [Redmine](https://www.redmine.org/) as the issue tracker. To enable the Redmine integration in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Redmine**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index fdcbb498621..dc6c2da0d91 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -15,7 +15,7 @@ With the GitLab spoke in ServiceNow, you can automate actions for GitLab projects, groups, users, issues, merge requests, branches, and repositories. For a full list of features, see the -[GitLab spoke documentation](https://docs.servicenow.com/bundle/orlando-servicenow-platform/page/administer/integrationhub-store-spokes/concept/gitlab-spoke.html). +[GitLab spoke documentation](https://docs.servicenow.com/bundle/sandiego-application-development/page/administer/integrationhub-store-spokes/concept/gitlab-spoke.html). You must [configure GitLab as an OAuth2 authentication service provider](../../../integration/oauth_provider.md), which involves creating an application and then providing the Application ID diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md new file mode 100644 index 00000000000..ea92b8b3f0b --- /dev/null +++ b/doc/user/project/integrations/shimo.md @@ -0,0 +1,34 @@ +--- +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 +--- + +# Shimo Workspace integration **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) in GitLab 14.5 with a feature flag named `shimo_integration`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. [Feature flag `shimo_integration`](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) removed. + +[Shimo](https://shimo.im/) is a productivity suite that includes documents, spreadsheets, and slideshows in one interface. With this integration, you can use the Shimo Wiki directly within GitLab instead of the [GitLab group/project wiki](../wiki/index.md). + +## Configure settings in GitLab + +To enable the Shimo Workspace integration for your group or project: + +1. On the top bar, select **Main menu** and find your group or project. +1. On the left sidebar, select **Settings > Integrations**. +1. In **Add an integration**, select **Shimo Workspace**. +1. In **Enable integration**, ensure the **Active** checkbox is selected. +1. Provide the **Shimo Workspace URL** you want to link to your group or project (for example, `https://shimo.im/space/aBAYV6VvajUP873j`). +1. Select **Save changes**. + +On the left sidebar, **Shimo** now appears instead of **Wiki**. + +## View the Shimo Workspace + +To view the Shimo Workspace from your group or project: + +1. On the top bar, select **Main menu** and find your group or project. +1. On the left sidebar, select **Shimo**. +1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index dd0f57570aa..ae2e57a6d7f 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -22,7 +22,7 @@ to control GitLab from Slack. Slash commands are configured separately. ## Configure GitLab -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Slack notifications**. 1. In the **Enable integration** section, select the **Active** checkbox. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 5ad344a7d8e..67d6befb5fc 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -21,7 +21,7 @@ For GitLab.com, use the [GitLab Slack app](gitlab_slack_application.md) instead. Slack slash command integrations are scoped to a project. -1. In GitLab, on the top bar, select **Menu > Projects** and find your project. +1. In GitLab, on the top bar, select **Main 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). diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 1e607d89e80..91beefd30ab 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -15,7 +15,7 @@ copy its URL. In GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Unify Circuit**. 1. Turn on the **Active** toggle. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index e8b2470cf13..0b487e29d26 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**. Then, in the left sidebar, + - On the top bar, select **Main 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/youtrack.md b/doc/user/project/integrations/youtrack.md index 25fc9c4e1c3..e6071e7517d 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -14,7 +14,7 @@ You can configure YouTrack as an To enable the YouTrack integration in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **YouTrack**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 787e990526d..916d566bb20 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -8,14 +8,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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 + +You can use it as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board. -It pairs issue tracking and project management, keeping everything together, -so that you don't need to jump between different platforms to organize your workflow. +Issue boards pair issue tracking and project management, keeping everything together, +so you can organize your workflow on a single platform. -Issue boards build on the existing [issue tracking functionality](issues/index.md) and -[labels](labels.md). Your issues appear as cards in vertical lists, organized by their assigned +Issue boards use [issues](issues/index.md) and [labels](labels.md). +Your issues appear as cards in vertical lists, organized by their assigned labels, [milestones](#milestone-lists), or [assignees](#assignee-lists). Issue boards help you to visualize and manage your entire process in GitLab. @@ -31,21 +32,20 @@ boards in the same project.  -Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), -as shown in the following table: +Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/): | Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) | | -------- | ------------------------------ | --------------------------------------------------- | ------------------------------------------------------- | --------------------------------- | -| Free | Multiple | 1 | No | No | -| Premium | Multiple | Multiple | Yes | Yes | -| Ultimate | Multiple | Multiple | Yes | Yes | +| Free | Multiple | 1 | **{dotted-circle}** No | **{dotted-circle}** No | +| Premium | Multiple | Multiple | **{check-circle}** Yes | **{check-circle}** Yes | +| Ultimate | Multiple | Multiple | **{check-circle}** Yes | **{check-circle}** Yes | -To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. +Read more about [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards).  <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of +Watch a [video presentation](https://youtu.be/vjccjHI7aGI) (April 2020) of the issue board feature. ## Multiple issue boards @@ -68,17 +68,25 @@ GitLab automatically loads the last board you visited. ### Create an issue board +Prerequisites: + +- You must have at least the Reporter role for the project. + To create a new issue board: -1. Select the dropdown with the current board name in the upper left corner of the issue boards page. +1. Select the dropdown list with the current board name in the upper left corner of the issue boards page. 1. Select **Create new board**. 1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. ### Delete an issue board +Prerequisites: + +- You must have at least the Reporter role for the project. + To delete the currently active issue board: -1. Select the dropdown with the current board name in the upper left corner of the issue boards page. +1. Select the dropdown list with the current board name in the upper left corner of the issue boards page. 1. Select **Delete board**. 1. Select **Delete** to confirm. @@ -192,12 +200,11 @@ card includes: - Issue number - Assignee -## Permissions +## Ordering issues in a list -Users with at least the Reporter role 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. +Prerequisites: -## Ordering issues in a list +- You must have at least the Reporter role for the project. When an issue is created, the system assigns a relative order value that is greater than the maximum value of that issue's project or root group. This means the issue will be at the bottom of any issue list that @@ -275,16 +282,19 @@ Users on GitLab Free can use a single group issue board. ### Assignee lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in GitLab 11.0. - As in a regular list showing all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. -You can have a board with both label lists and assignee lists. To add an -assignee list: +You can have a board with both label lists and assignee lists. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To add an assignee list: 1. Select **Create list**. 1. Select **Assignee**. -1. In the dropdown, select a user. +1. In the dropdown list, select a user. 1. Select **Add to board**. Now that the assignee list is added, you can assign or unassign issues to that user @@ -295,14 +305,18 @@ To remove an assignee list, just as with a label list, select the trash icon. ### Milestone lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6469) in GitLab 11.2. - You're also able to create lists of a milestone. These are lists that filter issues by the assigned -milestone, giving you more freedom and visibility on the issue board. To add a milestone list: +milestone, giving you more freedom and visibility on the issue board. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To add a milestone list: 1. Select **Create list**. 1. Select **Milestone**. -1. In the dropdown, select a milestone. +1. In the dropdown list, select a milestone. 1. Select **Add to board**. Like the assignee lists, you're able to [drag issues](#move-issues-and-lists) @@ -316,14 +330,17 @@ As in other list types, select the trash icon to remove a list. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11 [with a flag](../../administration/feature_flags.md) named `iteration_board_lists`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75404) in GitLab 14.6. Feature flag `iteration_board_lists` removed. -You're also able to create lists of an iteration. -These lists filter issues by the assigned iteration. +You can create lists of issues in an iteration. + +Prerequisites: + +- You must have at least the Reporter role for the project. To add an iteration list: 1. Select **Create list**. 1. Select **Iteration**. -1. In the dropdown, select an iteration. +1. In the dropdown list, select an iteration. 1. Select **Add to board**. Like the milestone lists, you're able to [drag issues](#move-issues-and-lists) @@ -344,9 +361,13 @@ This feature is available both at the project and group level. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a video overview, see [Epics Swimlanes Walkthrough - 13.6](https://www.youtube.com/watch?v=nHC7-kz5P2g) (November 2020). +Prerequisites: + +- You must have at least the Reporter role for the project. + To group issues by epic in an issue board: -1. Select the **Group by** dropdown button. +1. Select **Group by**. 1. Select **Epic**.  @@ -375,8 +396,7 @@ You can also [drag issues](#move-issues-and-lists) to change their position and ## Work In Progress limits **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. You can set a Work In Progress (WIP) limit for each issue list on an issue board. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. @@ -389,6 +409,10 @@ Examples: - You have a list with five issues with a limit of five. When you move another issue to that list, the list's header displays **6/5**, with the six shown in red. +Prerequisites: + +- You must have at least the Reporter role for the project. + To set a WIP limit for a list: 1. Navigate to a Project or Group board of which you're a member. @@ -399,8 +423,7 @@ To set a WIP limit for a list: ## Blocked issues **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34723) in GitLab 12.8. -> - [View blocking issues when hovering over blocked icon](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10: View blocking issues when hovering over the "blocked" icon. If an issue is [blocked by another issue](issues/related_issues.md#blocking-issues), an icon appears next to its title to indicate its blocked status. @@ -423,9 +446,6 @@ When you hover over the blocked icon (**{issue-block}**), a detailed information - Change issue labels (by dragging an issue between lists). - Close an issue (by dragging it to the **Closed** list). -If you're not able to do some of the things above, make sure you have the right -[permissions](#permissions). - ### Edit an issue > Editing title, iteration, and confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1. @@ -433,6 +453,10 @@ If you're not able to do some of the things above, make sure you have the right You can edit an issue without leaving the board view. To open the right sidebar, select an issue card (not its title). +Prerequisites: + +- You must have at least the Reporter role for the project. + You can edit the following issue attributes in the right sidebar: - Assignees @@ -462,6 +486,10 @@ at the end of the lists, before **Closed**. To move and reorder lists, drag them Removing a list doesn't have any effect on issues and labels, as it's just the list view that's removed. You can always create it again later if you need. +Prerequisites: + +- You must have at least the Reporter role for the project. + To remove a list from an issue board: 1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**). @@ -473,6 +501,10 @@ To remove a list from an issue board: > The **Add issues** button was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57329) in GitLab 13.11. +Prerequisites: + +- You must have at least the Reporter role for the project. + If your board is scoped to one or more attributes, go to the issues you want to add and apply the same attributes as your board scope. @@ -488,6 +520,11 @@ The issue should now show in the `Doing` list on your issue board. > The **Remove from board** button was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229507) in GitLab 13.10. When an issue should no longer belong to a list, you can remove it. + +Prerequisites: + +- You must have at least the Reporter role for the project. + The steps depend on the scope of the list: 1. To open the right sidebar, select the issue card. @@ -502,6 +539,10 @@ The steps depend on the scope of the list: You can use the filters on top of your issue board to show only the results you want. It's similar to the filtering used in the [issue tracker](issues/index.md). +Prerequisites: + +- You must have at least the Reporter role for the project. + You can filter by the following: - Assignee @@ -577,6 +618,40 @@ into a different list. Learn about possible effects in [Dragging issues between To move a list, select its top bar, and drag it horizontally. You can't move the **Open** and **Closed** lists, but you can hide them when editing an issue board. +#### Move an issue to the start of the list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4. + +You can move issues to the top of the list with a menu shortcut. + +Your issue is moved to the top of the list even if other issues are hidden by a filter. + +Prerequisites: + +- You must at least have the Reporter role for the project. + +To move an issue to the start of the list: + +1. In an issue board, hover over the card of the issue you want to move. +1. Select the vertical ellipsis (**{ellipsis_v}**), then **Move to start of list**. + +#### Move an issue to the end of the list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4. + +You can move issues to the bottom of the list with a menu shortcut. + +Your issue is moved to the bottom of the list even if other issues are hidden by a filter. + +Prerequisites: + +- You must at least have the Reporter role for the project. + +To move an issue to the end of the list: + +1. In an issue board, hover over the card of the issue you want to move. +1. Select the vertical ellipsis (**{ellipsis_v}**), then **Move to end of list**. + #### Dragging issues between lists To move an issue to another list, select the issue card and drag it onto that list. @@ -593,8 +668,7 @@ and the target list. ### Multi-select issue cards -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. -> - [Placed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md), disabled by default in GitLab 14.0. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md) named `board_multi_select` in GitLab 14.0. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an @@ -605,6 +679,10 @@ The feature is not ready for production use. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. +Prerequisites: + +- You must have at least the Reporter role for the project. + To select and move multiple cards: 1. Select each card with <kbd>Control</kbd>+`Click` on Windows or Linux, or <kbd>Command</kbd>+`Click` on MacOS. @@ -612,22 +690,6 @@ To select and move multiple cards:  -### First time using an issue board - -> - The automatic creation of the **To Do** and **Doing** lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. In GitLab 13.7 and later, the **To Do** and **Doing** columns are not automatically created. - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. -The **To Do** and **Doing** columns are no longer automatically created. - -In GitLab 13.5 and 13.6, the first time you open an issue board, you are presented with the default lists -(**Open**, **To Do**, **Doing**, and **Closed**). - -If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and -their lists appear as empty. If any of them already exists, the list is filled with the issues that -have that label. - ## Tips A few things to remember: diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index 41de91d9bd7..ef864dc2743 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -8,8 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4. -In order to communicate synchronously for incidents management, -GitLab allows to associate a Zoom meeting with an issue. +To communicate synchronously for incidents management, +you can associate a Zoom meeting with an issue. After you start a Zoom call for a fire-fight, you need a way to associate the conference call with an issue. This is so that your team members can join swiftly without requesting a link. @@ -36,6 +36,9 @@ You are only allowed to attach a single Zoom meeting to an issue. If you attempt to add a second Zoom meeting using the `/zoom` quick action, it doesn't work. You need to [remove it](#removing-an-existing-zoom-meeting-from-an-issue) first. +Users on GitLab Premium and higher can also +[add multiple Zoom links to incidents](../../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). + ## Removing an existing Zoom meeting from an issue Similarly to adding a Zoom meeting, you can remove it with a quick action: diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 402ce4bebec..5a1e66c8f7d 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -22,7 +22,7 @@ confidential checkbox and hit **Save changes**. When you create a confidential issue in a project, the project becomes listed in the **Contributed projects** section in your [profile](../../profile/index.md). **Contributed projects** does not show information about the confidential issue; it only shows the project name. - + ## Modify issue confidentiality @@ -39,9 +39,12 @@ The second way is to locate the **Confidentiality** section in the sidebar and s |  |  | Every change from regular to confidential and vice versa, is indicated by a -system note in the issue's comments. +system note in the issue's comments: - + + +- **{eye-slash}** The issue is made confidential. +- **{eye}** The issue is made public. When an issue is made confidential, only users with at least the Reporter role for the project have access to the issue. @@ -51,7 +54,7 @@ the issue even if they were actively participating before the change. ## Confidential issue indicators There are a few things that visually separate a confidential issue from a -regular one. In the issues index page view, you can see the eye-slash (**{eye-slash}**) icon +regular one. In the issues index page view, you can see the confidential (**{eye-slash}**) icon next to the issues that are marked as confidential:  @@ -61,7 +64,7 @@ you cannot see confidential issues at all. --- -Likewise, while inside the issue, you can see the eye-slash icon right next to +Likewise, while inside the issue, you can see the confidential (**{eye-slash}**) icon right next to the issue number. There is also an indicator in the comment area that the issue you are commenting on is confidential. diff --git a/doc/user/project/issues/img/confidential_issues_create.png b/doc/user/project/issues/img/confidential_issues_create.png Binary files differdeleted file mode 100644 index 0a141eb39f8..00000000000 --- a/doc/user/project/issues/img/confidential_issues_create.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_create_v15_4.png b/doc/user/project/issues/img/confidential_issues_create_v15_4.png Binary files differnew file mode 100644 index 00000000000..ff489ad8605 --- /dev/null +++ b/doc/user/project/issues/img/confidential_issues_create_v15_4.png diff --git a/doc/user/project/issues/img/confidential_issues_system_notes.png b/doc/user/project/issues/img/confidential_issues_system_notes.png Binary files differdeleted file mode 100644 index 355be80ecb6..00000000000 --- a/doc/user/project/issues/img/confidential_issues_system_notes.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png b/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png Binary files differnew file mode 100644 index 00000000000..e448f609112 --- /dev/null +++ b/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png diff --git a/doc/user/project/issues/img/issue_weight_v13_11.png b/doc/user/project/issues/img/issue_weight_v13_11.png Binary files differdeleted file mode 100644 index 842c154ea49..00000000000 --- a/doc/user/project/issues/img/issue_weight_v13_11.png +++ /dev/null diff --git a/doc/user/project/issues/img/related_issue_block_v15_3.png b/doc/user/project/issues/img/related_issue_block_v15_3.png Binary files differindex 827ddeabf10..942f7a33fe0 100644 --- a/doc/user/project/issues/img/related_issue_block_v15_3.png +++ b/doc/user/project/issues/img/related_issue_block_v15_3.png diff --git a/doc/user/project/issues/img/related_issues_add_v15_3.png b/doc/user/project/issues/img/related_issues_add_v15_3.png Binary files differindex 7c6edf61427..28739c0b909 100644 --- a/doc/user/project/issues/img/related_issues_add_v15_3.png +++ b/doc/user/project/issues/img/related_issues_add_v15_3.png diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index fcc53a239dc..21d7fb0a764 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -13,15 +13,56 @@ When you have a lot of issues, it can be hard to get an overview. With weighted issues, you can get a better idea of how much time, value, or complexity a given issue has or costs. -You can set the weight of an issue during its creation, by changing the -value in the dropdown menu. You can set it to a non-negative integer -value from 0, 1, 2, and so on. -You can remove weight from an issue as well. -A user with a Reporter role (or above) can set the weight. +## View the issue weight -This value appears on the right sidebar of an individual issue, as well as -in the issues page next to a weight icon (**{weight}**). +You can view the issue weight on: -As an added bonus, you can see the total sum of all issues on the milestone page. +- The right sidebar of each issue. +- The issues page, next to a weight icon (**{weight}**). +- [Issue boards](../issue_board.md), next to a weight icon (**{weight}**). +- The [milestone](../milestones/index.md) page, as a total sum of issue weights. - +## Set the issue weight + +Prerequisites: + +- You must have at least the Reporter role for the project. + +You can set the issue weight when you create or edit an issue. + +You must enter whole, positive numbers. + +When you change the weight of an issue, the new value overwrites the previous value. + +### When you create an issue + +To set the issue weight when you [create an issue](managing_issues.md#create-an-issue), enter a +number under **Weight**. + +### From an existing issue + +To set the issue weight from an existing issue: + +1. Go to the issue. +1. On the right sidebar, in the **Weight** section, select **Edit**. +1. Enter the new weight. +1. Select any area outside the dropdown list. + +### From an issue board + +To set the issue weight when you [edit an issue from an issue board](../issue_board.md#edit-an-issue): + +1. Go to your issue board. +1. Select an issue card (not its title). +1. On the right sidebar, in the **Weight** section, select **Edit**. +1. Enter the new weight. +1. Select any area outside the dropdown list. + +## Remove issue weight + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To remove the issue weight, follow the same steps as when you [set the issue weight](#set-the-issue-weight), +and select **remove weight**. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 40e5a6d6a92..b4edb238479 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -33,7 +33,7 @@ Prerequisites: To create an issue: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Either: - On the left sidebar, select **Issues**, and then, in the top right corner, select **New issue**. @@ -56,7 +56,7 @@ Prerequisites: To create an issue from a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues**. 1. In the top right corner, select **Select project to create issue**. 1. Select the project you'd like to create an issue for. The button now reflects the selected @@ -103,7 +103,7 @@ Prerequisites: To create an issue from a project issue board: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Issues > Boards**. 1. At the top of a board list, select **New issue** (**{plus-square}**). 1. Enter the issue's title. @@ -111,7 +111,7 @@ To create an issue from a project issue board: To create an issue from a group issue board: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. Select **Issues > Boards**. 1. At the top of a board list, select **New issue** (**{plus-square}**). 1. Enter the issue's title. @@ -138,7 +138,7 @@ Prerequisites: To email an issue to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Issues**. 1. At the bottom of the page, select **Email a new issue to this project**. 1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). @@ -271,7 +271,7 @@ Prerequisites: To edit multiple issues at the same time: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Issues**. 1. Select **Edit issues**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. @@ -304,7 +304,7 @@ Prerequisites: To edit multiple issues at the same time: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues**. 1. Select **Edit issues**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. @@ -458,7 +458,8 @@ The default issue closing pattern regex: #### Disable automatic issue closing -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/240922) in GitLab 15.4: The referenced issue's project setting is checked instead of the project of the commit or merge request. You can disable the automatic issue closing feature on a per-project basis in the [project's settings](../settings/index.md). @@ -469,23 +470,18 @@ Prerequisites: To disable automatic issue closing: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default branch**. -1. Select **Auto-close referenced issues on default branch**. +1. Clear the **Auto-close referenced issues on default branch** checkbox. 1. Select **Save changes**. Referenced issues are still displayed, but are not closed automatically. -The automatic issue closing is disabled by default in a project if the project has the issue tracker -disabled. If you want to enable automatic issue closing, make sure to -[enable GitLab Issues](../settings/index.md#configure-project-visibility-features-and-permissions). - Changing this setting applies only to new merge requests or commits. Already closed issues remain as they are. -If issue tracking is enabled, disabling automatic issue closing only applies to merge requests -attempting to automatically close issues in the same project. -Merge requests in other projects can still close another project's issues. +Disabling automatic issue closing only applies to issues in the project where the setting was disabled. +Merge requests and commits in this project can still close another project's issues. #### Customize the issue closing pattern **(FREE SELF)** @@ -602,7 +598,7 @@ GitLab displays the results on-screen, but you can also > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Issues > List**. 1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10. @@ -644,10 +640,15 @@ To copy the issue's email address: > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.5. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.9. Feature flags `real_time_issue_sidebar` and `broadcast_issue_updates` removed. -Assignees in the sidebar are updated in real time. -When you're viewing an issue and somebody changes its assignee, +Some sections of the right sidebar are updated in real time. +When you're viewing an issue and somebody changes one of the values, you can see the change without having to refresh the page. +The following sections are updated in real time: + +- [Assignee](#assignee) +- Labels, [if enabled](../labels.md#real-time-changes-to-labels) + ## Assignee An issue can be assigned to one or [more users](multiple_assignees_for_issues.md). @@ -685,6 +686,7 @@ Up to five similar issues, sorted by most recently updated, are displayed below > - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab 13.4 and later. > - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218618) in GitLab 15.4: health status is visible on issue cards in issue boards. To help you track issue statuses, you can assign a status to each issue. This status marks issues as progressing as planned or needing attention to keep on schedule. @@ -703,7 +705,11 @@ To edit health status of an issue: - Needs attention (amber) - At risk (red) -You can then see the issue's status in the issues list and the epic tree. +You can see the issue’s health status in: + +- Issues list +- Epic tree +- Issue cards in issue boards After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled until the issue is reopened. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 9dc361b403f..d1e62a76103 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -29,7 +29,7 @@ Prerequisites: To link one issue to another: -1. In the **Linked issues** section of an issue, +1. In the **Linked items** section of an issue, select the add linked issue button (**{plus}**). 1. Select the relationship between the two issues. Either: - **relates to** @@ -61,7 +61,7 @@ You can also add a linked issue from a commit message or the description in anot ## Remove a linked issue -In the **Linked issues** section of an issue, select the remove button (**{close}**) on the +In the **Linked items** section of an issue, select the remove button (**{close}**) on the right-side of each issue token to remove. Due to the bi-directional relationship, the relationship no longer appears in either issue. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 62c5489d9c3..13c93fadf6e 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -58,7 +58,7 @@ You can also assign and unassign labels with [quick actions](quick_actions.md): To view the **project's labels**: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. Or: @@ -75,7 +75,7 @@ project or group path where it was created. To view the **group's labels**: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Labels**. Or: @@ -97,7 +97,7 @@ Prerequisites: To create a project label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You @@ -131,7 +131,7 @@ To do so: To create a group label: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You @@ -171,7 +171,7 @@ Prerequisites: To edit a **project** label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). @@ -179,7 +179,7 @@ To edit a **project** label: To edit a **group** label: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). @@ -197,7 +197,7 @@ Prerequisites: To delete a **project** label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Either: @@ -210,7 +210,7 @@ To delete a **project** label: To delete a **group** label: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Labels**. 1. Either: @@ -240,7 +240,7 @@ Prerequisites: To promote a project label to a group label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and select **Promote to group label**. @@ -291,7 +291,7 @@ Prerequisites: To add the default labels to the project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Select **Generate a default set of labels**. @@ -430,7 +430,7 @@ Prerequisites: To prioritize a label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Next to a label you want to prioritize, select the star (**{star-o}**). diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 4a6272a0ca3..8d8169e8454 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -68,7 +68,7 @@ Prerequisite: To add a user to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Select **Invite members**. 1. Enter an email address and select a [role](../../permissions.md). @@ -106,7 +106,7 @@ Prerequisite: To add groups to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Select **Invite a group**. 1. Select a group. @@ -131,7 +131,7 @@ Prerequisite: To import users: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Select **Import from a project**. 1. Select the project. You can view only the projects for which you're a maintainer. @@ -175,7 +175,7 @@ Prerequisites: To remove a member from a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Next to the project member you want to remove, select **Remove member**. 1. Optional. In the confirmation box, select the @@ -197,7 +197,7 @@ You can filter and sort members in a project. ### Display inherited members -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press <kbd>Enter</kbd>. @@ -206,7 +206,7 @@ You can filter and sort members in a project. ### Display direct members -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. In the **Filter members** box, select `Membership` `=` `Direct`. 1. Press <kbd>Enter</kbd>. @@ -229,7 +229,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last GitLab users can request to become a member of a project. -1. On the top bar, select **Menu > Projects** and find the project you want to be a member of. +1. On the top bar, select **Main menu > Projects** and find the project you want to be a member of. 1. By the project name, select **Request Access**.  @@ -253,7 +253,7 @@ Prerequisite: - You must be the project owner. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Under **Project visibility**, select **Users can request access**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 3d5b855a9d3..ee161deaabb 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -48,6 +48,7 @@ After sharing 'Project Acme' with 'Engineering': - The group is listed in the **Groups** tab. - The project is listed on the group dashboard. +- All members, including members from the ancestors of the 'Engineering' group, gain access to 'Project Acme' with an access level based on the outcome of [maximum access level](#maximum-access-level). When you share a project, be aware of the following restrictions and outcomes: @@ -83,7 +84,7 @@ The following outcomes occur: ## Share project with group lock -It is possible to prevent projects in a group from +It is possible to prevent projects in a group from [sharing a project with another group](../members/share_project_with_groups.md). This allows for tighter control over project access. diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index c9278c19322..32548215054 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -32,8 +32,9 @@ use the default approval rules from the target (upstream) project, not the sourc To add a merge request approval rule: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**, and then select **Add approval rule**. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. +1. Select **Add approval rule**. 1. Add a human-readable **Rule name**. 1. Set the number of required approvals in **Approvals required**. A value of `0` makes [the rule optional](#configure-optional-approval-rules), and any number greater than `0` @@ -65,8 +66,9 @@ to existing merge requests: To edit a merge request approval rule: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**, and then select **Edit**. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. +1. Select **Edit** next to the rule you want to edit. 1. Optional. Change the **Rule name**. 1. Set the number of required approvals in **Approvals required**. The minimum value is `0`. 1. Add or remove eligible approvers, as needed: @@ -155,11 +157,11 @@ approve in these ways: If you add [code owners](../../code_owners.md) to your repository, the owners of files become eligible approvers in the project. To enable this merge request approval rule: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Locate **All eligible users** and select the number of approvals required: +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. +1. Locate the **All eligible users** rule, and select the number of approvals required: - +  You can also [require code owner approval](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch) @@ -182,9 +184,10 @@ granting them push access: and select the Reporter role for the user. 1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group-of-users), based on the Reporter role. -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select **Add approval rule** or **Update approval rule** and target the protected branch. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**, and either: + - For a new rule, select **Add approval rule** and target the protected branch. + - For an existing rule, select **Edit** and target the protected branch. 1. [Add the group](../../../group/manage.md#create-a-group) to the permission list.  @@ -226,12 +229,12 @@ Approval rules are often relevant only to specific branches, like your approval rule for certain branches: 1. [Create an approval rule](#add-an-approval-rule). -1. Go to your project and select **Settings**. -1. Expand **Merge request (MR) approvals**. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. 1. Select a **Target branch**: - To apply the rule to all branches, select **All branches**. - To apply the rule to all protected branches, select **All protected branches** (GitLab 15.3 and later). - - To apply the rule to a specific branch, select it from the list: + - To apply the rule to a specific branch, select it from the list. 1. To enable this configuration, read [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 3ca8ddb508a..4fdf6d46b8b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -16,8 +16,8 @@ those rules are applied as a merge request moves toward completion. To view or edit merge request approval settings: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. +1. Go to your project and select **Settings > Merge requests**. +1. Expand **Approvals**. ### Approval settings @@ -44,9 +44,9 @@ You can further define what happens to existing approvals when commits are added By default, the author of a merge request cannot approve it. To change this setting: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Clear the **Prevent approval by author** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + clear the **Prevent approval by author** checkbox. 1. Select **Save changes**. Authors can edit the approval rule in an individual merge request and override @@ -68,9 +68,9 @@ the project level or [instance level](../../../admin_area/merge_requests_approva you can prevent committers from approving merge requests that are partially their own. To do this: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent approvals by users who add commits** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Prevent approvals by users who add commits**. If this checkbox is cleared, an administrator has disabled it [at the instance level](../../../admin_area/merge_requests_approvals.md), and it can't be changed at the project level. @@ -94,9 +94,9 @@ By default, users can override the approval rules you [create for a project](rul on a per-merge-request basis. If you don't want users to change approval rules on merge requests, you can disable this setting: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent editing approval rules in merge requests** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Prevent editing approval rules in merge requests**. 1. Select **Save changes**. This change affects all open merge requests. @@ -112,9 +112,9 @@ permission enables an electronic signature for approvals, such as the one define 1. Enable password authentication for the web interface, as described in the [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Require user password to approve** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Require user password to approve**. 1. Select **Save changes**. ## Remove all approvals when commits are added to the source branch @@ -123,9 +123,9 @@ By default, an approval on a merge request remains in place, even if you add mor after the approval. If you want to remove all existing approvals on a merge request when more changes are added to it: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Remove all approvals when commits are added to the source branch** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Remove all approvals when commits are added to the source branch**. 1. Select **Save changes**. Approvals aren't removed when a merge request is [rebased from the UI](../methods/index.md#rebasing-in-semi-linear-merge-methods) @@ -143,10 +143,9 @@ Prerequisite: To do this: -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 **Remove approvals by Code Owners if their files changed**. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Remove approvals by Code Owners if their files changed**. 1. Select **Save changes**. ## Code coverage check approvals diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 14f3979cf34..2040995280e 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -7,61 +7,106 @@ type: reference, concepts # Cherry-pick changes **(FREE)** -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. +In Git, *cherry-picking* is taking a single commit from one branch and adding it +as the latest commit on another branch. The rest of the commits in the source branch +are not added to the target. You should cherry-pick a commit when you need the +change contained in a single commit, but you can't or don't want to pull the +entire contents of that branch into another. -## Cherry-pick a merge request +You can use the GitLab UI to cherry-pick single commits or entire merge requests. +You can even cherry-pick a commit from [a fork of your project](#cherry-pick-into-a-project). -After the merge request has been merged, a **Cherry-pick** button displays -to cherry-pick the changes introduced by that merge request. +NOTE: +Support for tracking commits cherry-picked from the command line +is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/202215). - +## Cherry-pick example + +In this example of cherry-picking, a Git repository has two branches: `develop` and `main`. +This example shows a cherry-picked commit from one branch being added to another: + +```mermaid +gitGraph + commit id: "A" + branch develop + commit id:"B" + checkout main + commit id:"C" + checkout develop + commit id:"D" + checkout main + commit id:"E" + cherry-pick id:"B" + commit id:"G" + checkout develop + commit id:"H" +``` -After you select that button, a modal displays a -[branch filter search box](../repository/branches/index.md#branch-filter-search-box) -where you can choose to either: +In this example, a cherry-pick of commit `B` from the `develop` branch is added +after commit `E` in the `main` branch. -- Cherry-pick the changes directly into the selected branch. -- Create a new merge request with the cherry-picked changes. +Commit `G` is added after the cherry-pick. -### Track a cherry-pick +## Cherry-pick all changes from a merge request -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. +After a merge request is merged, you can cherry-pick all changes introduced +by the merge request: -When you cherry-pick a merge commit, GitLab displays a system note to the related merge -request thread. It crosslinks the new commit and the existing merge request. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**, and find your merge request. +1. Scroll to the merge request reports section, and find the **Merged by** report. +1. In the top right, select **Cherry-pick**: - +  +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. -Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. +## Cherry-pick a single commit -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). +You can cherry-pick a single commit from multiple locations in your GitLab project. -## Cherry-pick a commit +### From a project's commit list -You can cherry-pick a commit from the commit details page: +To cherry-pick a commit from the list of all commits for a project: - +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Commits**. +1. Select the title of the commit you want to cherry-pick. +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. -Similar to cherry-picking a merge request, you can cherry-pick the changes -directly into the target branch or create a new merge request to cherry-pick the -changes. +### From a merge request -When cherry-picking merge commits, the mainline is always the -first parent. If you want to use a different mainline, you need to do that -from the command line. +You can cherry-pick commits from any merge request in your project, regardless of +whether the merge request is open or closed. To cherry-pick a commit from the +list of commits included in a merge request: -Here's a quick example to cherry-pick a merge commit using the second parent as the -mainline: +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**, and find your merge request. +1. In the merge request's secondary menu, select **Commits** to display the commit details page. +1. Select the title of the commit you want to cherry-pick. +1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. -```shell -git cherry-pick -m 2 7a39eb0 -``` +### From the file view of a repository -### Cherry-pick into a project +You can cherry-pick from the list of previous commits affecting an individual file +when you view that file in your project's Git repository: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files** and go to the file + changed by the commit. +1. Select **History**, then select the title of the commit you want to cherry-pick. +1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. + +## Cherry-pick into a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11 behind a [feature flag](../../feature_flags.md), disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0. @@ -70,25 +115,38 @@ You can cherry-pick merge requests from the same project, or forks of the same project, from the GitLab user interface: 1. In the merge request's secondary menu, select **Commits** to display the commit details page. -1. Select the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. +1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch:  1. Optional. Select **Start a new merge request** if you're ready to create a merge request. 1. Select **Cherry-pick**. +## View system notes for cherry-picked commits + +When you cherry-pick a merge commit in the GitLab UI or API, GitLab adds a system note +to the related merge request thread in the format **{cherry-pick-commit}** +`[USER]` **picked the changes into the branch** `[BRANCHNAME]` with commit** `[SHA]` `[DATE]`: + + + +The system note crosslinks the new commit and the existing merge request. +Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. + ## Related topics -- The [Commits API](../../../api/commits.md) enables you to add custom messages - to changes you cherry-pick through the API. +- Use the [Commits API](../../../api/commits.md) to add custom messages + to changes when you use the API to cherry-pick. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Selecting a different parent commit when cherry-picking -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +When you cherry-pick a merge commit in the GitLab UI, the mainline is always the +first parent. Use the command line to cherry-pick with a different mainline. + +Here's a quick example to cherry-pick a merge commit using the second parent as the +mainline: + +```shell +git cherry-pick -m 2 7a39eb0 +``` diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 6f9bc452b96..99a1739b1a4 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -29,8 +29,8 @@ Prerequisite: To do this: -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General** and expand **Merge requests**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. 1. Depending on the type of template you want to create, scroll to either [**Merge commit message template**](#default-template-for-merge-commits) or [**Squash commit message template**](#default-template-for-squash-commits). diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index f30b20e9d34..1a44126f7ff 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -14,7 +14,7 @@ There are many different ways to create a merge request. You can create a merge request from the list of merge requests. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. 1. In the top right, select **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. @@ -43,7 +43,7 @@ You can create a merge request when you add, edit, or upload a file to a reposit You can create a merge request when you create a branch. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Repository > Branches**. 1. Type a branch name and select **New branch**. 1. Above the file list, on the right side, select **Create merge request**. @@ -90,7 +90,7 @@ to reduce the need for editing merge requests manually through the UI. You can create a merge request from your fork to contribute back to the main project. -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select your fork of the repository. 1. On the left menu, go to **Merge requests**, and select **New merge request**. 1. In the **Source branch** drop-down list box, select the branch in your forked repository as the source branch. @@ -120,7 +120,7 @@ Prerequisites: To create a merge request by sending an email: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. 1. In the top right, select **Email a new merge request to this project**. An email address is displayed. Copy this address. @@ -165,7 +165,7 @@ scenarios when you create a new merge request: To have merge requests from a fork by default target your own fork (instead of the upstream project), you can change the default. -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Settings > General > Merge requests**. 1. In the **Target project** section, select the option you want to use for your default target project. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 893b2bc6811..f997898f5a5 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Compliance 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 --- @@ -12,7 +12,7 @@ Export all the data collected from a project's merge requests into a comma-separ To export merge requests to a CSV file: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** . 1. Add any searches or filters. This can help you keep the size of the CSV file under the 15MB limit. The limit ensures the file can be emailed to a variety of email providers. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md new file mode 100644 index 00000000000..5b88e69357c --- /dev/null +++ b/doc/user/project/merge_requests/dependencies.md @@ -0,0 +1,163 @@ +--- +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 +--- + +# Merge request dependencies **(PREMIUM)** + +A single feature can span several merge requests, spread out across multiple projects, +and the order in which the work merges can be significant. Use merge request dependencies +when it's important to merge work in a specific order. Some examples: + +- Ensure changes to a required library are merged before changes to a project that + imports the library. +- Prevent a documentation-only merge request from merging before the feature work + is itself merged. +- Require a merge request updating a permissions matrix to merge, before merging work + from someone who hasn't yet been granted permissions. + +If your project `me/myexample` imports a library from `myfriend/library`, +you might want to update your project to use a new feature in `myfriend/library`. +However, if you merge changes to your project before the external library adds the +new feature, you would break the default branch in your project. A merge request +dependency prevents your work from merging too soon: + +```mermaid +graph TB + A['me/myexample' project] + B['myfriend/library' project] + C[Merge request #1:<br>Create new version 2.5] + D[Merge request #2:<br>Add version 2.5<br>to build] + A-->|contains| D + B---->|contains| C + D-.->|depends on| C + C-.->|blocks| D +``` + +You could mark your `me/myexample` merge request as a [draft](drafts.md) +and explain why in the comments. However, this approach is manual and does not scale, especially +if your merge request relies on several others in multiple projects. Instead, +use the draft (or ready) state to track the readiness of an individual +merge request, and a merge request dependency to enforce merge order. + +NOTE: +Merge request dependencies are a **PREMIUM** feature, but this restriction is +enforced only for the dependent merge request. A merge request in a **PREMIUM** +project can depend on a merge request in a **FREE** project, but a merge request +in a **FREE** project cannot be marked as dependent. + +## View dependencies for a merge request + +If a merge request is dependent on another, the merge request reports section shows +information about the dependency: + + + +To view dependency information on a merge request: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and identify your merge request. +1. Scroll to the merge request reports area. Dependent merge requests display information + about the total number of dependencies set, such as + **(status-warning)** **Depends on 1 merge request being merged**. +1. Select **Expand** to view the title, milestone, assignee, and pipeline status + of each dependency. + +Until your merge request's dependencies all merge, your merge request +cannot be merged. The message +**Merge blocked: you can only merge after the above items are resolved** displays. + +### Closed merge requests + +Closed merge requests still prevent their dependents from being merged, because +a merge request can close regardless of whether or not the planned work actually merged. + +If a merge request closes and the dependency is no longer relevant, +remove it as a dependency to unblock the dependent merge request. + +## Create a new dependent merge request + +When you create a new merge request, you can prevent it from merging until after +other specific work merges, even if the merge request is in a different project. + +Prerequisites: + +- You must have at least the Developer role or be allowed to create merge requests in the project. +- The dependent merge request must be in a project in a **PREMIUM** or higher tier. + +To create a new merge request and mark it as dependent on another: + +1. [Create a new merge request](creating_merge_requests.md). +1. In **Merge request dependencies**, paste either the reference or the full URL + to the merge requests that should merge before this work merges. References + are in the form of `path/to/project!merge_request_id`. +1. Select **Create merge request**. + +## Edit a merge request to add a dependency + +You can edit an existing merge request and mark it as dependent on another. + +Prerequisite: + +- You must have at least the Developer role or be allowed to edit merge requests in the project. + +To do this: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and identify your merge request. +1. Select **Edit**. +1. In **Merge request dependencies**, paste either the reference or the full URL + to the merge requests that should merge before this work merges. References + are in the form of `path/to/project!merge_request_id`. + +## Remove a dependency from a merge request + +You can edit a dependent merge request and remove a dependency. + +Prerequisite: + +- You must have a role in the project that allows you to edit merge requests. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and identify your merge request. +1. Select **Edit**. +1. Scroll to **Merge request dependencies** and select **Remove** next to the reference + for each dependency you want to remove. + + NOTE: + Dependencies for merge requests you don't have access to are displayed as + **1 inaccessible merge request**, and can be removed the same way. +1. Select **Save changes**. + +## Troubleshooting + +### API support for managing merge request dependencies + +No API support exists for managing dependencies. For more information, read +[issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551). + +### Preserving dependencies on project import or export + +Dependencies are not preserved when projects are imported or exported. For more +information, read [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549). + +### Complex merge order dependencies are unsupported + +GitLab supports direct dependencies between merge requests, but does not support +[indirect (nested) dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/11393). + +Acceptable dependency patterns include: + +- A single merge request can directly depend on a single merge request. +- A single merge request can directly depend on multiple merge requests. +- Multiple merge requests can directly depend on a single merge request. + +The indirect, nested dependency between `myfriend/library!10` and `mycorp/example!100` shown in this example is not supported: + +```mermaid +graph LR; + A[myfriend/library!10]-->|depends on| B[herfriend/another-lib!1] + B-->|depends on| C[mycorp/example!100] +``` diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 4bb6034c0bd..695c6d7e612 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -20,6 +20,7 @@ the **Merge** button until you remove the **Draft** flag: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/228685) all support for using **WIP** in GitLab 14.8. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. +> `/draft` quick action as a toggle [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4. There are several ways to flag a merge request as a draft: @@ -29,8 +30,7 @@ There are several ways to flag a merge request as a draft: below the **Title** field. - **Commenting in an existing merge request**: Add the `/draft` [quick action](../quick_actions.md#issues-merge-requests-and-epics) - in a comment. This quick action is a toggle, and can be repeated to change the status - back to Ready. + in a comment. GitLab 15.4 [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) the toggle behavior of `/draft`. To mark a merge request as ready, use `/ready`. - **Creating a commit**: Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the merge request's source branch. This is not a toggle, and adding this text again in a later commit doesn't mark the diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 09ee828ffd3..9475c0d60ab 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -66,7 +66,7 @@ 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). -- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. +- Add [merge request dependencies](dependencies.md) to restrict it to be merged only when other merge requests have been merged. - 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). - [Allow collaboration on merge requests across forks](allow_collaboration.md). diff --git a/doc/user/project/merge_requests/img/cancel-mwps_v15_4.png b/doc/user/project/merge_requests/img/cancel-mwps_v15_4.png Binary files differnew file mode 100644 index 00000000000..7ed780d4389 --- /dev/null +++ b/doc/user/project/merge_requests/img/cancel-mwps_v15_4.png diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png b/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png Binary files differdeleted file mode 100644 index c98821548f8..00000000000 --- a/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png b/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png Binary files differdeleted file mode 100644 index 8b51503419b..00000000000 --- a/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png b/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png Binary files differdeleted file mode 100644 index 919b576fcc6..00000000000 --- a/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png b/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png Binary files differnew file mode 100644 index 00000000000..d18c4aaec20 --- /dev/null +++ b/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png diff --git a/doc/user/project/merge_requests/img/cherry_pick_v15_4.png b/doc/user/project/merge_requests/img/cherry_pick_v15_4.png Binary files differnew file mode 100644 index 00000000000..174bb113961 --- /dev/null +++ b/doc/user/project/merge_requests/img/cherry_pick_v15_4.png diff --git a/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png b/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png Binary files differdeleted file mode 100644 index 4edf0648794..00000000000 --- a/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/dependencies_view_v15_3.png b/doc/user/project/merge_requests/img/dependencies_view_v15_3.png Binary files differnew file mode 100644 index 00000000000..d044e28046f --- /dev/null +++ b/doc/user/project/merge_requests/img/dependencies_view_v15_3.png diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png Binary files differdeleted file mode 100644 index 9487264b41a..00000000000 --- a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.png Binary files differdeleted file mode 100644 index 70fa2efc855..00000000000 --- a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/mwps_v15_4.png b/doc/user/project/merge_requests/img/mwps_v15_4.png Binary files differnew file mode 100644 index 00000000000..f042912d470 --- /dev/null +++ b/doc/user/project/merge_requests/img/mwps_v15_4.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 35ec075c674..500fb95c193 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -27,7 +27,7 @@ You can view merge requests for your project, group, or yourself. To view all merge requests for a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. @@ -36,7 +36,7 @@ Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd> To view merge requests for all projects in a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Merge requests**. If your group contains subgroups, this view also displays merge requests from the subgroup projects. @@ -160,13 +160,11 @@ change and whether you need access to a development environment: ## Assign a user to a merge request -When a merge request is created, it's assigned by default to the person who created it. -This person owns the merge request, but isn't responsible for [reviewing it](reviews/index.md). -To assign the merge request to someone else, use the `/assign @user` +To assign the merge request to a user, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area in a merge request, or: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit**. @@ -186,7 +184,7 @@ accountable for it: To assign multiple assignees to a merge request, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area, or: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit** and, from the dropdown list, select all users you want diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 6bfef6ab134..6242a77e931 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -1,141 +1,11 @@ --- -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 +redirect_to: 'dependencies.md' +remove_date: '2022-11-22' --- -# Merge request dependencies **(PREMIUM)** +This document was moved to [another location](dependencies.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in GitLab 12.2. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge request dependencies" in GitLab 12.4. -> - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in GitLab 12.4. - -Merge request dependencies allows a required order of merging -between merge requests to be expressed. If a merge request "depends on" another, -then it cannot be merged until its dependency is itself merged. - -NOTE: -Merge requests dependencies are a **PREMIUM** feature, but this restriction is -only enforced for the dependent merge request. A merge request in a **FREE** -project can be a dependency of a **PREMIUM** merge request, but not -the other way around. - -## Use cases - -- Ensure changes to a library are merged before changes to a project that - imports the library. -- Prevent a documentation-only merge request from being merged before the merge request - implementing the feature to be documented. -- Require a merge request updating a permissions matrix to be merged before merging a - merge request from someone who hasn't yet been granted permissions. - -It is common for a single logical change to span several merge requests, spread -out across multiple projects, and the order in which they are merged can be -significant. - -For example, given a project `mycorp/awesome-project` that imports a library -at `myfriend/awesome-lib`, adding a feature in `awesome-project` may **also** -require changes to `awesome-lib`, and so necessitate two merge requests. Merging -the `awesome-project` merge request before the `awesome-lib` one would -break the default branch. - -The `awesome-project` merge request could be [marked as **Draft**](drafts.md), -and the reason for the draft stated included in the comments. However, this -requires the state of the `awesome-lib` merge request to be manually -tracked, and doesn't scale well if the `awesome-project` merge request -depends on changes to **several** other projects. - -By making the `awesome-project` merge request depend on the -`awesome-lib` merge request instead, this relationship is -automatically tracked by GitLab, and the draft state can be used to -communicate the readiness of the code in each individual merge request -instead. - -## Configuration - -To continue the above example, you can configure a dependency when creating the -new merge request in `awesome-project` (or by editing it, if it already exists). -The dependency needs to be configured on the **dependent** merge -request. There is a **Merge request dependencies** section in the form: - - - -Anyone who can edit a merge request can change the list of dependencies. - -New dependencies can be added by reference, or by URL. To remove a dependency, -press the **X** by its reference. - -As dependencies can be specified across projects, it's possible that someone else -has added a dependency for a merge request in a project you don't have access to. -These are shown as a simple count: - - - -If necessary, you can remove all the dependencies like this by pressing the -**X**, just as you would for a single, visible dependency. - -Once you're finished, press the **Save changes** button to submit the request, -or **Cancel** to return without making any changes. - -The list of configured dependencies, and the status of each one, is shown in the -merge request widget: - - - -Until all dependencies have, themselves, been merged, the **Merge** -button is disabled for the dependent merge request. In -particular, note that **closed merge requests** still prevent their -dependents from being merged - it is impossible to automatically -determine whether the dependency expressed by a closed merge request -has been satisfied in some other way or not. - -If a merge request has been closed **and** the dependency is no longer relevant, -it must be removed as a dependency, following the instructions above, before -merge. - -## Limitations - -- API support: [issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551) -- Dependencies are not preserved across project export/import: [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549) -- Complex merge order dependencies are not supported: [issue #11393](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) - -The last item merits a little more explanation. Dependencies between merge -requests can be described as a graph of relationships. The simplest possible -graph has one merge request that depends upon another: - -```mermaid -graph LR; - myfriend/awesome-lib!10-->mycorp/awesome-project!100; -``` - -A more complex (and still supported) graph might have one merge request that -directly depends upon several others: - -```mermaid -graph LR; - myfriend/awesome-lib!10-->mycorp/awesome-project!100; - herfriend/another-lib!1-->mycorp/awesome-project!100; -``` - -Several different merge requests can also directly depend upon the -same merge request: - -```mermaid -graph LR; - herfriend/another-lib!1-->myfriend/awesome-lib!10; - herfriend/another-lib!1-->mycorp/awesome-project!100; -``` - -What is **not** supported is a "deep", or "nested" graph of dependencies. For example: - -```mermaid -graph LR; - herfriend/another-lib!1-->myfriend/awesome-lib!10; - myfriend/awesome-lib!10-->mycorp/awesome-project!100; -``` - -In this example, `myfriend/awesome-lib!10` depends on `herfriend/another-lib!1`, -and is itself a dependent of `mycorp/awesome-project!100`. This means that -`myfriend/awesome-lib!10` becomes an **indirect** dependency of -`mycorp/awesome-project!100`, which is not yet supported. +<!-- This redirect file can be deleted after <2022-11-22>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 9182cf11566..57c4ff455cb 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -7,125 +7,143 @@ type: reference, concepts # Merge when pipeline succeeds **(FREE)** -When reviewing a merge request that looks ready to merge but still has a -pipeline running, you can set it to merge automatically when the -pipeline succeeds. This way, you don't have to wait for the pipeline to -finish and remember to merge the request manually. +If you review a merge request and it's ready to merge, but the pipeline hasn't +completed yet, you can set it to merge when the pipeline succeeds (MWPS). You don't +have to remember later to merge the work manually: - + -## How it works +If the pipeline succeeds, the merge request is merged. If the pipeline fails, the +author can either retry any failed jobs, or push new commits to fix the failure: -When you select "Merge When Pipeline Succeeds", the status of the merge -request is updated to show the impending merge. If you can't wait -for the pipeline to succeed, you can choose **Merge immediately** -in the dropdown menu on the right of the main button. +- If a retried job succeeds on the second try, the merge request is merged. +- If new commits are added to the merge request, GitLab cancels the MWPS request + to ensure the new changes are reviewed before merge. -The author of the merge request and project members with the Developer role can -cancel the automatic merge at any time before the pipeline finishes. +## Set a merge request to MWPS - +Prerequisites: -When the pipeline succeeds, the merge request is automatically merged. -When the pipeline fails, the author gets a chance to retry any failed jobs, -or to push new commits to fix the failure. +- You must have at least the Developer role in the project. +- If the project is configured to require it, all threads in the + merge request [must be resolved](../../discussions/index.md#resolve-a-thread). +- The merge request must have received all required approvals. -When the jobs are retried and succeed on the second try, the merge request -is automatically merged. When the merge request is updated with -new commits, the automatic merge is canceled to allow the new -changes to be reviewed. +To do this when pushing from the command line, use the `merge_request.merge_when_pipeline_succeeds` +[push option](../push_options.md). -By default, all threads must be resolved before you see the **Merge when -pipeline succeeds** button. If someone adds a new comment after -the button is selected, but before the jobs in the CI pipeline are -complete, the merge is blocked until you resolve all existing threads. +To do this from the GitLab user interface: -## Only allow merge requests to be merged if the pipeline succeeds +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. +1. Scroll to the merge request reports section. +1. Optional. Select your desired merge options, such as **Delete source branch**, + **Squash commits**, or **Edit commit message**. +1. Select **Merge when pipeline succeeds**. -You can prevent merge requests from being merged if: +If a new comment is added to the merge request after you select **Merge when pipeline succeeds**, +but before the pipeline completes, GitLab blocks the merge until you +resolve all existing threads. -- No pipeline ran. -- The pipeline did not succeed. +## Cancel an auto-merge -This works for both: +If a merge request is set to MWPS, you can cancel it. -- GitLab CI/CD pipelines -- Pipelines run from an [external CI integration](../integrations/index.md#available-integrations) +Prerequisites: + +- You must either be the author of the merge request, or a project member with + at least the Developer role. +- The merge request's pipeline must still be in progress. + +To do this: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. +1. Scroll to the merge request reports section. +1. Select **Cancel auto-merge**. + + + +## Require a successful pipeline for merge + +You can configure your project to require a complete and successful pipeline before +merge. This configuration works for both: + +- GitLab CI/CD pipelines. +- Pipelines run from an [external CI integration](../integrations/index.md#available-integrations). As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md) -does not disable this feature, as it is possible to use pipelines from external -CI providers with this feature. To enable it, you must: +does not disable this feature, but you can use pipelines from external +CI providers with it. + +Prerequisites: + +- Ensure CI/CD is configured to run a pipeline for every merge request. +- You must have at least the Maintainer role in the project. + +To enable this setting: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Scroll to **Merge checks**, and select **Pipelines must succeed**. + This setting also prevents merge requests from being merged if there is no pipeline, + which can [conflict with some rules](#merge-requests-dont-merge-when-successful-pipeline-is-required). +1. Select **Save**. + +### Allow merge after skipped pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. + +When the **Pipelines must succeed** checkbox is checked, +[skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent +merge requests from being merged. + +Prerequisite: -1. On the top bar, select **Menu > Projects** and find your project. +- You must have at least the Maintainer role in the project. + +To change this behavior: + +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Merge requests**. -1. Under **Merge checks**, select the **Pipelines must succeed** checkbox. +1. Under **Merge checks**: + - Select **Pipelines must succeed**. + - Select **Skipped pipelines are considered successful**. 1. Select **Save**. -This setting also prevents merge requests from being merged if there is no pipeline. -You should be careful to configure CI/CD so that pipelines run for every merge request. +## Troubleshooting -### Limitations +### Merge requests don't merge when successful pipeline is required -When this setting is enabled, a merge request is prevented from being merged if there -is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/index.md#only--except) -or [`rules`](../../../ci/yaml/index.md#rules) are used and they don't generate any pipelines. +If you require a successful pipeline for a merge, this setting can conflict with some +use cases that do not generate pipelines, such as [`only/except`](../../../ci/yaml/index.md#only--except) +or [`rules`](../../../ci/yaml/index.md#rules). Ensure your project +[runs a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) for +every merge request, and that the pipeline is successful. -You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) -and that it's successful. +### Ensure test parity between pipeline types -If both a branch pipeline and a merge request pipeline are triggered for a single -merge request, only the success or failure of the *merge request pipeline* is checked. -If the merge request pipeline is configured with fewer jobs than the branch pipeline, -it could allow code that fails tests to be merged: +If a merge request triggers both a branch pipeline and a merge request pipeline, +the success or failure of only the *merge request pipeline* is checked. +If the merge request pipeline contains fewer jobs than the branch pipeline, +it could allow code that fails tests to be merged, like in this example: ```yaml branch-pipeline-job: rules: - if: $CI_PIPELINE_SOURCE == "push" script: - - echo "Code testing scripts here, for example." + - echo "Testing happens here." merge-request-pipeline-job: rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" script: - - echo "No tests run, but this pipeline always succeeds and enables merge." + - echo "No testing happens here. This pipeline always succeeds, and enables merge." - echo true ``` -You should avoid configuration like this, and only use branch (`push`) pipelines -or merge request pipelines, when possible. See [`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines) -for details on avoiding two pipelines for a single merge request. - -### Skipped pipelines - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. - -When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent -merge requests from being merged. To change this behavior: - -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. Under **Merge checks**: - - Ensure **Pipelines must succeed** is selected. - - Select the **Skipped pipelines are considered successful** checkbox. -1. Select **Save**. - -## From the command line - -You can use [Push Options](../push_options.md) to enable merge when pipeline succeeds -for a merge request when pushing from the command line. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +Instead, use branch (`push`) pipelines or merge request pipelines, when possible. +For details on avoiding two pipelines for a single merge request, read the +[`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines). diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index c4e4b40dc48..68dd6477408 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -12,9 +12,8 @@ merge requests are merged into an existing branch. ## Configure a project's merge method -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. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Merge method** section, select your desired merge method. 1. Select **Save changes**. @@ -110,7 +109,7 @@ gitGraph ``` This method is equivalent to `git merge --ff <source-branch>` for regular merges, and to -`git merge -squash <source-branch>` for squash merges. +`git merge --squash <source-branch>` for squash merges. When the fast-forward merge ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 8f433c13887..a6e0740ff78 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -6,50 +6,86 @@ info: To determine the technical writer assigned to the Stage/Group associated w # 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. +You can revert individual commits or an entire merge request in GitLab. +When you revert a commit in Git, you create a new commit that reverses all actions +taken in the original commit: + +- Lines added in the original commit are removed. +- Lines removed in the original commit are added back. +- Lines modified in the original commit are restored to their previous state. + +Your **revert commit** is still subject to your project's access controls and processes. ## Revert a merge request -NOTE: -The **Revert** button is shown only for projects that use the -merge method "Merge Commit", which can be set under the project's -**Settings > General > Merge request**. [Fast-forward commits](methods/index.md#fast-forward-merge) -can not be reverted by using the merge request view. +After a merge request is merged, you can revert all changes in the merge request. + +Prerequisites: -After the merge request has been merged, use the **Revert** button -to revert the changes introduced by that merge request. +- You must have a role in the project that allows you to edit merge requests, and add + code to the repository. +- Your project must use the [merge method](methods/index.md#fast-forward-merge) **Merge Commit**, + which is set in the project's **Settings > General > Merge request**. You can't revert + fast-forwarded commits from the GitLab UI. - +To do this: -After you select that button, a modal appears where you can choose to -revert the changes directly into the selected branch or you can opt to -create a new merge request with the revert changes. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and identify your merge request. +1. Scroll to the merge request reports area, and find the report showing when the + merge request was merged. +1. Select **Revert**. +1. In **Revert in branch**, select the branch to revert your changes into. +1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit. +1. Select **Revert**. -After the merge request has been reverted, the **Revert** button is no longer available. +The option to **Revert** is no longer shown after a merge request is reverted. ## Revert a commit -You can revert a commit from the commit details page: +You can revert any commit in a repository into either: + +- The current branch. +- A new merge request. + +Prerequisites: + +- You must have a role in the project that allows you to edit merge requests, and add + code to the repository. + +To do this: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. If you know the merge request that contains the commit: + 1. On the left sidebar, select **Merge requests** and identify your merge request. + 1. Select **Commits**, then select the title of the commit you want to revert. GitLab displays the contents of the commit. +1. If you don't know the merge request the commit originated from: + 1. On the left sidebar, select **Repository > Commits**. + 1. Select the title of the commit to display full information about the commit. +1. In the top right corner, select **Options**, then select **Revert**. +1. In **Revert in branch**, select the branch to revert your changes into. +1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit. +1. Select **Revert**. + +The option to **Revert** is no longer shown after a commit is reverted. - +### Revert a merge commit to a different parent commit -Similar to reverting a merge request, you can opt to revert the changes -directly into the target branch or create a new merge request to revert the -changes. +When you revert a merge commit, the branch you merged to (usually `main`) is always the +first parent. To revert a merge commit to a different parent, +you must revert the commit from the command line: -After a commit is reverted, the **Revert** button is no longer available. +1. Identify the SHA of the parent commit you want to revert to. +1. Identify the parent number of the commit you want to revert to. (Defaults to 1, for the first parent.) +1. Modify this command, replacing `2` with the parent number, and `7a39eb0` with the commit SHA: -When reverting merge commits, the mainline is always the -first parent. If you want to use a different mainline, you need to do that -from the command line. + ```shell + git revert -m 2 7a39eb0 + ``` -Here's an example to revert a merge commit using the second parent as the -mainline: +## Related topics -```shell -git revert -m 2 7a39eb0 -``` +- [Official `git revert` documentation](https://git-scm.com/docs/git-revert) <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png b/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png Binary files differdeleted file mode 100644 index 38e18115803..00000000000 --- a/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_4.png b/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_4.png Binary files differnew file mode 100644 index 00000000000..47b7be3886d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_4.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 27b223c48ec..78f82b019b8 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -56,12 +56,11 @@ displays next to your name. You can submit your completed review in multiple ways: - Use the `/submit_review` [quick action](../../quick_actions.md) in the text of a non-review comment. -- Select **Finish review** and then **Submit review** in the footer at the bottom of the screen. +- Select **Finish review**, then select **Submit review** at the bottom of the modal window. + In the modal window, you can supply a **Summary comment**, approve the merge request, and + include quick actions: -Selecting **Finish review** opens a modal window to add an optional comment to summarize your review. -You can also include quick actions: - - +  When you submit your review, GitLab: @@ -69,6 +68,7 @@ When you submit your review, GitLab: - Sends a single email to every notifiable user of the merge request, with your 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. +- Optional. Approves the merge request. ### Resolve or unresolve thread with a comment @@ -96,7 +96,7 @@ If you have a review in progress, you can also add a comment from the **Overview ### Approval Rule information for Reviewers **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. +> - [Feature flag `reviewer_approval_rules` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](../approvals/rules.md) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 7e37990b9bf..066149afbb5 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -60,9 +60,8 @@ squash the commits as part of the merge process: To configure the default squashing behavior for all merge requests in your project: -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. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Squash commits when merging** section, select your desired behavior: - **Do not allow**: Squashing is never performed, and the option is not displayed. - **Allow**: Squashing is allowed, but cleared by default. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 0d7794a3ebd..da705a53153 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Compliance 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 @@ -61,9 +61,8 @@ using the API. You don't need to wait for a merge request webhook payload to be Within each project's settings, you can see a list of status checks added to the project: -1. In your project, go to **Settings > General**. -1. Expand the **Merge requests** section. -1. Scroll down to the **Status checks** sub-section. +1. In your project, go to **Settings > Merge requests** section. +1. Scroll down to **Status checks**.  diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index ef734225fb4..723ca17ee56 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -37,27 +37,75 @@ For information about project and group milestones API, see: To view the milestone list: -1. On the top bar, select **Menu > Projects** and find your project or - **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Projects** and find your project or + **Main menu > Groups** and find your group. 1. Select **Issues > Milestones**. In a project, GitLab displays milestones that belong to the project. In a group, GitLab displays milestones that belong to the group and all projects in the group. -NOTE: +### View milestones in a project with issues turned off + If a project has issue tracking [turned off](../settings/index.md#configure-project-visibility-features-and-permissions), you can get to the milestones page -by going to its URL. To do so, add: `/-/milestones` to your project or group URL. -For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/milestones`. -This is tracked in [issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). +by going to its URL. + +To do so: + +1. Go to your project. +1. Add: `/-/milestones` to your project URL. + For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/milestones`. + +Alternatively, this project's issues are visible in the group's milestone page. + +Improving this experience is tracked in issue [339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). ### View all milestones You can view all the milestones you have access to in the entire GitLab namespace. You might not see some milestones because they're in projects or groups you're not a member of. -To do so, on the top bar select **Menu > Milestones**. +To do so, on the top bar select **Main menu > Milestones**. + +### View milestone details + +To view more information about a milestone, +in the milestone list select the title of the milestone you want to view. + +The milestone view shows the title and description. + +There are also tabs below these that show the following: + +- **Issues**: Shows all issues assigned to the milestone. These are displayed in three columns named: + - Unstarted Issues (open and unassigned) + - Ongoing Issues (open and assigned) + - Completed Issues (closed) +- **Merge Requests**: Shows all merge requests assigned to the milestone. These are displayed in four columns named: + - Work in progress (open and unassigned) + - Waiting for merge (open and assigned) + - Rejected (closed) + - Merged +- **Participants**: Shows all assignees of issues assigned to the milestone. +- **Labels**: Shows all labels that are used in issues assigned to the milestone. + +#### Burndown charts + +The milestone view contains a [burndown and burnup chart](burndown_and_burnup_charts.md), +showing the progress of completing a milestone. + + + +#### Milestone sidebar + +The milestone sidebar on the milestone view shows the following: + +- Percentage complete, which is calculated as number of closed issues divided by total number of issues. +- The start date and due date. +- The total time spent on all issues and merge requests assigned to the milestone. +- The total issue weight of all issues assigned to the milestone. + + ## Create a milestone @@ -71,7 +119,7 @@ Prerequisites: To create a milestone: -1. On the top bar, select **Menu > Projects** and find your project or **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues > Milestones**. 1. Select **New milestone**. 1. Enter the title. @@ -90,7 +138,7 @@ Prerequisites: To edit a milestone: -1. On the top bar, select **Menu > Projects** and find your project or **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. 1. Select a milestone's title. 1. Select **Edit**. 1. Edit the title, start date, due date, or description. @@ -106,7 +154,7 @@ Prerequisites: To edit a milestone: -1. On the top bar, select **Menu > Projects** and find your project or **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. 1. Select a milestone's title. 1. Select **Delete**. 1. Select **Delete milestone**. @@ -131,7 +179,7 @@ Prerequisites: To promote a project milestone: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Either: - Select **Promote to Group Milestone** (**{level-up}**). - Select the milestone title, and then select **Promote**. @@ -153,13 +201,13 @@ To assign or unassign a milestone: You can also use the `/assign` [quick action](../quick_actions.md) in a comment. -## Filtering issues and merge requests by milestone +## Filter issues and merge requests by milestone -### Filtering in list pages +### Filters in list pages From the project and group issue/merge request list pages, you can filter by both group and project milestones. -### Filtering in issue boards +### Filters in issue boards From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in: @@ -181,42 +229,6 @@ When filtering by milestone, in addition to choosing a specific project mileston - **Upcoming**: Show issues or merge requests that have been assigned the open milestone and has the nearest due date in the future. - **Started**: Show issues or merge requests that have an open assigned milestone with a start date that is before today. -## Milestone view - -The milestone view shows the title and description. - -There are also tabs below these that show the following: - -- **Issues**: Shows all issues assigned to the milestone. These are displayed in three columns named: - - Unstarted Issues (open and unassigned) - - Ongoing Issues (open and assigned) - - Completed Issues (closed) -- **Merge Requests**: Shows all merge requests assigned to the milestone. These are displayed in four columns named: - - Work in progress (open and unassigned) - - Waiting for merge (open and assigned) - - Rejected (closed) - - Merged -- **Participants**: Shows all assignees of issues assigned to the milestone. -- **Labels**: Shows all labels that are used in issues assigned to the milestone. - -### Burndown Charts - -The milestone view contains a [burndown and burnup chart](burndown_and_burnup_charts.md), -showing the progress of completing a milestone. - - - -### Milestone sidebar - -The milestone sidebar on the milestone view shows the following: - -- Percentage complete, which is calculated as number of closed issues divided by total number of issues. -- The start date and due date. -- The total time spent on all issues and merge requests assigned to the milestone. -- The total issue weight of all issues assigned to the milestone. - - - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 2c668e2c409..03f8ecac77f 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -7,17 +7,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Custom domains and SSL/TLS certificates **(FREE)** -Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4, you can use verified domains to [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). -To use one or more custom domain names with your Pages site, you can: +You can use custom domains: -- Add a [custom **root domain** or a **subdomain**](#set-up-pages-with-a-custom-domain). +- With GitLab Pages. +- To [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). + When using custom domains this way, you use the GitLab Pages feature but can skip the [requirements](#requirements). + +To use one or more custom domain names: + +- Add a [custom **root domain** or a **subdomain**](#set-up-a-custom-domain). - Add [SSL/TLS certification](#adding-an-ssltls-certificate-to-pages). -## Set up Pages with a custom domain +## Set up a custom domain -To set up Pages with a custom domain name, read the requirements -and steps below. +To set up Pages with a custom domain name, read the requirements and steps below. ### Requirements @@ -45,7 +50,7 @@ and steps below. Follow the steps below to add your custom domain to Pages. See also this document for an [overview on DNS records](dns_concepts.md). -#### 1. Add a custom domain to Pages +#### 1. Add a custom domain Navigate to your project's **Setting > Pages** and select **+ New domain** to add your custom domain to GitLab Pages. You can choose whether to: @@ -64,7 +69,7 @@ and paste them in your domain's control panel as a `TXT` record on the next step  -#### 3. Set up DNS records for Pages +#### 3. Set up DNS records Read this document for an [overview of DNS records for Pages](dns_concepts.md). If you're familiar with the subject, follow the instructions below @@ -144,7 +149,7 @@ They require: | `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | If you're using Cloudflare, check -[Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirecting-wwwdomaincom-to-domaincom-with-cloudflare). +[Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirect-wwwdomaincom-to-domaincom-with-cloudflare). > **Notes**: > @@ -186,7 +191,7 @@ from the GitLab project. in place. Your domain is periodically reverified, and may be disabled if the record is removed. -##### Troubleshooting Pages domain verification +##### Troubleshoot domain verification To manually verify that you have properly configured the domain verification `TXT` DNS entry, you can run the following command in your terminal: @@ -218,7 +223,7 @@ For a subdomain: | `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | | `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -### Adding more domain aliases +### Add more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. An alias can be understood as having many doors leading to the same room. @@ -226,7 +231,7 @@ An alias can be understood as having many doors leading to the same room. All the aliases you've set to your site are listed on **Setting > Pages**. From that page, you can view, add, and remove them. -### Redirecting `www.domain.com` to `domain.com` with Cloudflare +### Redirect `www.domain.com` to `domain.com` with Cloudflare If you use Cloudflare, you can redirect `www` to `domain.com` without adding both `www.domain.com` and `domain.com` to GitLab. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 0cc6cb808d1..b5487f7a465 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -30,7 +30,7 @@ Before you can enable automatic provisioning of an SSL certificate for your doma - Acquired a domain (`example.com`) and added a [DNS entry](index.md) pointing it to your Pages website. The top-level domain (`.com`) must be a [public suffix](https://publicsuffix.org/). -- [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) +- [Added your domain to your Pages project](index.md#1-add-a-custom-domain) and verified your ownership. - Verified your website is up and running, accessible through your custom domain. @@ -76,7 +76,7 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. 1. Make sure your domain **doesn't have** an `AAAA` DNS record. 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). - 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain-to-pages). + 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain). 1. Go to step 1. ### Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour @@ -85,7 +85,7 @@ If you've enabled Let's Encrypt integration, but a certificate is absent after a 1. Go to your project's **Settings > Pages**. 1. Select **Remove** on your domain. -1. [Add the domain again and verify it](index.md#1-add-a-custom-domain-to-pages). +1. [Add the domain again and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). 1. If you still see the same message after some time: 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 510f9332e7b..58e15104815 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -16,7 +16,7 @@ Use a `.gitlab-ci.yml` template when you have an existing project that you want Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete these steps, you may have to do additional configuration for the Pages site to generate properly. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select the project's name. 1. From the **Add** (**{plus}**) dropdown, select **New file**. 1. From the **Select a template type** dropdown, select `.gitlab-ci.yml`. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 68a2a6a80ad..1c3d5d722cb 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -266,6 +266,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production ``` Now add another job to the CI file, telling it to @@ -289,6 +290,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production test: stage: test @@ -342,6 +344,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production test: stage: test @@ -386,6 +389,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production test: stage: test @@ -420,7 +424,7 @@ Now GitLab CI/CD not only builds the website, but also: For more information, see the following blog posts. -- Use GitLab CI/CD `environments` to +- Use GitLab CI/CD `environments` to [deploy your web app to staging and production](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). - Learn how to run jobs [sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md new file mode 100644 index 00000000000..7e618fbaec8 --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -0,0 +1,58 @@ +--- +stage: Create +group: Incubation +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 +--- + +# Tutorial: Use the GitLab UI to deploy your static site **(FREE)** + +This tutorial assumes you have a project that either: + +- Generates static sites or a client-rendered single-page application (SPA), + such as [Eleventy](https://www.11ty.dev), [Astro](https://astro.build), or [Jekyll](https://jekyllrb.com). +- Contains a framework configured for static output, such as [Next.js](https://nextjs.org), + [Nuxt.js](https://nuxtjs.org), or [SvelteKit](https://kit.svelte.dev). + +## Update your app to output files to the `public` folder + +GitLab Pages requires all files intended to be part of the published website to +be in a root-level folder called `public`. If you create this folder during the build +pipeline, committing it to Git is not required. + +For detailed instructions, read [Configure the public files folder](../public_folder.md). + +## Set up the `.gitlab-ci.yml` file + +GitLab helps you write the `.gitlab-ci.yml` needed to create your first GitLab Pages +deployment pipeline. Rather than building the file from scratch, it asks you to +provide the build commands, and creates the necessary boilerplate for you. + +To build your YAML file from the GitLab UI: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages** to display the friendly + interface **Get Started With Pages**. +1. If your framework's build process does not need one of the provided build + commands, you can either: + - Skip the step by selecting **Next**. + - Enter `:` (the bash "do nothing" command) if you still want to incorporate that + step's boilerplate into your `.gitlab-ci.yml` file. +1. Optional. Edit and adjust the generated `.gitlab-ci.yml` file as needed. +1. Commit your `.gitlab-ci.yml` to your repository. This commit triggers your first + GitLab Pages deployment. + +## Troubleshooting + +### If you can't see the "Get Started with Pages" interface + +GitLab doesn't show this interface if you have either: + +- Deployed a GitLab Pages site before. +- Committed a `.gitlab-ci.yml` through this interface at least once. + +To fix this problem: + +- If you see the message **Waiting for the Pages Pipeline to complete**, select + **Start over** to start the wizard again. +- If your project has previously deployed GitLab Pages successfully, + [manually update](pages_from_scratch.md) your `.gitlab-ci.yml`. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index af49522efe2..1f3628b74ec 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -38,12 +38,13 @@ Learn more about To create a GitLab Pages website: -| Document | Description | -|----------|-------------| +| Document | Description | +|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------| +| [Use the GitLab UI to create a simple `.gitlab-ci.yml`](getting_started/pages_ui.md) | Add a Pages site to an existing project. Use the UI to set up a simple `.gitlab-ci.yml`. | | [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. | +| [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. | To update a GitLab Pages website: diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 3bd16a17f23..da024881ed6 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -314,6 +314,7 @@ pages: artifacts: paths: - public + environment: production ``` The `FF_USE_FASTZIP` variable enables the [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) which is needed for [`ARTIFACT_COMPRESSION_LEVEL`](../../../ci/runners/configure_runners.md#artifact-and-cache-settings). diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md new file mode 100644 index 00000000000..f9c80875cc9 --- /dev/null +++ b/doc/user/project/pages/public_folder.md @@ -0,0 +1,153 @@ +--- +description: 'Learn how to configure the build output folder for the most +common static site generators' +stage: Create +group: Incubation +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 +--- + +# Configure the public files folder **(FREE)** + +GitLab Pages requires all files you intend to be available in the published website to +be in a root-level folder called `public`. This page describe how +to set this up for some common static site generators. + +## Guide by framework + +### Eleventy + +For Eleventy, you should either: + +1. Add the `--output=public` flag in Eleventy's build commands, for example: + + `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` + +1. Add the following to your `.eleventy.js` file: + + ```javascript + // .eleventy.js + module.exports = function(eleventyConfig) { + return { + dir: { + output: "public" + } + } + }; + ``` + +### Astro + +By default, Astro uses the `public` folder to store static assets. For GitLab Pages, +rename that folder to a collision-free alternative first: + +1. In your project directory, run: + + ```shell + mv public static + ``` + +1. Add the following to your `astro.config.mjs`. This code informs Astro about + our folder name remapping: + + ```javascript + // astro.config.mjs + export default { + // GitLab Pages requires exposed files to be located in a folder called "public". + // So we're instructing Astro to put the static build output in a folder of that name. + dist: 'public', + + // The folder name Astro uses for static files (`public`) is already reserved + // for the build output. So in deviation from the defaults we're using a folder + // called `static` instead. + public: 'static', + }; + ``` + +### SvelteKit + +NOTE: +GitLab Pages supports only static sites. For SvelteKit, +we recommend using [`adapter-static`](https://kit.svelte.dev/docs/adapters#supported-environments-static-sites). + +When using `adapter-static`, add the following to your `svelte.config.js`: + +```javascript +// svelte.config.js +import adapter from '@sveltejs/adapter-static'; + +export default { + kit: { + adapter: adapter({ + pages: 'public' + }) + } +}; +``` + +### Next.js + +NOTE: +GitLab Pages supports only static sites. For Next.js, we +recommend using Next's [Static HTML export functionality](https://nextjs.org/docs/advanced-features/static-html-export) + +Use the `-o public` flag after `next export` as the build command, for +example: + +```shell +next export -o public +``` + +### Nuxt.js + +NOTE: +GitLab Pages supports only static sites. + +1. Add the following to your `nuxt.config.js`: + + ```javascript + export default { + target: 'static', + generate: { + dir: 'public' + } + } + ``` + +1. Configure your Nuxt.js application for + [Static Site Generation](https://nuxtjs.org/docs/features/deployment-targets#static-hosting). + +### Vite + +Update your `vite.config.js` to include the following: + +```javascript +// vite.config.js +export default { + build: { + outDir: 'public' + } +} +``` + +### Webpack + +Update your `webpack.config.js` to include the following: + +```javascript +// webpack.config.js +module.exports = { + output: { + path: __dirname + '/public' + } +}; +``` + +## Should you commit the `public` folder? + +Not necessarily. However, when the GitLab Pages deploy pipeline runs, it looks +for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. So +If you set up a job that creates the `public` folder before deploy, such as by +running `npm run build`, committing the folder isn't required. + +If you prefer to build your site locally, you can commit the `public` folder and +omit the build step during the job, instead. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 3e40a7962ae..9b685592c9d 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -41,7 +41,7 @@ Prerequisite: To protect a branch: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. @@ -63,7 +63,7 @@ Prerequisite: To protect multiple branches at the same time: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, type the branch name and a wildcard. @@ -96,7 +96,7 @@ from the command line or from a Git client application. To create a new branch through the user interface: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Branches**. 1. Select **New branch**. 1. Fill in the branch name and select an existing branch, tag, or commit to @@ -109,7 +109,7 @@ You can force everyone to submit a merge request, rather than allowing them to check in directly to a protected branch. This setting is compatible with workflows like the [GitLab workflow](../../topics/gitlab_flow.md). -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. @@ -125,7 +125,7 @@ like the [GitLab workflow](../../topics/gitlab_flow.md). You can allow everyone with write access to push to the protected branch. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. @@ -153,7 +153,7 @@ Prerequisites: To allow a deploy key to push to a protected branch: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. @@ -172,7 +172,7 @@ protected branches. To protect a new branch and enable force push: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. @@ -184,7 +184,7 @@ To protect a new branch and enable force push: To enable force pushes on branches that are already protected: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle. @@ -200,7 +200,7 @@ For a protected branch, you can require at least one approval by a [Code Owner]( To protect a new branch and enable Code Owner's approval: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. @@ -210,7 +210,7 @@ To protect a new branch and enable Code Owner's approval: To enable Code Owner's approval on branches that are already protected: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle. @@ -242,7 +242,7 @@ for details about the pipelines security model. Users with at least the Maintainer role can manually delete protected branches by using the GitLab web interface: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Branches**. 1. Next to the branch you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, type the branch name. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 870c544cf4c..9b1e862af58 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -97,7 +97,7 @@ Prerequisite: To do this: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Tags**. 1. Next to the tag you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, enter the tag name and select **Yes, delete protected tag**. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index d02609cbdc7..3eb333f5785 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -102,7 +102,7 @@ long Git commands. ### Merge when pipeline succeeds alias -To set up a Git alias for the +To set up a Git alias for the [merge when pipeline succeeds Git push option](#push-options-for-merge-requests): ```shell diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 216d040734d..8b8eba62cce 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -67,7 +67,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | | `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | | `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | -| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the [draft status](merge_requests/drafts.md). | +| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). Use for toggling the draft status ([deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4.) | | `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | | `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. Also, mark both as related. | | `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | @@ -100,7 +100,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | | `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | | `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | -| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4). | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. | | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | | `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | @@ -110,6 +110,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | | `/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. | +| `/timeline <timeline comment> \| <date(YYYY-MM-DD)> <time(HH:MM)>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a timeline event to this incident. For example, `/timeline DB load spiked \| 2022-09-07 09:30`. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4). | | `/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](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3 | | `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | @@ -121,7 +122,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | | `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | -| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4). | +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident).| ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index d3456e086ce..87ea95524fe 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -57,8 +57,6 @@ switch between ascending or descending order, select **Sort order**. ## Create a release -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI. - You can create a release: - [Using a job in your CI/CD pipeline](#creating-a-release-by-using-a-cicd-job). @@ -68,16 +66,16 @@ You can create a release: We recommend creating a release as one of the last steps in your CI/CD pipeline. +### Create a release in the Releases page + Prerequisites: - You must have at least the Developer role for a project. For more information, read [Release permissions](#release-permissions). -### Create a release in the Releases page - To create a release in the Releases page: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases** and select **New release**. 1. From the [**Tag name**](release_fields.md#tag-name) dropdown, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release @@ -99,7 +97,7 @@ To create a release in the Tags page, add release notes to either an existing or To add release notes to a new Git tag: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Tags**. 1. Select **New tag**. 1. Optional. Enter a tag message in the **Message** text box. @@ -109,7 +107,7 @@ To add release notes to a new Git tag: To edit release notes of an existing Git tag: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Tags**. 1. Select **Edit release notes** (**{pencil}**). 1. In the **Release notes** text box, enter the release's description. @@ -124,8 +122,11 @@ You can create a release directly as part of the GitLab CI/CD pipeline by using The release is created only if the job processes without error. If the API returns an error during release creation, the release job fails. -For examples of how you can create a release of your application in the CI/CD pipeline, -see [Release CI/CD examples](release_cicd_examples.md). +Methods for creating a release using a CI/CD job include: + +- [Create a release when a Git tag is created](release_cicd_examples.md#create-a-release-when-a-git-tag-is-created). +- [Create a release when a commit is merged to the default branch](release_cicd_examples.md#create-a-release-when-a-commit-is-merged-to-the-default-branch). +- [Create release metadata in a custom script](release_cicd_examples.md#create-release-metadata-in-a-custom-script). ### Use a custom SSL CA certificate authority @@ -232,7 +233,7 @@ Prerequisites: To delete a release in the UI: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases**. 1. In the top-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. @@ -312,6 +313,7 @@ deploy_to_production: script: deploy_to_prod.sh rules: - if: $CI_DEPLOY_FREEZE == null + environment: production ``` To set a deploy freeze window in the UI, complete these steps: diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md index f1d3e55a707..bfd83a20caf 100644 --- a/doc/user/project/releases/release_cicd_examples.md +++ b/doc/user/project/releases/release_cicd_examples.md @@ -12,9 +12,13 @@ CI/CD pipeline. ## Create a release when a Git tag is created -In this CI/CD example, pushing a Git tag to the repository, or creating a Git tag in the UI triggers -the release. You can use this method if you prefer to create the Git tag manually, and create a -release as a result. +In this CI/CD example, the release is triggered by one of the following events: + +- Pushing a Git tag to the repository. +- Creating a Git tag in the UI. + +You can use this method if you prefer to create the Git tag manually, and create a release as a +result. NOTE: Do not provide Release notes when you create the Git tag in the UI. Providing release notes @@ -40,8 +44,8 @@ release_job: ## Create a release when a commit is merged to the default branch -In this CI/CD example, merging a commit to the default branch triggers the pipeline. You can use -this method if your release workflow does not create a tag manually. +In this CI/CD example, the release is triggered when you merge a commit to the default branch. You +can use this method if your release workflow does not create a tag manually. Key points in the following _extract_ of an example `.gitlab-ci.yml` file: @@ -69,16 +73,75 @@ Environment variables set in `before_script` or `script` are not available for e in the same job. Read more about [potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). +## Create release metadata in a custom script + +In this CI/CD example the release preparation is split into separate jobs for greater flexibility: + +- The `prepare_job` job generates the release metadata. Any image can be used to run the job, + including a custom image. The generated metadata is stored in the variable file `variables.env`. + This metadata is [passed to the downstream job](../../../ci/variables/index.md#pass-an-environment-variable-to-another-job). +- The `release_job` uses the content from the variables file to create a release, using the + metadata passed to it in the variables file. This job must use the + `registry.gitlab.com/gitlab-org/release-cli:latest` image because it contains the release CLI. + +```yaml +prepare_job: + stage: prepare # This stage must run before the release stage + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo "EXTRA_DESCRIPTION=some message" >> variables.env # Generate the EXTRA_DESCRIPTION and TAG environment variables + - echo "TAG=v$(cat VERSION)" >> variables.env # and append to the variables.env file + artifacts: + reports: + dotenv: variables.env # Use artifacts:reports:dotenv to expose the variables to other jobs + +release_job: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + needs: + - job: prepare_job + artifacts: true + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo "running release_job for $TAG" + release: + name: 'Release $TAG' + description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG + tag_name: '$TAG' # variables must be defined elsewhere + ref: '$CI_COMMIT_SHA' # in the pipeline. For example, in the + milestones: # prepare_job + - 'm1' + - 'm2' + - 'm3' + released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. + assets: + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional +``` + ## Skip multiple pipelines when creating a release Creating a release using a CI/CD job could potentially trigger multiple pipelines if the associated tag does not exist already. To understand how this might happen, consider the following workflows: - Tag first, release second: + 1. A tag is created via UI or pushed. 1. A tag pipeline is triggered, and runs `release` job. 1. A release is created. - Release first, tag second: + 1. A pipeline is triggered when commits are pushed or merged to default branch. The pipeline runs `release` job. 1. A release is created. 1. A tag is created. diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index 9e65ab4bc01..90363fca8b0 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -46,7 +46,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av Or from the GitLab Package Registry: ```shell - curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-darwin-amd64" + curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-linux-amd64" ``` 1. Give it permissions to execute: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 3083ca5da3c..d31c64f4640 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -64,7 +64,7 @@ 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**. +1. On the top bar, select **Main 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. @@ -115,7 +115,7 @@ you must either: Administrators of self-managed instances can customize the initial default branch protection 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). @@ -132,7 +132,7 @@ can be overridden on a per-group basis by the group's owner. In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand the **Default branch** section. 1. Clear the **Allow owners to manage default branch protection per group** checkbox. @@ -152,7 +152,7 @@ can be overridden on a per-group basis by the group's owner. In [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) which locks this setting for group owners. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 6da2e5fc7ee..5e5a42a061b 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -59,7 +59,8 @@ To compare branches in a repository:  This feature allows merged branches to be deleted in bulk. Only branches that -have been merged and [are not protected](../../protected_branches.md) are deleted as part of +have been merged into the project's default branch and +[are not protected](../../protected_branches.md) are deleted as part of this operation. It's particularly useful to clean up old branches that were not deleted diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index b2a6c8848ce..d307a6a8580 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -193,10 +193,10 @@ you can sign individual commits manually, or configure Git to default to signed You can review commits for a merge request, or for an entire project: 1. To review commits for a project: - 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Commits**. 1. To review commits for a merge request: - 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**, then select your merge request. 1. Select **Commits**. 1. Identify the commit you want to review. Signed commits show either a **Verified** diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 8e1286548b9..4926cf3812e 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -49,7 +49,7 @@ 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-pick-a-commit) + [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-pick-a-single-commit) from the UI. - **Revert a commit:** [Revert a commit](../merge_requests/revert_changes.md#revert-a-commit) @@ -201,6 +201,14 @@ To render an OpenAPI file: ## Repository size +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368150) in GitLab 15.3, feature flags `gitaly_revlist_for_repo_size` and `gitaly_catfile_repo_size` for alternative repository size calculations. + +FLAG: +On self-managed GitLab, by default GitLab uses the `du -sk` command to determine the size of a repository. GitLab can use either +`git-rev-list` (enabled with feature flag `gitaly_revlist_for_repo_size`) or `git-cat-file` (enabled with feature flag +`gitaly_catfile_repo_size`) instead. To switch between different calculation methods, ask an administrator to +[enable or disable](../../../administration/feature_flags.md) these feature flags. + The **Project information** page shows the size of all files in the repository. The size is updated, at most, every 15 minutes. The file size includes repository files, artifacts, and LFS. diff --git a/doc/user/project/repository/managing_large_repositories.md b/doc/user/project/repository/managing_large_repositories.md index ba425ae3dc7..d2ca49c118c 100644 --- a/doc/user/project/repository/managing_large_repositories.md +++ b/doc/user/project/repository/managing_large_repositories.md @@ -10,13 +10,13 @@ description: "Documentation on large repositories." GitLab, like any Git based system, is subject to similar performance restraints when it comes to large repositories that size into the gigabytes. -On this page we detail several best practices to improve performance with these large repositories on GitLab. +In the following sections, we detail several best practices for improving performance with these large repositories on GitLab. ## Large File System (LFS) -It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, graphics, etc.) are stored as Large File Storage (LFS) objects. In such setup, the Objects are stored elsewhere, such as in Object Storage, and this can reduce the repository size significantly, thus improving performance. +It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, or graphics) are stored as Large File Storage (LFS) objects. In such setup, the Objects are stored elsewhere, such as in Object Storage, and this can reduce the repository size significantly, thus improving performance. -To analyze if the repository has these sorts of objects, it's recommended to run [`git-sizer`](https://github.com/github/git-sizer) to get a detailed analysis. This tool shows in detail what makes up the repository as well as highlights any areas of concern. +To analyze if the repository has these sorts of objects, it's recommended to run a tool like [`git-sizer`](https://github.com/github/git-sizer) to get a detailed analysis. These tools can show in detail what makes up the repository as well as highlights any areas of concern. If any large objects are found, it's then recommended removing them with tools such as [`git filter-repo`](reducing_the_repo_size_using_git.md). Refer to the [Git LFS documentation for more information](../../../topics/git/lfs/index.md). diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 340d7b48a47..793ca2a5f1f 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -45,7 +45,7 @@ and [pull](pull.md#pull-from-a-remote-repository) mirrors in the upstream GitLab To create the webhook in the downstream instance: 1. Create a [personal access token](../../../profile/personal_access_tokens.md) with `API` scope. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Webhooks**. 1. Add the webhook **URL**, which (in this case) uses the [Pull Mirror API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index b08530c34b3..176461aeba7 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -41,7 +41,7 @@ Prerequisite: - If your mirror connects with `ssh://`, the host key must be detectable on the server, or you must have a local copy of the key. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a **Git repository URL**. For security reasons, the URL to the original @@ -89,7 +89,7 @@ Prerequisite: - You must have at least the Maintainer role for the project. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories** and identify the mirror to update. @@ -141,7 +141,7 @@ When you mirror a repository and select the **SSH public key** as your authentication method, GitLab generates a public key for you. The non-GitLab server needs this key to establish trust with your GitLab repository. To copy your SSH public key: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories**. @@ -249,7 +249,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. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **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/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index d0f2b9a8088..159580dcfa5 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -61,7 +61,7 @@ Prerequisite: with the `repo` scope. If 2FA is enabled, this personal access token serves as your GitHub password. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter the **Git repository URL**. Include the username diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index c00ebf415c9..10bdc54ecee 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -33,7 +33,7 @@ section. To set up push mirroring for an existing project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a repository URL. diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 46a9585604e..90d2fdb89d0 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -36,7 +36,7 @@ Prerequisite: To create global push rules: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Push Rules**. 1. Expand **Push rules**. 1. Set the rule you want. @@ -48,7 +48,7 @@ The push rule of an individual project overrides the global push rule. To override global push rules for a specific project, or to update the rules for an existing project to match new global push rules: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Push rules**. 1. Set the rule you want. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 344c288b607..f209c7ef137 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -46,7 +46,7 @@ To purge files from a GitLab repository: [`git-sizer`](https://github.com/github/git-sizer#getting-started) using a supported package manager or from source. -1. Generate a fresh +1. Generate a fresh [export from the project](../settings/import_export.md#export-a-project-and-its-data) and download it. This project export contains a backup copy of your repository *and* refs we can use to purge files from your repository. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index f32035102bb..bafa2005fdf 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -150,7 +150,7 @@ The templates are inherited. For example, in a project, you can also access temp To use a custom description template with Service Desk: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. [Create a description template](description_templates.md#create-an-issue-template). 1. On the left sidebar, select **Settings > General > Service Desk**. 1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. @@ -164,7 +164,7 @@ this name in the `From` header. The default display name is `GitLab Support Bot` To edit the custom email display name: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General > Service Desk**. 1. Enter a new name in **Email display name**. 1. Select **Save Changes**. @@ -358,9 +358,23 @@ to everyone who can view the project. Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user does not count toward the license limit count. +### Moving a Service Desk issue + +Service Desk issues can be moved like any other issue in GitLab. + +You can move a Service Desk issue the same way you +[move a regular issue](issues/managing_issues.md#move-an-issue) in GitLab. + +If a Service Desk issue is moved to a different project the customer who created the issue stops receiving emails. + ## Troubleshooting Service Desk ### Emails to Service Desk do not create issues Your emails might be ignored because they contain one of the [email headers that GitLab ignores](../../administration/incoming_email.md#rejected-headers). + +### Responses to a Service Desk issue do not generate emails + +Your issue might have been moved to a different project. +Moved Service Desk issues do not retain email participants. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 4eeb7c5ba83..375e4a62b86 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -43,7 +43,7 @@ Prerequisites: To export a project and its data, follow these steps: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Advanced**. 1. Select **Export project**. @@ -57,13 +57,34 @@ moved to your configured `uploads_directory`. Every 24 hours, a worker deletes t ### Items that are exported -The following items are exported: +The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) +file lists the items exported and imported when migrating projects using file exports. View this file in the branch +for your version of GitLab to see the list of items relevant to you. For example, +[`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml). + +Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and +[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. + +Items that are exported include: - Project and wiki repositories - Project uploads - Project configuration, excluding integrations -- Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, time - tracking, and other project entities +- Issues + - Issue comments + - Issue resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) +- Merge requests + - Merge request diffs + - Merge request comments + - Merge request resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Merge request multiple assignees ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request reviewers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request approvers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) +- Labels +- Milestones +- Snippets +- Time tracking and other project entities - Design Management files and data - LFS objects - Issue boards @@ -73,7 +94,7 @@ The following items are exported: - Group members are exported as project members, as long as the user has the Maintainer role in the exported project's group, or is an administrator -The following items are **not** exported: +Items that are **not** exported include: - [Child pipeline history](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) - Build traces and artifacts @@ -82,20 +103,11 @@ The following items are **not** exported: - Pipeline triggers - Webhooks - Any encrypted tokens -- Merge Request Approvers and [the number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) +- [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) - Repository size limits - Deploy keys allowed to push to protected branches - Secure Files -These content rules also apply to creating projects from templates on the -[group](../../group/custom_project_templates.md) -or [instance](../../admin_area/custom_project_templates.md) -levels, because the same export and import mechanisms are used. - -NOTE: -For more details on the specific data persisted in a project export, see the -[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file. - ## Import a project and its data > Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. @@ -166,7 +178,8 @@ Imported users can be mapped by their public email addresses on self-managed ins - Public email addresses are not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) for mapping to work correctly. - For contributions to be mapped correctly, users must be an existing member of the namespace, - or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues that are owned by the importer. + or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original + author and the merge requests, notes, or issues that are owned by the importer. - Imported users are set as [direct members](../members/index.md) in the imported project. @@ -403,5 +416,5 @@ Error adding importer user to Project members. Validation failed: User project bots cannot be added to other groups / projects ``` -To use [Import REST APIs](../../../api/project_import_export.md), +To use [Import REST API](../../../api/project_import_export.md), pass regular user account credentials such as [personal access tokens](../../profile/personal_access_tokens.md). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index b973a0f56d1..5c2118e02cf 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -13,7 +13,7 @@ Use the **Settings** page to manage the configuration options in your [project]( You must have at least the Maintainer role to view project settings. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. To display all settings in a section, select **Expand**. 1. Optional. Use the search box to find a setting. @@ -23,7 +23,7 @@ You must have at least the Maintainer role to view project settings. Use the project general settings to edit your project details. 1. Sign in to GitLab with at least the Maintainer role. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. In the **Project name** text box, enter your project name. 1. In the **Project description** text box, enter your project description. @@ -35,7 +35,7 @@ Use topics to categorize projects and find similar new projects. To assign topics to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings** > **General**. 1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. 1. Select **Save changes**. @@ -51,7 +51,7 @@ requirements or needs additional oversight. The label can optionally apply Group owners can create, edit, and delete compliance frameworks: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings** > **General**. 1. Expand the **Compliance frameworks** section. @@ -170,7 +170,7 @@ include: # Execute individual project's configuration (if project contains .git When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/scan-execution-policies.md), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on the similarities and differences between these features, see -[Enforce scan execution](../../application_security/#enforce-scan-execution). +[Enforce scan execution](../../application_security/index.md#enforce-scan-execution). ### Ensure compliance jobs are always run @@ -214,10 +214,10 @@ Compliance pipelines start on the run of _every_ pipeline in a relevant project. triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. Therefore, in projects with compliance frameworks, we recommend replacing -[parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md) with the following: +[parent-child pipelines](../../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines) with the following: - Direct [`include`](../../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. -- Child pipelines placed in another project that are run using the [trigger API](../../../ci/triggers/) rather than the parent-child +- Child pipelines placed in another project that are run using the [trigger API](../../../ci/triggers/index.md) rather than the parent-child pipeline feature. This alternative ensures the compliance pipeline does not re-start the parent pipeline. @@ -226,7 +226,7 @@ This alternative ensures the compliance pipeline does not re-start the parent pi To configure visibility, features, and permissions for a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility, project features, permissions** section. 1. To change the project visibility, select the dropdown list. If you select to **Public**, you limit access to some features to **Only Project Members**. @@ -241,17 +241,17 @@ Use the toggles to enable or disable features in the project. | 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](#configure-merge-request-settings-for-a-project). | +| **Repository** | ✓ | Enables [repository](../repository/index.md) functionality | +| **Merge requests** | ✓ | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). | | **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/). | +| **Container Registry** | | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. | +| **Analytics** | ✓ | Enables [analytics](../../analytics/index.md). | | **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/). | +| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/index.md). | | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | | **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | | **Operations** | ✓ | Control access to Operations-related features, including [Operations Dashboard](../../../operations/index.md), [Environments and Deployments](../../../ci/environments/index.md), [Feature Flags](../../../operations/feature_flags.md). | @@ -286,7 +286,7 @@ In some environments, users can submit a [CVE identifier request](../../applicat To disable the CVE identifier request option in issues in your project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility, project features, permissions** section. 1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. @@ -298,7 +298,7 @@ Prerequisites: - You must be an Owner of the project to disable email notifications related to the project. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility, project features, permissions** section. 1. Clear the **Disable email notifications** checkbox. @@ -339,7 +339,7 @@ other features are read-only. Archived projects are also hidden from project lis To archive a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Advanced**. 1. In the **Archive project** section, select **Archive project**. @@ -355,7 +355,7 @@ Prerequisites: - To unarchive a project, you must be an administrator or a project Owner. 1. Find the archived project. - 1. On the top bar, select **Menu > Project**. + 1. On the top bar, select **Main menu > Projects > View all projects**. 1. Select **Explore projects**. 1. In the **Sort projects** dropdown list, select **Show archived projects**. 1. In the **Filter by name** field, enter the project name. @@ -380,7 +380,7 @@ When you change the repository path, users may experience issues if they push to To rename a repository: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Change path** text box, edit the path. @@ -402,7 +402,7 @@ Prerequisites: To transfer a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Advanced**. 1. Under **Transfer project**, choose the namespace to transfer the project to. @@ -420,7 +420,7 @@ to move any project to any namespace. When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free, the following paid feature data is deleted: - [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked -- [Pipeline subscriptions](../../../ci/pipelines/multi_project_pipelines.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) +- [Pipeline subscriptions](../../../ci/pipelines/index.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) and [test cases](../../../ci/test_cases/index.md) are deleted. ## Delete a project @@ -433,7 +433,7 @@ Prerequisite: To delete a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Advanced**. 1. In the "Delete project" section, select **Delete project**. @@ -472,7 +472,7 @@ Prerequisites: To immediately delete a project marked for deletion: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Advanced**. 1. In the "Permanently delete project" section, select **Delete project**. @@ -504,7 +504,7 @@ To restore the fork relationship, [use the API](../../../api/projects.md#create- To remove a fork relationship: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Advanced**. 1. In the **Remove fork relationship** section, select **Remove fork relationship**. diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 77a53874777..c9c5efce9b1 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -27,6 +27,13 @@ and [personal access tokens](../../profile/personal_access_tokens.md). In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. +WARNING: +The ability to create project access tokens without expiry was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and is planned for removal in GitLab +16.0. When this ability is removed, existing project access tokens without an expiry are planned to have an expiry added. +The automatic adding of an expiry occurs on GitLab.com during the 16.0 milestone. The automatic adding of an expiry +occurs on self-managed instances when they are upgraded to GitLab 16.0. This change is a breaking change. + You can use project access tokens: - On GitLab SaaS if you have the Premium license tier or higher. Project access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). @@ -43,11 +50,12 @@ configured for personal access tokens. ## Create a project access token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days and default role of Guest is populated in the UI. To create a project access token: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Optional. Enter an expiry date for the token. The token expires on that date at midnight UTC. An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. @@ -62,7 +70,7 @@ A project access token is displayed. Save the project access token somewhere saf To revoke a project access token: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Access Tokens**. 1. Next to the project access token to revoke, select **Revoke**. @@ -85,7 +93,7 @@ The scope determines the actions you can perform when you authenticate with a pr To enable or disable project access token creation for all projects in a top-level group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Allow project and group access token creation**. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 971ecf66a3c..522ec962e53 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -170,7 +170,7 @@ The following time units are available: 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**. +1. On the top bar, select **Main 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/index.md b/doc/user/project/web_ide/index.md index 5a4e300a210..2a197c733cf 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -260,7 +260,7 @@ 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**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Scroll to **Web IDE** and select **Expand**:  diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index a3ba5789d39..03838a62d59 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -29,7 +29,7 @@ and higher can edit group wikis. Group wiki repositories can be moved using the To access a group wiki: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. To display the wiki, either: - On the left sidebar, select **Wiki**. - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> @@ -69,7 +69,7 @@ can enable or disable a group wiki through the group settings. To open group settings: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. Scroll to **Wiki** and select one of these options: diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index c7f675417bb..b8924c33b13 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -31,7 +31,7 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se To access a project wiki: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. To display the wiki, either: - On the left sidebar, select **Wiki**. - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> @@ -61,7 +61,7 @@ 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. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. @@ -79,7 +79,7 @@ to be used as your wiki's home page. To create it: Users with at least the Developer role can create new wiki pages: -1. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. @@ -142,7 +142,7 @@ may not be able to check out the wiki locally afterward. You need at least the Developer role to edit a wiki page: -1. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. @@ -161,7 +161,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). You need at least the Developer role to delete a wiki page: -1. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. @@ -174,7 +174,7 @@ You need at least the Developer role to delete a wiki page: You need at least the Developer role to move a wiki page: -1. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. @@ -200,7 +200,7 @@ The history page shows: To view the changes for a wiki page: -1. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. @@ -213,7 +213,7 @@ To view the changes for a wiki page: You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. @@ -246,7 +246,7 @@ You need at least the Developer role to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. @@ -284,7 +284,7 @@ You can disable group wikis from the [group settings](group.md#configure-group-w To add a link to an external wiki from a project's left sidebar: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. @@ -300,7 +300,7 @@ To hide the internal wiki from the sidebar, [disable the project's wiki](#disabl To hide the link to an external wiki: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. In the **Enable integration** section, clear the **Active** checkbox. @@ -310,7 +310,7 @@ To hide the link to an external wiki: To disable a project's internal wiki: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Go to your project and select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll down to find **Wiki** and toggle it off (in gray). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 2501fa8b45c..e58bf5aa557 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -11,22 +11,9 @@ code are saved in projects, and most features are in the scope of projects. ## View projects -To explore projects: +To view projects, on the top bar, select **Main menu > Projects > View all projects**. -1. On the top bar, select **Menu > Projects**. -1. Select **Explore projects**. - -The **Projects** page shows a list of projects, sorted by last updated date. - -- To view projects with the most [stars](#star-a-project), select **Most stars**. -- To view projects with the largest number of comments in the past month, select **Trending**. - -NOTE: -The **Explore projects** tab is visible to unauthenticated users unless the -[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted. Then the tab is visible only to signed-in users. - -### Who can view the **Projects** page +### Who can view the Projects page When you select a project, the project landing page shows the project contents. @@ -53,11 +40,16 @@ visit the `/projects/:id` URL in your browser or other tool accessing the projec To explore project topics: -1. On the top bar, select **Menu > Projects**. -1. Select **Explore topics**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. Select the **Explore topics** tab. +1. To view projects associated with a topic, select a topic. + +The **Explore topics** tab shows a list of topics sorted by the number of associated projects. -The **Projects** page shows list of topics sorted by the number of associated projects. -To view projects associated with a topic, select a topic from the list. +NOTE: +The **Explore projects** tab is visible to unauthenticated users unless the +[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) +is restricted. Then the tab is visible only to signed-in users. You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). @@ -68,8 +60,9 @@ If you're an instance administrator, you can administer all project topics from To create a project in GitLab: -1. On the top bar, select **Menu > Project > Create new project**. -1. On the **Create new project** page, choose if you want to: +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select an option: - Create a [blank project](#create-a-blank-project). - Create a project from a: - [built-in template](#create-a-project-from-a-built-in-template). @@ -88,7 +81,8 @@ To create a project in GitLab: To create a blank project: -1. On the top bar, select **Menu > Projects > Create new project**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, enter the name of your project. You cannot use special characters at @@ -119,7 +113,8 @@ Anyone can [contribute a built-in template](../../development/project_templates. To create a project from a built-in template: -1. On the top bar, select **Menu > Projects > Create new project**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. From the list of templates: @@ -145,7 +140,8 @@ Custom project templates are available at: - The [instance-level](../../user/admin_area/custom_project_templates.md) - The [group-level](../../user/group/custom_project_templates.md) -1. On the top bar, select **Menu > Projects > Create new project**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create from template**. 1. Select the **Instance** or **Group** tab. 1. From the list of templates: @@ -171,7 +167,8 @@ HIPAA Audit Protocol published by the U.S Department of Health and Human Service To create a project from the HIPAA Audit Protocol template: -1. On the top bar, select **Menu > Projects > Create new project**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. Locate the **HIPAA Audit Protocol** template: @@ -210,9 +207,7 @@ Prerequisites: [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). - You must have permission to add new projects to a namespace. To check if you have permission: - 1. On the top bar, select **Menu > Projects**. - 1. Select **Groups**. - 1. Select a group. + 1. On the top bar, select **Main menu > Groups** and find your group. 1. Confirm that **New project** is visible in the upper right corner. Contact your GitLab administrator if you require permission. @@ -258,15 +253,13 @@ You can add a star to projects you use frequently to make them easier to find. To add a star to a project: -1. On the top bar, select **Menu > Projects**. -1. Select **Your projects** or **Explore projects**. -1. Select a project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. In the upper right corner of the page, select **Star**. ## View starred projects -1. On the top bar, select **Menu > Projects**. -1. Select **Starred projects**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. Select the **Starred projects** tab. 1. GitLab displays information about your starred projects, including: - Project description, including name, description, and icon. @@ -284,8 +277,8 @@ called `my-project` under your username, the project is created at `https://gitl To view your personal projects: -1. On the top bar, select **Menu > Projects > Your Projects**. -1. Under **Your projects**, select **Personal**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. In the **Your projects** tab, select **Personal**. ## Delete a project @@ -294,9 +287,7 @@ you can [enable delayed project removal](../group/manage.md#enable-delayed-proje To delete a project: -1. On the top bar, select **Menu > Projects**. -1. Select **Your projects** or **Explore projects**. -1. Select a project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Scroll down to the **Delete project** section. @@ -315,7 +306,7 @@ projects within that group are not deleted immediately, but only after a delay. To view a list of all projects that are pending deletion: -1. On the top bar, select **Menu > Projects > Explore projects**. +1. On the top bar, select **Main menu > Projects > View all projects**. 1. Based on your GitLab version: - GitLab 14.6 and later: select the **Pending deletion** tab. - GitLab 14.5 and earlier: select the **Deleted projects** tab. @@ -330,9 +321,7 @@ Each project in the list shows: To view the activity of a project: -1. On the top bar, select **Menu > Projects**. -1. Select **Your projects** or **Explore projects**. -1. Select a project. +1. On the top bar, select **Main menu > Projects** and find your project.. 1. On the left sidebar, select **Project information > Activity**. 1. Select a tab to view the type of project activity. @@ -340,7 +329,7 @@ To view the activity of a project: You can search through your projects. -1. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. 1. In **Search your projects**, type the project name. GitLab filters as you type. @@ -366,9 +355,7 @@ member and cannot contribute. To leave a project: -1. On the top bar, select **Menu > Projects**. -1. Select **Your projects** or **Explore projects**. -1. Select a project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Leave project**. The **Leave project** option only displays on the project dashboard when a project is part of a group under a [group namespace](../namespace/index.md). diff --git a/doc/user/public_access.md b/doc/user/public_access.md index d821c1abe47..3accb0f5e3d 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -24,6 +24,8 @@ Public projects can be cloned **without any** authentication over HTTPS. They are listed in the public access directory (`/public`) for all users. +Public groups can have public, internal, or private subgroups. + **Any signed-in user** has the Guest role on the repository. NOTE: @@ -38,6 +40,8 @@ Internal projects can be cloned by any signed-in user except They are also listed in the public access directory (`/public`), but only for signed-in users. +Internal groups can have internal or private subgroups. + Any signed-in users except [external users](permissions.md#external-users) have the Guest role on the repository. @@ -53,13 +57,15 @@ Private projects can only be cloned and viewed by project members (except for gu They appear in the public access directory (`/public`) for project members only. +Private groups can only have private subgroups. + ## Change project visibility Prerequisite: - You must have the Owner role for a project. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Change **Project visibility** to either **Private**, **Internal**, or **Public**. @@ -71,9 +77,9 @@ Prerequisite: - You must have the Owner role for a group. - Subgroups and projects must already have visibility settings that are at least as - restrictive as the new setting for the group. + restrictive as the new setting of the parent group. -1. On the top bar, select **Menu > Groups** and find your project. +1. On the top bar, select **Main menu > Groups** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Naming, visibility**. 1. Under **Visibility level** select either **Private**, **Internal**, or **Public**. diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index 90d6a15901a..bec1a8f3d4c 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -5,60 +5,44 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# GitLab Advanced Search **(PREMIUM)** +# Advanced Search **(PREMIUM)** > Moved to GitLab Premium in 13.9. -Advanced Search uses Elasticsearch for faster, more advanced search across the entire -GitLab instance. +You can use Advanced Search for faster, more efficient search across the entire GitLab +instance. Advanced Search is based on Elasticsearch, a purpose-built full-text search +engine you can horizontally scale to get results in up to a second in most cases. -Use Advanced Search when searching in: +You can find code you want to update in all projects at once to save +maintenance time and promote innersourcing. + +You can use Advanced Search in: - Projects - Issues - Merge requests - Milestones - Users -- Epics (when searching in a group only) +- Epics (in groups only) - Code - Comments - Commits -- Wiki (except [group wikis](../project/wiki/group.md)) - -Advanced Search can be useful in various scenarios: - -- **Faster searches:** - Advanced Search is based on Elasticsearch, which is a purpose-built full - text search engine that can be horizontally scaled so that it can provide - search results in 1-2 seconds in most cases. -- **Code Maintenance:** - Finding all the code that needs to be updated at once across an entire - instance can save time spent maintaining code. - This is especially helpful for organizations with more than 10 active projects. - This can also help build confidence is code refactoring to identify unknown impacts. -- **Promote innersourcing:** - Your company may consist of many different developer teams each of which has - their own group where the various projects are hosted. Some of your applications - may be connected to each other, so your developers need to instantly search - throughout the GitLab instance and find the code they search for. - -## Configuring Advanced Search - -For self-managed GitLab instances, an administrator must -[configure Advanced Search](../../integration/advanced_search/elasticsearch.md). +- Project wikis (not [group wikis](../project/wiki/group.md)) -On GitLab.com, Advanced Search is enabled. +## Configure Advanced Search -## Advanced Search syntax +- On GitLab.com, Advanced Search is enabled for groups with paid subscriptions. +- For self-managed GitLab instances, an administrator must + [configure Advanced Search](../../integration/advanced_search/elasticsearch.md). -See the documentation on [Advanced Search syntax](global_search/advanced_search_syntax.md). +## Syntax -## Search by issue or merge request ID +See [Advanced Search syntax](global_search/advanced_search_syntax.md) for more information. -You can search a specific issue or merge request by its ID with a special prefix. +## Search by ID -- 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) +- To search by issue ID, use the `#` prefix followed by the 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 the `!` prefix followed by the 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)** diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 76a85b55585..41eff28b088 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -44,7 +44,7 @@ search, or choose a specific group or project. To search through code or other documents in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the top bar, in the search field, type the string you want to search for. 1. Press **Enter**. @@ -68,7 +68,7 @@ where the results were found. You can search for a commit SHA. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the top bar, in the search field, type the SHA. If a single result is returned, GitLab redirects to the commit result diff --git a/doc/user/snippets.md b/doc/user/snippets.md index cab18b221c1..f4683414dea 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -23,9 +23,15 @@ GitLab provides two types of snippets: - **Personal snippets**: Created independent of any project. You can set a [visibility level](public_access.md) - for your snippet: public, internal, or private. + for your snippet: public or private. - **Project snippets**: Always related to a specific project. - Project snippets can be visible publicly or to only group members. + Project snippets can be visible publicly, or to only project members. + +NOTE: +From July 2019, the `Internal` visibility setting is disabled for new projects, groups, +and snippets on GitLab.com. Existing snippets using the `Internal` +visibility setting keep this setting. You can read more about the change in the +[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). ## Create snippets @@ -61,10 +67,10 @@ In GitLab versions 13.0 and later, snippets are [versioned by default](#versione To discover all snippets visible to you in GitLab, you can: - **View all snippets visible to you**: On the top bar of your GitLab - instance, select **Menu > Snippets** to view your snippets dashboard. + instance, select **Main menu > Snippets** to view your snippets dashboard. - **Visit [GitLab snippets](https://gitlab.com/dashboard/snippets)** for your snippets on GitLab.com. - **Explore all public snippets**: On the top bar of your GitLab - instance, select **Menu > Snippets** and select **Explore snippets** to view + instance, select **Main menu > Snippets** and select **Explore snippets** to view [all public snippets](https://gitlab.com/explore/snippets). - **View a project's snippets**: In your project, go to **Snippets**. @@ -219,7 +225,7 @@ Prerequisites: To do this task: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Snippets**. 1. Select the snippet you want to report as spam. 1. Select **Submit as spam**. diff --git a/doc/user/ssh.md b/doc/user/ssh.md index 5667890757a..913140d2a01 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -254,6 +254,8 @@ A public and private key are generated. ## Add an SSH key to your GitLab account +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271239) in GitLab 15.4, default expiration date suggested in UI. + To use SSH with GitLab, copy your public key to your GitLab account: 1. Copy the contents of your public key file. You can do this manually or use a script. @@ -289,7 +291,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: `ssh-ed25519`, `sk-ecdsa-sha2-nistp256@openssh.com`, or `sk-ssh-ed25519@openssh.com`, and may end with a comment. 1. In the **Title** box, type a description, like `Work Laptop` or `Home Workstation`. -1. Optional. In the **Expires at** box, select an expiration date. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36243) in GitLab 12.9.) +1. Optional. Update **Expiration date** to modify the default expiration date. In: - GitLab 13.12 and earlier, the expiration date is informational only. It doesn't prevent you from using the key. Administrators can view expiration dates and use them for @@ -419,6 +421,9 @@ as both have a different home directory: You can either copy over the `.ssh/` directory to use the same key, or generate a key in each environment. +If you're running Windows 11 and using [OpenSSH for Windows](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview), ensure the `HOME` +environment variable is set correctly. Otherwise, your private SSH key might not be found. + Alternative tools include: - [Cygwin](https://www.cygwin.com) @@ -468,6 +473,7 @@ This indicates that something is wrong with your SSH setup. - Try to manually register your private SSH key by using `ssh-agent`. - Try to debug the connection by running `ssh -Tv git@example.com`. Replace `example.com` with your GitLab URL. +- Ensure you followed all the instructions in [Use SSH on Microsoft Windows](#use-ssh-on-microsoft-windows). ### `Could not resolve hostname` error diff --git a/doc/user/tasks.md b/doc/user/tasks.md index 16e5c85a354..15abc77ad47 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -10,13 +10,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Creating, editing, and deleting tasks](https://gitlab.com/groups/gitlab-org/-/epics/7169) introduced in GitLab 15.0. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 15.3. -WARNING: -Tasks are in [**Alpha**](../policy/alpha-beta-support.md#alpha-features). - -The following list are the known limitations: +Known limitation: - [Tasks currently cannot be accessed via REST API.](https://gitlab.com/gitlab-org/gitlab/-/issues/368055) -- An issue's tasks can only currently be accessed via a reference within a description, comment, or direct URL (`.../-/work_items/[global_id]`). For the latest updates, check the [Tasks Roadmap](https://gitlab.com/groups/gitlab-org/-/epics/7103). @@ -40,7 +36,7 @@ to work items and adding custom work item types, visit ## View tasks -View tasks in issues, in the **Child items** section. +View tasks in issues, in the **Tasks** section. You can also [filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = task`. @@ -53,7 +49,7 @@ Prerequisites: To create a task: -1. In an issue description, in the **Child items** section, select **Add a task**. +1. In the issue description, in the **Tasks** section, select **Add**. 1. Enter the task title. 1. Select **Create task**. @@ -65,7 +61,7 @@ Prerequisites: To edit a task: -1. In the issue description, in the **Child items** section, select the task you want to edit. +1. In the issue description, in the **Tasks** section, select the task you want to edit. The task window opens. 1. Optional. To edit the title, select it and make your changes. 1. Optional. To edit the description, select the edit icon (**{pencil}**), make your changes, and @@ -83,7 +79,7 @@ It's not possible to connect them again. To remove a task from an issue: -1. In the issue description, in the **Child items** section, next to the task you want to remove, select the options menu (**{ellipsis_v}**). +1. In the issue description, in the **Tasks** section, next to the task you want to remove, select the options menu (**{ellipsis_v}**). 1. Select **Remove task**. ## Delete a task @@ -96,6 +92,75 @@ Prerequisites: To delete a task: -1. In the issue description, in the **Child items** section, select the task you want to edit. +1. In the issue description, in the **Tasks** section, select the task you want to edit. 1. In the task window, in the options menu (**{ellipsis_v}**), select **Delete task**. 1. Select **OK**. + +## Assign users to a task + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334810) in GitLab 15.4. + +To show who is responsible for a task, you can assign users to it. + +Users on GitLab Free can assign one user per task. +Users on GitLab Premium and higher can assign multiple users to a single task. +See also [multiple assignees for issues](project/issues/multiple_assignees_for_issues.md). + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To change the assignee on a task: + +1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. + The task window opens. +1. Next to **Assignees**, select **Add assignees**. +1. From the dropdown list, select the user(s) to add as an assignee. +1. Select any area outside the dropdown list. + +## Set a start and due date + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365399) in GitLab 15.4. + +You can set a [start and due date](project/issues/due_dates.md) on a task. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +You can set start and due dates on a task to show when work should begin and end. + +To set a due date: + +1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. + The task window opens. +1. If the task already has a due date next to **Due date**, select it. Otherwise, select **Add due date**. +1. In the date picker, select the desired due date. + +To set a start date: + +1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. + The task window opens. +1. If the task already has a start date next to **Start date**, select it. Otherwise, select **Add start date**. +1. In the date picker, select the desired due date. + + The due date must be the same or later than the start date. + If you select a start date to be later than the due date, the due date is then changed to the same day. + +## Set task weight **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.3. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +You can set weight on each task to show how much work it needs. +This value is visible only when you view a task. + +To set issue weight of a task: + +1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. + The task window opens. +1. Next to **Weight**, enter a whole, positive number. +1. Select the close icon (**{close}**). diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 5d78b4bb795..828c9a3c4b0 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -32,36 +32,36 @@ To prevent exceeding the namespace storage quota, you can: 1. Reduce storage consumption by following the suggestions in the [Manage Your Storage Usage](#manage-your-storage-usage) section of this page. 1. Apply for [GitLab for Education](https://about.gitlab.com/solutions/education/join/), [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/), or [GitLab for Startups](https://about.gitlab.com/solutions/startups/) if you meet the eligibility requirements. -1. Consider using a [self-managed instance](../subscriptions/self_managed/) of GitLab which does not have these limits on the free tier. +1. Consider using a [self-managed instance](../subscriptions/self_managed/index.md) of GitLab which does not have these limits on the free tier. 1. [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60/year for 10GB of storage. 1. [Start a trial](https://about.gitlab.com/free-trial/) or [upgrade to GitLab Premium or Ultimate](https://about.gitlab.com/pricing) which include higher limits and features that enable growing teams to ship faster without sacrificing on quality. 1. [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) to learn more about your options and ask questions. ### Namespace storage limit enforcement schedule -Storage limits for GitLab SaaS Free tier namespaces will not be enforced prior to 2022-10-19. Storage limits for GitLab SaaS Paid tier namespaces will not be enforced for prior to 2023-02-15. +Storage limits for GitLab SaaS Free tier namespaces will not be enforced prior to 2022-10-19. Storage limits for GitLab SaaS Paid tier namespaces will not be enforced for prior to 2023-02-15. Enforcement will not occur until all storage types are accurately measured, including deduplication of forks for [Git](https://gitlab.com/gitlab-org/gitlab/-/issues/371671) and [LFS](https://gitlab.com/gitlab-org/gitlab/-/issues/370242). -Impacted users are notified via email and in-app notifications at least 60 days prior to enforcement. +Impacted users are notified via email and in-app notifications at least 60 days prior to enforcement. ### Project storage limit -Namespaces on a GitLab SaaS **paid** tier (Premium and Ultimate) have a storage limit on their project repositories. -A project's repository has a storage quota of 10 GB. A namespace has either a namespace-level storage limit or a project-level storage limit, but not both. +Projects on GitLab SaaS have a 10GB storage limit on their Git repository and LFS storage. +Once namespace-level storage limits are enforced, the project limit will be removed. A namespace has either a namespace-level storage limit or a project-level storage limit, but not both. -- Paid tier namespaces have project-level storage limits enforced. -- Free tier namespaces have namespace-level storage limits. - -When a project's repository reaches the quota, the project is locked. You cannot push changes to a locked project. To monitor the size of each +When a project's repository and LFS reaches the quota, the project is locked. You cannot push changes to a locked project. To monitor the size of each repository in a namespace, including a breakdown for each project, you can -[view storage usage](#view-storage-usage). To allow a project's repository to exceed the free quota +[view storage usage](#view-storage-usage). To allow a project's repository and LFS to exceed the free quota you must purchase additional storage. For more details, see [Excess storage usage](#excess-storage-usage). ## View storage usage -You can view storage usage for your project or [namespace](../user/namespace/index.md). +Prerequisites: + +- To view storage usage for a project, you must have at least the Maintainer role for the project or Owner role for the namespace. +- To view storage usage for a namespace, you must have the Owner role for the namespace. 1. Go to your project or namespace: - - For a project, on the top bar, select **Menu > Projects** and find your project. + - For a project, on the top bar, select **Main menu > Projects** and find your project. - For a namespace, enter the URL in your browser's toolbar. 1. From the left sidebar, select **Settings > Usage Quotas**. 1. Select the **Storage** tab. @@ -87,20 +87,20 @@ The following storage usage statistics are available to a maintainer: ## Manage your storage usage -You can use several methods to manage and reduce your usage for some storage types. +To manage your storage, if you are a namespace Owner you can [purchase more storage for the namespace](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). -For more information, see the following pages: +Depending on your role, you can also use the following methods to manage or reduce your storage: -- [Reduce package registry storage](packages/package_registry/reduce_package_registry_storage.md) -- [Reduce dependency proxy storage](packages/dependency_proxy/reduce_dependency_proxy_storage.md) -- [Reduce repository size](project/repository/reducing_the_repo_size_using_git.md) -- [Reduce container registry storage](packages/container_registry/reduce_container_registry_storage.md) -- [Reduce container registry data transfers](packages/container_registry/reduce_container_registry_data_transfer.md) -- [Reduce wiki repository size](../administration/wikis/index.md#reduce-wiki-repository-size) +- [Reduce package registry storage](packages/package_registry/reduce_package_registry_storage.md). +- [Reduce dependency proxy storage](packages/dependency_proxy/reduce_dependency_proxy_storage.md). +- [Reduce repository size](project/repository/reducing_the_repo_size_using_git.md). +- [Reduce container registry storage](packages/container_registry/reduce_container_registry_storage.md). +- [Reduce container registry data transfers](packages/container_registry/reduce_container_registry_data_transfer.md). +- [Reduce wiki repository size](../administration/wikis/index.md#reduce-wiki-repository-size). ## Excess storage usage -Excess storage usage is the amount that a project's repository exceeds the free storage quota. If no +Excess storage usage is the amount that a project's repository and LFS exceeds the free storage quota. If no purchased storage is available the project is locked. You cannot push changes to a locked project. To unlock a project you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) for the namespace. When the purchase is completed, locked projects are automatically unlocked. The @@ -115,7 +115,7 @@ The **Storage** tab of the **Usage Quotas** page warns you of the following: ### Excess storage example -The following example describes an excess storage scenario for namespace _Example Company_: +The following example describes an excess storage scenario for a namespace: | Repository | Storage used | Excess storage | Quota | Status | |------------|--------------|----------------|--------|-------------------| @@ -125,12 +125,12 @@ The following example describes an excess storage scenario for namespace _Exampl | Yellow | 2 GB | 0 GB | 10 GB | Not locked | | **Totals** | **30 GB** | **0 GB** | - | - | -The Red and Green projects are locked because their repositories have reached the quota. In this +The Red and Green projects are locked because their repositories and LFS have reached the quota. In this example, no additional storage has yet been purchased. To unlock the Red and Green projects, 50 GB additional storage is purchased. -Assuming the Green and Red projects' repositories grow past the 10 GB quota, the purchased storage +Assuming the Green and Red projects' repositories and LFS grow past the 10 GB quota, the purchased storage available decreases. All projects remain unlocked because 40 GB purchased storage is available: 50 GB (purchased storage) - 10 GB (total excess storage used). |
